Berry animation performance improvements: LUT and native push_pixels (#24094)

Author: s-hadinger

…ation/anim_examples/old/ocean_waves.anim …animation/anim_examples/ocean_waves.animlib/libesp32/berry_animation/anim_examples/old/ocean_waves.anim renamed to lib/libesp32/berry_animation/anim_examples/ocean_waves.anim lib/libesp32/berry_animation/anim_examples/old/ocean_waves.anim renamed to lib/libesp32/berry_animation/anim_examples/ocean_waves.anim

@@ -14,7 +14,7 @@ palette rainbow_with_white = [
 ]
 
 # define a color attribute that cycles over time, cycle is 10 seconds
-color rainbow_rich_color = rich_palette(palette=rainbow_with_white, cycle_period=10s, transition_type=SINE)
+color rainbow_rich_color = rich_palette(palette=rainbow_with_white, cycle_period=0, transition_type=SINE)
 
 # since strip_length is dynamic, we need to map it to a variable
 set strip_len = strip_length()

…ation/anim_examples/old/plasma_wave.anim …animation/anim_examples/plasma_wave.animlib/libesp32/berry_animation/anim_examples/old/plasma_wave.anim renamed to lib/libesp32/berry_animation/anim_examples/plasma_wave.anim lib/libesp32/berry_animation/anim_examples/old/plasma_wave.anim renamed to lib/libesp32/berry_animation/anim_examples/plasma_wave.anim

@@ -14,7 +14,7 @@ palette rainbow_with_white = [
 ]
 
 # define a color attribute that cycles over time, cycle is 10 seconds
-color rainbow_rich_color = rich_palette(palette=rainbow_with_white, cycle_period=10s, transition_type=SINE)
+color rainbow_rich_color = rich_palette(palette=rainbow_with_white, cycle_period=0, transition_type=SINE)
 
 # define a gradient across the whole strip
 animation back_pattern = palette_gradient_animation(color_source = rainbow_rich_color, shift_period = 5s)

lib/libesp32/berry_animation/anim_tutorials/chap_1_32_color_pattern_spatial_osc.anim

@@ -331,7 +331,10 @@ Base interface for all color providers. Inherits from `ValueProvider`.
 
 | Parameter | Type | Default | Constraints | Description |
 |-----------|------|---------|-------------|-------------|
-| *(none)* | - | - | - | Base interface has no parameters |
+| `brightness` | int | 255 | 0-255 | Overall brightness scaling for all colors |
+
+**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)
 
@@ -342,6 +345,7 @@ Returns a single, static color. Inherits from `ColorProvider`.
 | Parameter | Type | Default | Constraints | Description |
 |-----------|------|---------|-------------|-------------|
 | `color` | int | 0xFFFFFFFF | - | The solid color to return |
+| *(inherits brightness from ColorProvider)* | | | | |
 
 #### Usage Examples
 
@@ -370,6 +374,7 @@ Cycles through a palette of colors with brutal switching. Inherits from `ColorPr
 | `cycle_period` | int | 5000 | min: 0 | Cycle time in ms (0 = manual only) |
 | `next` | int | 0 | - | Write 1 to move to next color manually, or any number to go forward or backwards by `n` colors |
 | `palette_size` | int | 3 | read-only | Number of colors in the palette (automatically updated when palette changes) |
+| *(inherits brightness from ColorProvider)* | | | | |
 
 **Note**: The `get_color_for_value()` method accepts values in the 0-255 range for value-based color mapping.
 
@@ -406,7 +411,7 @@ Generates colors from predefined palettes with smooth transitions and profession
 | `palette` | bytes | rainbow palette | - | Palette bytes or predefined palette constant |
 | `cycle_period` | int | 5000 | min: 0 | Cycle time in ms (0 = value-based only) |
 | `transition_type` | int | animation.LINEAR | enum: [animation.LINEAR, animation.SINE] | LINEAR=constant speed, SINE=smooth ease-in/ease-out |
-| `brightness` | int | 255 | 0-255 | Overall brightness scaling |
+| *(inherits brightness from ColorProvider)* | | | | |
 
 #### Available Predefined Palettes
 
@@ -453,10 +458,11 @@ Creates breathing/pulsing color effects by modulating the brightness of a base c
 | Parameter | Type | Default | Constraints | Description |
 |-----------|------|---------|-------------|-------------|
 | `base_color` | int | 0xFFFFFFFF | - | The base color to modulate (32-bit ARGB value) |
-| `min_brightness` | int | 0 | 0-255 | Minimum brightness level |
-| `max_brightness` | int | 255 | 0-255 | Maximum brightness level |
+| `min_brightness` | int | 0 | 0-255 | Minimum brightness level (breathing effect) |
+| `max_brightness` | int | 255 | 0-255 | Maximum brightness level (breathing effect) |
 | `duration` | int | 3000 | min: 1 | Time for one complete breathing cycle in ms |
 | `curve_factor` | int | 2 | 1-5 | Breathing curve shape (1=cosine wave, 2-5=curved breathing with pauses) |
+| *(inherits brightness from ColorProvider)* | | | | Overall brightness scaling applied after breathing effect |
 | *(inherits all OscillatorValueProvider parameters)* | | | | |
 
 **Curve Factor Effects:**
@@ -518,6 +524,7 @@ Combines multiple color providers with blending. Inherits from `ColorProvider`.
 | Parameter | Type | Default | Constraints | Description |
 |-----------|------|---------|-------------|-------------|
 | `blend_mode` | int | 0 | enum: [0,1,2] | 0=overlay, 1=add, 2=multiply |
+| *(inherits brightness from ColorProvider)* | | | | Overall brightness scaling applied to final composite color |
 
 **Factory**: `animation.composite_color(engine)`
 

lib/libesp32/berry_animation/anim_tutorials/chap_1_33_color_pattern_spatial_rotate.anim

@@ -215,6 +215,125 @@ def render(frame, time_ms)
 end
 ```
 
+### Color Provider LUT Optimization
+
+For color providers that perform expensive color calculations (like palette interpolation), the base `ColorProvider` class provides a Lookup Table (LUT) mechanism for caching pre-computed colors:
+
+```berry
+#@ solidify:MyColorProvider,weak
+class MyColorProvider : animation.color_provider
+  # Instance variables (all should start with underscore)
+  var _cached_data    # Your custom cached data
+  
+  def init(engine)
+    super(self).init(engine)  # Initializes _color_lut and _lut_dirty
+    self._cached_data = nil
+  end
+  
+  # Mark LUT as dirty when parameters change
+  def on_param_changed(name, value)
+    super(self).on_param_changed(name, value)
+    if name == "palette" || name == "transition_type"
+      self._lut_dirty = true  # Inherited from ColorProvider
+    end
+  end
+  
+  # Rebuild LUT when needed
+  def _rebuild_color_lut()
+    # Allocate LUT (e.g., 129 entries * 4 bytes = 516 bytes)
+    if self._color_lut == nil
+      self._color_lut = bytes()
+      self._color_lut.resize(129 * 4)
+    end
+    
+    # Pre-compute colors for values 0, 2, 4, ..., 254, 255
+    var i = 0
+    while i < 128
+      var value = i * 2
+      var color = self._compute_color_expensive(value)
+      self._color_lut.set(i * 4, color, 4)
+      i += 1
+    end
+    
+    # Add final entry for value 255
+    var color_255 = self._compute_color_expensive(255)
+    self._color_lut.set(128 * 4, color_255, 4)
+    
+    self._lut_dirty = false
+  end
+  
+  # Update method checks if LUT needs rebuilding
+  def update(time_ms)
+    if self._lut_dirty || self._color_lut == nil
+      self._rebuild_color_lut()
+    end
+    return self.is_running
+  end
+  
+  # Fast color lookup using LUT
+  def get_color_for_value(value, time_ms)
+    # Build LUT if needed (lazy initialization)
+    if self._lut_dirty || self._color_lut == nil
+      self._rebuild_color_lut()
+    end
+    
+    # Map value to LUT index (divide by 2, special case for 255)
+    var lut_index = value >> 1
+    if value >= 255
+      lut_index = 128
+    end
+    
+    # Retrieve pre-computed color from LUT
+    var color = self._color_lut.get(lut_index * 4, 4)
+    
+    # Apply brightness scaling using static method (only if not 255)
+    var brightness = self.brightness
+    if brightness != 255
+      return animation.color_provider.apply_brightness(color, brightness)
+    end
+    
+    return color
+  end
+  
+  # Access LUT from outside (returns bytes() or nil)
+  # Inherited from ColorProvider: get_lut()
+end
+```
+
+**LUT Benefits:**
+- **5-10x speedup** for expensive color calculations
+- **Reduced CPU usage** during rendering
+- **Smooth animations** even with complex color logic
+- **Memory efficient** (typically 516 bytes for 129 entries)
+
+**When to use LUT:**
+- Palette interpolation with binary search
+- Complex color transformations
+- Brightness calculations
+- Any expensive per-pixel color computation
+
+**LUT Guidelines:**
+- Store colors at maximum brightness, apply scaling after lookup
+- Use 2-step resolution (0, 2, 4, ..., 254, 255) to save memory
+- Invalidate LUT when parameters affecting color calculation change
+- Don't invalidate for brightness changes if brightness is applied post-lookup
+
+**Brightness Handling:**
+
+The `ColorProvider` base class includes a `brightness` parameter (0-255, default 255) and a static method for applying brightness scaling:
+
+```berry
+# Static method for brightness scaling (only scales if brightness != 255)
+animation.color_provider.apply_brightness(color, brightness)
+```
+
+**Best Practices:**
+- Store LUT colors at maximum brightness (255)
+- Apply brightness scaling after LUT lookup using the static method
+- Only call the static method if `brightness != 255` to avoid unnecessary overhead
+- For inline performance-critical code, you can inline the brightness calculation instead of calling the static method
+- Brightness changes do NOT invalidate the LUT since brightness is applied after lookup
+
 ## Parameter Access
 
 ### Direct Virtual Member Assignment

lib/libesp32/berry_animation/docs/ANIMATION_CLASS_HIERARCHY.md

@@ -258,14 +258,7 @@ class AnimationEngine
 
   # Output frame buffer to LED strip
   def _output_to_strip()
-    var i = 0
-    var strip_length = self.strip_length
-    var strip = self.strip
-    var pixels = self.frame_buffer.pixels
-    while i < strip_length
-      strip.set_pixel_color(i, pixels.get(i * 4, 4))
-      i += 1
-    end
+    self.strip.push_pixels_buffer_argb(self.frame_buffer.pixels)
     self.strip.show()
   end
 

lib/libesp32/berry_animation/docs/ANIMATION_DEVELOPMENT.md

@@ -139,7 +139,14 @@ class ColorCycleColorProvider : animation.color_provider
       if (idx >= palette_size)    idx = palette_size - 1    end
       if (idx < 0)                idx = 0                   end
       self.current_index = idx
-      return self._get_color_at_index(self.current_index)
+      var color = self._get_color_at_index(self.current_index)
+      
+      # Apply brightness scaling
+      var brightness = self.brightness
+      if brightness != 255
+        return self.apply_brightness(color, brightness)
+      end
+      return color
     end
 
     # Auto-cycle mode: calculate which color to show based on time (brutal switching using integer math)
@@ -151,9 +158,16 @@ class ColorCycleColorProvider : animation.color_provider
       color_index = palette_size - 1
     end
 
-    # Update current state and return the color
+    # Update current state and get the color
     self.current_index = color_index
-    return self._get_color_at_index(color_index)
+    var color = self._get_color_at_index(color_index)
+    
+    # Apply brightness scaling
+    var brightness = self.brightness
+    if brightness != 255
+      return self.apply_brightness(color, brightness)
+    end
+    return color
   end
 
   # Get a color based on a value (maps value to position in cycle)
@@ -170,7 +184,12 @@ class ColorCycleColorProvider : animation.color_provider
     end
 
     if palette_size == 1
-      return self._get_color_at_index(0)  # If only one color, just return it
+      var color = self._get_color_at_index(0)  # If only one color, just return it
+      var brightness = self.brightness
+      if brightness != 255
+        return self.apply_brightness(color, brightness)
+      end
+      return color
     end
 
     # Clamp value to 0-255
@@ -188,7 +207,14 @@ class ColorCycleColorProvider : animation.color_provider
       color_index = palette_size - 1
     end
 
-    return self._get_color_at_index(color_index)
+    var color = self._get_color_at_index(color_index)
+    
+    # Apply brightness scaling
+    var brightness = self.brightness
+    if brightness != 255
+      return self.apply_brightness(color, brightness)
+    end
+    return color
   end
 
   # String representation of the provider

lib/libesp32/berry_animation/src/core/animation_engine.be

@@ -14,6 +14,34 @@
 
 #@ solidify:ColorProvider,weak
 class ColorProvider : animation.value_provider
+  # LUT (Lookup Table) management for color providers
+  # Subclasses can use this to cache pre-computed colors for performance
+  # If a subclass doesn't use a LUT, this remains nil
+  var _color_lut       # Color lookup table cache (bytes() object or nil)
+  var _lut_dirty       # Flag indicating LUT needs rebuilding
+  
+  # Parameter definitions
+  static var PARAMS = animation.enc_params({
+    "brightness": {"min": 0, "max": 255, "default": 255}
+  })
+  
+  # Initialize the color provider
+  #
+  # @param engine: AnimationEngine - Reference to the animation engine (required)
+  def init(engine)
+    super(self).init(engine)
+    self._color_lut = nil
+    self._lut_dirty = true
+  end
+  
+  # Get the color lookup table
+  # Returns the LUT bytes() object if the provider uses one, or nil otherwise
+  #
+  # @return bytes|nil - The LUT bytes object or nil
+  def get_lut()
+    return self._color_lut
+  end
+  
   # Produce a color value for any parameter name
   # This is the main method that subclasses should override
   #
@@ -34,6 +62,31 @@ class ColorProvider : animation.value_provider
     return self.produce_value("color", time_ms)  # Default: use time-based color
   end
 
+  # Static method to apply brightness scaling to a color
+  # Only performs scaling if brightness is not 255 (full brightness)
+  #
+  # @param color: int - Color in ARGB format (0xAARRGGBB)
+  # @param brightness: int - Brightness level (0-255)
+  # @return int - Color with brightness applied
+  static def apply_brightness(color, brightness)
+    # Skip scaling if brightness is full (255)
+    if brightness == 255
+      return color
+    end
+    
+    # Extract RGB components (preserve alpha channel)
+    var r = (color >> 16) & 0xFF
+    var g = (color >> 8) & 0xFF
+    var b = color & 0xFF
+    
+    # Scale each component by brightness
+    r = tasmota.scale_uint(r, 0, 255, 0, brightness)
+    g = tasmota.scale_uint(g, 0, 255, 0, brightness)
+    b = tasmota.scale_uint(b, 0, 255, 0, brightness)
+    
+    # Reconstruct color with scaled brightness (preserve alpha)
+    return (color & 0xFF000000) | (r << 16) | (g << 8) | b
+  end
 
 end