Visual effects (VisualEffect)

Declarative post-processing for EffectScope and hover passes on MouseRegion (hover_effect / hover_effects).

VisualEffect::Gradient

Uses ColorGradient stops (min -> optional center -> max) sampled along EffectAxis in scope-local normalized coordinates (nested scopes remap independently), then blended onto rendered fg/bg like RainbowWave. frequency repeats a sine-eased mirrored ramp (min -> max -> min) across the scope, avoiding hard wrap seams and sharp endpoint troughs; speed shifts the pattern using the renderer phase (0.0 = static).

VisualEffect::Clipped

Restricts an inner effect to a sub-rectangle of the scope and/or a per-cell bitmask:

• bounds: Option<Rect> - clip rect in scope-local coordinates (origin at the effect scope’s top-left). None means the full scope.
• mask: Option<Arc<CellMask>> - optional bitmap; cells where the mask is false skip the inner effect. None means a solid rectangle (bounds, or the full scope when bounds is None).
• inner - another VisualEffect (for example Ripple or Dim).

CellMask stores origin, w, h, and row-major packed bits in Arc<[u64]>. Use CellMask::test_scope_local for scope-local coordinates.

BigText::layout_glyphs builds the same raster as BigText::build_lines() for each line of text, splits it into per-character column bands, then derives each glyph’s ink Rect and CellMask. Exact letter boundaries only when FIGlet leaves at least one fully blank column between glyphs; when letters touch, bands use each character’s standalone FIGlet width (same font and style as the line), scaled to the full ink span - closer than equal slices, though smushed strings can still differ slightly from per-glyph truth. Blank lines advance the vertical offset by one row each; "A\n\nB" inserts a single empty row between blocks. Use a single MouseRegion over the BigText with hit_test / pointer move using those masks so coordinates stay in the shared scope. See the “Letter burst” tab in examples/burst_effects.rs.

Nested Clipped layers compose; each layer’s bounds / mask uses the same scope-local coordinate system as the enclosing EffectScope.