name: color-operations
description: FlatRedBall ColorOperation enum (Add, Modulate, Color, etc.) shared across visual object types. Triggers: ColorOperation, mColorOperation, Sprite.ColorOperation, RenderableIpso, RenderableSkiaObject, AnimationFrame.ColorOperation, UpdateVertexColorsAccordingToAlpha.
Where it lives
ColorOperation enum: Engines/FlatRedBallXNA/FlatRedBall/Graphics/GraphicalEmumerations.cs.
It's not Sprite-specific — consumers include:
| Type | File | Notes |
|---|
Sprite | Engines/FlatRedBallXNA/FlatRedBall/Sprite.cs | Full support, all enum values; setter calls UpdateVertexColorsAccordingToAlpha |
AnimationFrame | Engines/FlatRedBallXNA/FlatRedBall/Graphics/Animation/AnimationFrame.cs | Nullable per-frame override, applied in Sprite.UpdateToAnimationFrame |
RenderableSkiaObject (Gum/SkiaSharp text, SVG) | Engines/SkiaGum/Renderables/RenderableSkiaObject.cs | Hardcoded to Modulate, read-only — does not respect Add/Subtract/etc. |
Renderer global state | Engines/FlatRedBallXNA/FlatRedBall/Graphics/Renderer.cs | Static ColorOperation property drives shader technique selection via _effectManager.GetVertexColorTechniqueFromColorOperation |
Gotchas
- Skia-rendered objects (Text/Gum via
RenderableSkiaObject) silently ignore non-Modulate operations — the IRenderableIpso.ColorOperation getter always returns Modulate, there's no setter. Don't expect Add/Subtract/etc. to work outside the XNA Sprite render path.
- Debug-only platform restriction: on iOS/Android/WinRT, setting
Sprite.ColorOperation to Add, Subtract, InterpolateColor, InverseTexture, Modulate2X, or Modulate4X throws in DEBUG builds (Sprite.cs ~line 410) — these ops aren't guaranteed cross-platform.
"AddSigned" is not ColorOperation.AddSubtract. It's a separate legacy string op-code handled only in GraphicalEnumerations.SetColors (GraphicalEmumerations.cs ~line 293), which biases desiredRed/Green/Blue by -127.5 and remaps to plain "Add" — no enum value, no VertexColorPacker involvement.ColorOperation.Texture with a null Texture behaves like ColorOperation.Color (see Renderer.cs ~line 3349, Sprite.cs ~line 256) — a common "why does my untextured sprite still show color" trip-up.Sprite.Red/Green/Blue clamp to [-1, 1], not [0, 1] (Sprite.cs ~line 301-304), and nothing downstream re-clamps before GPU upload. Packing (now VertexColorPacker.Pack, called from SpriteManager.cs ~line 2146) casts the float channel to uint via (uint)(255 * value). A negative float→uint cast here is undefined behavior per ECMA-335 (out-of-range float-to-unsigned conversion is unspecified) and is genuinely runtime-dependent, not just "clamps to 0": on .NET 8/x64 (this repo's actual net8.0 target) it wraps to byte 129; on .NET 10 the same code gives 0. Either way it is NOT a clean subtraction — never rely on negative Red/Green/Blue under ColorOperation.Add to produce predictable output; use ColorOperation.AddSubtract instead (bias/scale-encodes the signed value so it survives the UNORM byte round-trip predictably).
