Berry Animation Framework - Class Hierarchy and Parameters Reference~

This document provides a comprehensive reference for all classes in the Berry Animation Framework that extend ParameterizedObject, including their parameters and factory functions.

Table of Contents~

1. Class Hierarchy
2. Base Classes
3. Value Providers
4. Color Providers
5. Animation Classes
6. Parameter Constraints

Class Hierarchy~

ParameterizedObject (base class with parameter management and playable interface)
├── Animation (unified base class for all visual elements)
│   ├── EngineProxy (combines rendering and orchestration)
│   │   └── (user-defined template animations)
│   ├── SolidAnimation (solid color fill)
│   ├── BeaconAnimation (pulse at specific position)
│   ├── CrenelPositionAnimation (crenel/square wave pattern)
│   ├── BreatheAnimation (breathing effect)
│   ├── PaletteGradientAnimation (gradient patterns with palette colors)
│   │   ├── PaletteMeterAnimation (meter/bar patterns)
│   │   └── GradientMeterAnimation (VU meter with gradient colors and peak hold)
│   ├── CometAnimation (moving comet with tail)
│   ├── FireAnimation (realistic fire effect)
│   ├── TwinkleAnimation (twinkling stars effect)
│   ├── GradientAnimation (color gradients)
│   ├── NoiseAnimation (Perlin noise patterns)
│   ├── WaveAnimation (wave motion effects)
│   └── RichPaletteAnimation (smooth palette transitions)
├── SequenceManager (orchestrates animation sequences)
└── ValueProvider (dynamic value generation)
    ├── StaticValueProvider (wraps static values)
    ├── StripLengthProvider (provides LED strip length)
    ├── IterationNumberProvider (provides sequence iteration number)
    ├── OscillatorValueProvider (oscillating values with waveforms)
    ├── ClosureValueProvider (computed values, internal use only)
    └── ColorProvider (dynamic color generation)
        ├── StaticColorProvider (solid color)
        ├── ColorCycleColorProvider (cycles through palette)
        ├── RichPaletteColorProvider (smooth palette transitions)
        ├── BreatheColorProvider (breathing color effect)
        └── CompositeColorProvider (blends multiple colors)

Base Classes~

ParameterizedObject~

Base class for all parameterized objects in the framework. Provides parameter management with validation, storage, and retrieval, as well as the playable interface for lifecycle management (start/stop/update).

This unified base class enables: - Consistent parameter handling across all framework objects - Unified engine management (animations and sequences treated uniformly) - Hybrid objects that combine rendering and orchestration - Consistent lifecycle management (start/stop/update)

Key Methods: - start(time_ms) - Start the object at a specific time - stop() - Stop the object - update(time_ms) - Update object state based on current time (no return value)

Factory: N/A (base class)

Animation~

Unified base class for all visual elements. Inherits from ParameterizedObject.

Special Behavior: Setting is_running = true/false starts/stops the animation.

Timing Behavior: The start() method only resets the time origin if the animation was already started previously (i.e., self.start_time is not nil). The first actual rendering tick occurs in update() or render() methods, which initialize start_time on first call.

Factory: animation.animation(engine)

EngineProxy~

A specialized animation class that combines rendering and orchestration capabilities. Extends Animation and can contain child animations and sequences. Inherits from Animation.

Key Features: - Can render visual content like a regular animation - Can orchestrate sub-animations and sequences using add() - Enables complex composite effects - Used as base class for template animations

Child Management: - add(obj) - Adds a child animation or sequence - remove(obj) - Removes a child - Children are automatically started/stopped with parent - Children are rendered in priority order (higher priority on top)

Use Cases: - Composite effects combining multiple animations - Template animations with parameters - Complex patterns with timing control - Reusable animation components

Factory: animation.engine_proxy(engine)

Template Animations~

Template animations are user-defined classes that extend EngineProxy, created using the DSL's template animation syntax. They provide reusable, parameterized animation patterns.

DSL Definition:

template animation shutter_effect {
  param colors type palette nillable true
  param duration type time min 0 max 3600 default 5 nillable false

  # Animation definition with sequences, colors, etc.
  # Parameters accessed as self.colors, self.duration
}

Generated Class Structure:

class shutter_effect_animation : animation.engine_proxy
  static var PARAMS = animation.enc_params({
    "colors": {"type": "palette", "nillable": true},
    "duration": {"type": "time", "min": 0, "max": 3600, "default": 5, "nillable": false}
  })

  def init(engine)
    super(self).init(engine)
    # Generated code with self.colors and self.duration references
    # Uses self.add() for sub-animations and sequences
  end
end

Parameter Constraints: Template animation parameters support all standard constraints: - type - Parameter type (palette, time, int, color, etc.) - min - Minimum value (for numeric types) - max - Maximum value (for numeric types) - default - Default value - nillable - Whether parameter can be nil (true/false)

Implicit Parameters: Template animations automatically inherit parameters from the EngineProxy class hierarchy without explicit declaration: - id (string, default: "animation") - Animation name - priority (int, default: 10) - Rendering priority - duration (int, default: 0) - Animation duration in milliseconds - loop (bool, default: false) - Whether animation loops - opacity (int, default: 255) - Animation opacity (0-255) - color (int, default: 0) - Base color value - is_running (bool, default: false) - Running state

These parameters can be used directly in template animation bodies without declaration:

template animation fade_effect {
  param colors type palette

  # 'duration' is implicit - no need to declare
  set oscillator = sawtooth(min_value=0, max_value=255, duration=duration)

  color col = color_cycle(colors=colors, period=0)
  animation test = solid(color=col)
  test.opacity = oscillator  # 'opacity' is also implicit

  run test
}

Usage:

# Create instance with parameters
palette rainbow = [red, orange, yellow, green, blue]
animation my_shutter = shutter_effect(colors=rainbow, duration=2s)
run my_shutter

Key Differences from Regular Animations: - Defined in DSL, not Berry code - Parameters accessed as self.<param> instead of direct variables - Uses self.add() for composition - Can be instantiated multiple times with different parameters - Automatically registered as animation constructors

Factory: User-defined (e.g., shutter_effect(engine))

Value Providers~

Value providers generate dynamic values over time for use as animation parameters.

ValueProvider~

Base interface for all value providers. Inherits from ParameterizedObject.

Timing Behavior: For value providers, start() is typically not called because instances can be embedded in closures. Value providers consider the first call to produce_value() as the start of their internal time reference. The start() method only resets the time origin if the provider was already started previously (i.e., self.start_time is not nil).

Update Method: The update(time_ms) method does not return any value. Subclasses should check self.is_running to determine if the object is still active.

Factory: N/A (base interface)

StaticValueProvider~

Wraps static values to provide ValueProvider interface. Inherits from ValueProvider.

Factory: animation.static_value(engine)

StripLengthProvider~

Provides access to the LED strip length as a dynamic value. Inherits from ValueProvider.

Usage: Returns the 1D length of the LED strip in pixels. Useful for animations that need to know the strip dimensions for positioning, scaling, or boundary calculations.

Factory: animation.strip_length(engine)

OscillatorValueProvider~

Generates oscillating values using various waveforms. Inherits from ValueProvider.

Waveform Constants: - 1 (SAWTOOTH) - Linear ramp from min to max - 2 (TRIANGLE) - Linear ramp from min to max and back - 3 (SQUARE) - Square wave alternating between min and max - 4 (COSINE) - Smooth cosine wave - 5 (SINE) - Pure sine wave - 6 (EASE_IN) - Quadratic acceleration - 7 (EASE_OUT) - Quadratic deceleration - 8 (ELASTIC) - Spring-like overshoot and oscillation - 9 (BOUNCE) - Ball-like bouncing with decreasing amplitude

Timing Behavior: The start_time is initialized on the first call to produce_value(). The start() method only resets the time origin if the oscillator was already started previously (i.e., self.start_time is not nil).

Factories: animation.ramp(engine), animation.sawtooth(engine), animation.linear(engine), animation.triangle(engine), animation.smooth(engine), animation.sine_osc(engine), animation.cosine_osc(engine), animation.square(engine), animation.ease_in(engine), animation.ease_out(engine), animation.elastic(engine), animation.bounce(engine), animation.oscillator_value(engine)

See Also: Oscillation Patterns - Visual examples and usage patterns for oscillation waveforms

ClosureValueProvider~

⚠️ INTERNAL USE ONLY - NOT FOR DIRECT USE

Wraps a closure/function as a value provider for internal transpiler use. This class is used internally by the DSL transpiler to handle computed values and should not be used directly by users.

Internal Usage: This provider is automatically created by the DSL transpiler when it encounters computed expressions or arithmetic operations involving value providers. The closure is called with (self, param_name, time_ms) parameters.

Mathematical Helper Methods~

The ClosureValueProvider includes built-in mathematical helper methods that can be used within closures for computed values:

Mathematical Method Notes:

• Integer Handling: sqrt() treats integers in 0-255 range as normalized values (255 = 1.0)
• Angle Range: sin() and cos() use 0-255 input range (0-360 degrees)
• Output Range: Trigonometric functions return -255 to 255 (mapped from -1.0 to 1.0)
• Cosine Behavior: Matches oscillator COSINE waveform (starts at minimum, not maximum)
• Scale Function: Uses tasmota.scale_int() for efficient integer scaling

Closure Signature~

Closures used with ClosureValueProvider must follow this signature:

def closure_func(engine, param_name, time_ms)
  # engine: AnimationEngine reference
  # param_name: Name of the parameter being computed
  # time_ms: Current time in milliseconds
  return computed_value
end

Usage in Computed Values~

These methods are automatically available in DSL computed expressions:

# Example: Dynamic brightness based on strip position
set strip_len = strip_length()
animation pulse = pulsating_animation(
  color=red
  brightness=strip_len / 4 + 50    # Uses built-in arithmetic
)

# Complex mathematical expressions are automatically wrapped in closures
# that have access to all mathematical helper methods

Factory: animation.closure_value(engine) (internal use only)

Note: Users should not create ClosureValueProvider instances directly. Instead, use the DSL's computed value syntax which automatically creates these providers as needed.

Color Providers~

Color providers generate dynamic colors over time, extending ValueProvider for color-specific functionality.

ColorProvider~

Base interface for all color providers. Inherits from ValueProvider.

Static Methods: - apply_brightness(color, brightness) - Applies brightness scaling to a color (ARGB format). Only performs scaling if brightness is not 255 (full brightness). This is a static utility method that can be called without an instance.

Factory: N/A (base interface)

StaticColorProvider~

Returns a single, static color. Inherits from ColorProvider.

Usage Examples~

# Using predefined colors
color static_red = solid(color=red)
color static_blue = solid(color=blue)

# Using hex colors
color static_orange = solid(color=0xFF8C00)

# Using custom defined colors
color accent = 0xFF6B35
color static_accent = solid(color=accent)

Note: The solid() function is the recommended shorthand for static_color().

ColorCycleColorProvider~

Cycles through a palette of colors with brutal switching. Inherits from ColorProvider.

Note: The get_color_for_value() method accepts values in the 0-255 range for value-based color mapping.

Modes: Auto-cycle (period > 0) or Manual-only (period = 0)

Usage Examples~

# RGB cycle with brutal switching
color rgb_cycle = color_cycle(
  colors=bytes("FF0000FF" "FF00FF00" "FFFF0000"),
  period=4s
)

# Custom warm colors
color warm_cycle = color_cycle(
  colors=bytes("FF4500FF" "FF8C00FF" "FFFF00"),
  period=3s
)

# Mixed colors in AARRGGBB format
color mixed_cycle = color_cycle(
  colors=bytes("FFFF0000" "FF00FF00" "FF0000FF"),
  period=2s
)

RichPaletteColorProvider~

Generates colors from predefined palettes with smooth transitions and professional color schemes. Inherits from ColorProvider.

Available Predefined Palettes~

Usage Examples~

# Rainbow palette with smooth ease-in/ease-out transitions
color rainbow_colors = rich_palette(
  colors=PALETTE_RAINBOW,
  period=5s,
  transition_type=SINE,
  brightness=255
)

# Fire effect with linear (constant speed) transitions
color fire_colors = rich_palette(
  colors=PALETTE_FIRE,
  period=3s,
  transition_type=LINEAR,
  brightness=200
)

BreatheColorProvider~

Creates breathing/pulsing color effects by modulating the brightness of a base color over time. Inherits from ColorProvider.

Curve Factor Effects: - 1: Pure cosine wave (smooth pulsing, equivalent to pulsating_color) - 2: Natural breathing with slight pauses at peaks - 3: More pronounced breathing with longer pauses - 4: Deep breathing with extended pauses - 5: Most pronounced pauses at peaks (dramatic breathing effect)

Usage Examples~

# Natural breathing effect
color breathing_red = breathe_color(
  base_color=red,
  min_brightness=20,
  max_brightness=255,
  duration=4s,
  curve_factor=3
)

# Fast pulsing effect (equivalent to pulsating_color)
color pulse_blue = breathe_color(
  base_color=blue,
  min_brightness=50,
  max_brightness=200,
  duration=1s,
  curve_factor=1
)

# Slow, deep breathing
color deep_breath = breathe_color(
  base_color=purple,
  min_brightness=5,
  max_brightness=255,
  duration=6s,
  curve_factor=4
)

# Using dynamic base color
color rainbow_cycle = color_cycle(colors=bytes("FF0000FF" "FF00FF00" "FFFF0000"), period=5s)
color breathing_rainbow = breathe_color(
  base_color=rainbow_cycle,
  min_brightness=30,
  max_brightness=255,
  duration=3s,
  curve_factor=2
)

Factories: animation.breathe_color(engine), animation.pulsating_color(engine)

Note: The pulsating_color() factory creates a BreatheColorProvider with curve_factor=1 and duration=1000ms for fast pulsing effects.

CompositeColorProvider~

Combines multiple color providers with blending. Inherits from ColorProvider.

Factory: animation.composite_color(engine)

Animation Classes~

All animation classes extend the base Animation class and inherit its parameters.

BreatheAnimation~

Creates a smooth breathing effect with natural breathing curves. Inherits from Animation.

Factory: animation.breathe_animation(engine)

CometAnimation~

Creates a comet effect with a bright head and fading tail. Inherits from Animation.

Factory: animation.comet_animation(engine)

FireAnimation~

Creates a realistic fire effect with flickering flames. Inherits from Animation.

Factory: animation.fire_animation(engine)

GradientAnimation~

Creates smooth color gradients that can be linear or radial. Inherits from Animation.

Factories: animation.gradient_animation(engine), animation.gradient_rainbow_linear(engine), animation.gradient_rainbow_radial(engine), animation.gradient_two_color_linear(engine)

GradientMeterAnimation~

VU meter style animation that displays a gradient-colored bar from the start of the strip up to a configurable level. Includes optional peak hold indicator. Inherits from PaletteGradientAnimation.

Visual Representation~

level=128 (50%), peak at 200
[████████████████--------•-------]
^                        ^
|                        peak indicator (single pixel)
filled gradient area

Usage Examples~

# Simple meter with rainbow gradient
color rainbow = rich_palette()
animation meter = gradient_meter_animation()
meter.color_source = rainbow
meter.level = 128

# Meter with peak hold (1 second)
color fire_colors = rich_palette(colors=PALETTE_FIRE)
animation vu_meter = gradient_meter_animation(peak_hold=1000)
vu_meter.color_source = fire_colors

# Dynamic level from value provider
set audio_level = triangle(min_value=0, max_value=255, period=2s)
animation audio_meter = gradient_meter_animation(peak_hold=500)
audio_meter.color_source = rainbow
audio_meter.level = audio_level

Factory: animation.gradient_meter_animation(engine)

NoiseAnimation~

Creates pseudo-random noise patterns with configurable scale, speed, and fractal complexity. Perfect for organic, natural-looking effects like clouds, fire textures, or abstract patterns. Inherits from Animation.

Noise Characteristics~

Scale Effects: - Low scale (10-30): Large, flowing patterns - Medium scale (40-80): Balanced detail and flow
- High scale (100-200): Fine, detailed textures

Octave Effects: - 1 octave: Smooth, simple patterns - 2 octaves: Added medium-frequency detail - 3+ octaves: Complex, natural-looking textures

Speed Effects: - Static (0): Fixed pattern for backgrounds - Slow (10-40): Gentle, organic movement - Fast (80-200): Dynamic, energetic patterns

Usage Examples~

# Rainbow noise with medium detail
animation rainbow_noise = noise_animation(
  scale=60,
  speed=40,
  octaves=1
)

# Blue fire texture with fractal detail
color blue_fire = 0xFF0066FF
animation blue_texture = noise_animation(
  color=blue_fire,
  scale=120,
  speed=60,
  octaves=3,
  persistence=100
)

# Static cloud pattern
animation cloud_pattern = noise_animation(
  color=white,
  scale=30,
  speed=0,
  octaves=2
)

Common Use Cases~

• Ambient Lighting: Slow, low-scale noise for background ambiance
• Fire Effects: Orange/red colors with medium scale and speed
• Water Effects: Blue/cyan colors with flowing movement
• Cloud Simulation: White/gray colors with large-scale patterns
• Abstract Art: Rainbow colors with high detail and multiple octaves

PulseAnimation~

Creates a pulsing effect oscillating between min and max brightness. Inherits from Animation.

Factory: animation.pulsating_animation(engine)

BeaconAnimation~

Creates a pulse effect at a specific position with optional fade regions. Inherits from Animation.

Visual Pattern~

         pos (1)
           |
           v
           _______
          /       \
  _______/         \____________
         | |     | |
         |2|  3  |2|

Where: 1. pos - Start of the pulse (in pixels) 2. slew_size - Number of pixels to fade from back to fore color (can be 0) 3. beacon_size - Number of pixels of the pulse

The pulse consists of: - Core pulse: Full brightness region of beacon_size pixels - Fade regions: Optional slew_size pixels on each side with gradual fade - Total width: beacon_size + (2 * slew_size) pixels

Parameters~

Pattern Behavior~

• Sharp Pulse (slew_size = 0): Rectangular pulse with hard edges
• Soft Pulse (slew_size > 0): Pulse with smooth fade-in/fade-out regions
• Positioning: pos defines the start of the core pulse region
• Fade Calculation: Linear fade from full brightness to background color
• Boundary Handling: Fade regions are clipped to frame boundaries

Usage Examples~

# Sharp pulse at center
animation sharp_pulse = beacon_animation(
  color=red,
  pos=10,
  beacon_size=3,
  slew_size=0
)

# Soft pulse with fade regions
animation soft_pulse = beacon_animation(
  color=green,
  pos=5,
  beacon_size=2,
  slew_size=3
)
# Total width: 2 + (2 * 3) = 8 pixels

# Spotlight effect
color dark_blue = 0xFF000040
animation spotlight = beacon_animation(
  color=white,
  back_color=dark_blue,
  pos=15,
  beacon_size=1,
  slew_size=5
)

run spotlight

Common Use Cases~

Spotlight Effects:

# Moving spotlight with soft edges
animation moving_spotlight = beacon_animation(
  color=white,
  back_color=0xFF000040,
  beacon_size=1,
  slew_size=5
)
moving_spotlight.pos = triangle(min_value=0, max_value=29, period=3s)

Position Markers:

# Sharp position marker
animation position_marker = beacon_animation(
  color=red,
  pos=15,
  beacon_size=1,
  slew_size=0
)

Breathing Spots:

# Breathing effect at specific position
animation breathing_spot = beacon_animation(
  color=blue,
  pos=10,
  beacon_size=3,
  slew_size=2
)
breathing_spot.opacity = smooth(min_value=50, max_value=255, period=2s)

Factory: animation.beacon_animation(engine)

CrenelPositionAnimation~

Creates a crenel (square wave) pattern with repeating rectangular pulses. Inherits from Animation.

Visual Pattern~

         pos (1)
           |
           v                 (*4)
            ______           ____
           |      |         |
  _________|      |_________|

           |   2  |    3     |

Where: 1. pos - Starting position of the first pulse (in pixels) 2. pulse_size - Width of each pulse (in pixels)
3. low_size - Gap between pulses (in pixels) 4. nb_pulse - Number of pulses (-1 for infinite)

The full period of the pattern is pulse_size + low_size pixels.

Parameters~

Pattern Behavior~

• Infinite Mode (nb_pulse = -1): Pattern repeats continuously across the strip
• Finite Mode (nb_pulse > 0): Shows exactly the specified number of pulses
• Period: Each pattern cycle spans pulse_size + low_size pixels
• Boundary Handling: Pulses are clipped to frame boundaries
• Zero Sizes: pulse_size = 0 produces no output; low_size = 0 creates continuous pulses

Pattern Calculations~

• Period and Positioning: The pattern repeats every pulse_size + low_size pixels
• Optimization: For infinite pulses, the algorithm calculates optimal starting position for efficient rendering
• Boundary Clipping: Pulses are automatically clipped to frame boundaries
• Modulo Arithmetic: Negative positions are handled correctly with modulo arithmetic

Common Use Cases~

Status Indicators:

# Slow blinking pattern for status indication
animation status_indicator = crenel_animation(
  color=green,
  pulse_size=1,
  low_size=9
)

Rhythmic Effects:

# Fast rhythmic pattern
animation rhythm_pattern = crenel_animation(
  color=red,
  pulse_size=2,
  low_size=2
)

Decorative Borders:

# Decorative border pattern
color gold = 0xFFFFD700
animation border_pattern = crenel_animation(
  color=gold,
  pulse_size=3,
  low_size=1,
  nb_pulse=10
)

Progress Indicators:

# Progress bar with limited pulses
animation progress_bar = crenel_animation(
  color=0xFF0080FF,
  pulse_size=2,
  low_size=1,
  nb_pulse=5
)

Integration Features~

• Parameter System: All parameters support dynamic updates with validation
• Method Chaining: Fluent API for configuration (in Berry code)
• Animation Lifecycle: Inherits standard animation lifecycle methods
• Framework Integration: Seamless integration with animation engine
• Testing: Comprehensive test suite covering edge cases and performance

Factory: animation.crenel_animation(engine)

RichPaletteAnimation~

Creates smooth color transitions using rich palette data with direct parameter access. Inherits from Animation.

Special Features: - Direct parameter access (set anim.colors instead of anim.color.colors) - Parameters are automatically forwarded to internal RichPaletteColorProvider - Access to specialized methods via anim.color_provider.method_name()

Factory: animation.rich_palette_animation(engine)

TwinkleAnimation~

Creates a twinkling stars effect with random lights appearing and fading. Inherits from Animation.

Factories: animation.twinkle_animation(engine), animation.twinkle_classic(engine), animation.twinkle_solid(engine), animation.twinkle_rainbow(engine), animation.twinkle_gentle(engine), animation.twinkle_intense(engine)

WaveAnimation~

Creates mathematical waveforms that can move along the LED strip. Perfect for rhythmic patterns, breathing effects, or mathematical visualizations. Inherits from Animation.

Wave Types~

Sine Wave (0): - Characteristics: Smooth, natural oscillation - Best for: Breathing effects, natural rhythms, ambient lighting

Triangle Wave (1): - Characteristics: Linear ramps up and down with sharp peaks - Best for: Scanning effects, linear fades

Square Wave (2): - Characteristics: Sharp on/off transitions - Best for: Strobing, digital effects, alerts

Sawtooth Wave (3): - Characteristics: Gradual rise, instant drop - Best for: Scanning beams, ramp effects

Wave Characteristics~

Frequency Effects: - Low frequency (10-30): Long, flowing waves - Medium frequency (40-80): Balanced wave patterns - High frequency (100-200): Dense, detailed patterns

Amplitude Effects: - Low amplitude (50-100): Subtle intensity variation - Medium amplitude (100-180): Noticeable wave pattern - High amplitude (200-255): Dramatic intensity swings

Usage Examples~

# Rainbow sine wave
animation rainbow_wave = wave_animation(
  wave_type=0,
  frequency=40,
  wave_speed=80,
  amplitude=150
)

# Green breathing effect
animation breathing = wave_animation(
  color=green,
  wave_type=0,
  amplitude=150,
  frequency=20,
  wave_speed=30
)

# Fast square wave strobe
animation strobe = wave_animation(
  color=white,
  wave_type=2,
  frequency=80,
  wave_speed=150
)

Common Use Cases~

• Breathing Effects: Slow sine waves for calming ambiance
• Scanning Beams: Sawtooth waves for radar-like effects
• Strobing: Square waves for attention-getting flashes
• Color Cycling: Rainbow waves for spectrum effects
• Pulse Patterns: Triangle waves for rhythmic pulses

PaletteGradientAnimation~

Creates shifting gradient patterns with palette colors. Inherits from Animation.

Implementation Details: - Uses bytes() buffer for efficient storage of per-pixel values - Color source receives values in 0-255 range via get_color_for_value(value, time_ms) - Buffer automatically resizes when strip length changes - Optimized LUT (Lookup Table) support for color providers

Pattern Generation: - Generates linear gradient values in 0-255 range across the specified spatial period - shift_period: Controls temporal movement - how long it takes for the gradient to shift one full spatial period - 0: Static gradient (no movement) - > 0: Moving gradient with specified period in milliseconds - spatial_period: Controls spatial repetition - how many pixels before the gradient pattern repeats - 0: Gradient spans the full strip length (single gradient across entire strip) - > 0: Gradient repeats every N pixels - phase_shift: Shifts the gradient pattern spatially by a percentage of the spatial period - Each pixel's value calculated using optimized fixed-point arithmetic

Factory: animation.palette_gradient_animation(engine)

PaletteMeterAnimation~

Creates meter/bar patterns based on a value function. Inherits from PaletteGradientAnimation.

Pattern Generation: - Value function signature: value_func(engine, time_ms, self) where: - engine: AnimationEngine reference - time_ms: Elapsed time since animation start - self: Reference to the animation instance - Value function returns value in 0-255 range representing meter level - Pixels within meter range get value 255, others get value 0 - Meter position calculated as: position = tasmota.scale_uint(value, 0, 255, 0, strip_length)

Factory: animation.palette_meter_animation(engine)

Motion Effects~

Motion effects are transformation animations that apply movement, scaling, and distortion to existing animations. They accept any animation as a source and can be chained together for complex effects.

Combining Motion Effects~

Motion effects can be chained to create sophisticated transformations:

# Base animation
animation base_pulse = pulsating_animation(color=blue, period=3s)

# Simple animation composition
animation fire_effect = fire_animation(
  color=fire_colors,
  intensity=180,
  flicker_speed=8
)

animation gradient_wave = gradient_animation(
  color=rainbow_cycle,
  gradient_type=0,
  movement_speed=50
)

# Result: Multiple independent animations
run base_pulse
run fire_effect
run gradient_wave

Performance Considerations~

• Each animation uses approximately 4 bytes per pixel for color storage
• Fire animation includes additional flicker calculations
• Gradient animation requires color interpolation calculations
• Noise animation includes pseudo-random pattern generation
• Consider strip length impact on transformation calculations

Parameter Constraints~

Constraint Types~

Supported Types~

Factory Function Rules~

1. Engine-Only Parameters: All factory functions take ONLY the engine parameter
2. No Redundant Factories: If a factory only calls the constructor, export the class directly
3. Preset Factories: Factory functions should provide useful presets or complex configurations
4. Parameter Assignment: Set parameters via virtual member assignment after creation