feat: Add HueEffect and HueDecorator

[s1r1m1r1]

Description

This PR adds a new
HueEffect
to the Flame effects library. This effect allows animating the hue shift of a component's paint over time.

Checklist

• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Related Issues

[spydon]

Docs and examples are missing, other than that it looks good!

[s1r1m1r1]

⚠️ Performance Warning: Decorators vs. Effects

This PR provides two ways to apply visual transformations: Decorators and Effects. It is crucial to understand their performance profiles:

Decorators (e.g., HueDecorator): This use canvas.saveLayer() to isolate the component's rendering and apply filters.

Pros: Highly flexible; supports complex chaining of multiple effects; works on any custom draw logic.
Cons: Significant performance overhead. Each saveLayer requires an off-screen buffer allocation and a GPU context switch. In high-density benchmarks (100+ sprites), this can be up to 20x slower than direct paint manipulation.

Effects (e.g., HueEffect): These modify the component's Paint(specifically colorFilter) directly.
Pros: Extremely fast. Hardware-accelerated directly in the fragment shader with zero memory allocation overhead.
Cons: Less flexible for complex layering; only works on components that expose a Paint.

Recommendation: Always prefer Effects for simple color/hue shifts on large numbers of units. Use Decorators only when you need complex visual composition or when targeting raw canvas drawing that isn't governed by a single

[spydon]

⚠️ Performance Warning: Decorators vs. Effects

This PR provides two ways to apply visual transformations: Decorators and Effects. It is crucial to understand their performance profiles:

Decorators (e.g., HueDecorator): This use canvas.saveLayer() to isolate the component's rendering and apply filters.

Pros: Highly flexible; supports complex chaining of multiple effects; works on any custom draw logic.
Cons: Significant performance overhead. Each saveLayer requires an off-screen buffer allocation and a GPU context switch. In high-density benchmarks (100+ sprites), this can be up to 20x slower than direct paint manipulation.

Effects (e.g., HueEffect): These modify the component's Paint(specifically colorFilter) directly.
Pros: Extremely fast. Hardware-accelerated directly in the fragment shader with zero memory allocation overhead.
Cons: Less flexible for complex layering; only works on components that expose a Paint.

Recommendation: Always prefer Effects for simple color/hue shifts on large numbers of units. Use Decorators only when you need complex visual composition or when targeting raw canvas drawing that isn't governed by a single

This should be a general comment on decorators in the docs, if it's not already in there.

[spydon]

Thanks for your contribution!