led_strand.hpp

Go to the documentation of this file.

#pragma once
#include "led_profile.hpp"
#include "platform.hpp"
#include <cstddef>
#include <cstdint>
#include <utility>
#include <vector>

 
namespace hitlib {
 
// ============================================================================

class LedStrand {
public:
 
    // ========================================================================

    struct ExpanderPort {
        uint8_t smartPort; 
        uint8_t adiPort;   
    };

    struct BitScrollSegment {
        uint32_t color; 
        uint8_t  width; 
    };

    struct Speed {
        uint8_t  pixels; 
        uint16_t stepMs; 

        constexpr Speed(int pixelsPerStep = 1, uint16_t ms = 0)
            : pixels((uint8_t)pixelsPerStep), stepMs(ms) {}

        static constexpr Speed everyMs(uint16_t ms, uint8_t pixelsPerStep = 1) {
            return Speed(pixelsPerStep, ms);
        }
    };

    using LevelFn = double (*)();

    enum class SpliceRegionAnimKind : uint8_t {
        OFF, SOLID, PULSE, FLASH, FLOW, RAINBOW, TWINKLE, BITSCROLL, GAUGE
    };

    struct GaugeStop {
        double   at;    
        uint32_t color; 
    };

    enum class GaugeStyle : uint8_t {
        HEAT, 
        BAR,  
    };

    enum class GaugeBlend : uint8_t {
        LERP, 
        STEP, 
    };

    struct SpliceRegion {
        uint8_t  start;                                        
        uint8_t  width;                                         
        SpliceRegionAnimKind kind = SpliceRegionAnimKind::OFF;  
        uint32_t color     = 0xFFFFFF; 
        uint32_t color2    = 0x0000FF; 
        uint32_t bgColor   = 0x000000; 
        uint8_t  runLength = 5;        
        Speed    speed     = 1;        
        uint32_t onMs      = 250;      
        uint32_t offMs     = 250;      
        bool     seamless  = true;     
        bool     invert    = false;
 
        // ---- TWINKLE only ----

        std::vector<uint32_t> palette;
        uint8_t densityPct = 30;  
        uint8_t fadeStep   = 16;  
 
        // ---- BITSCROLL only ----
 
        uint8_t segmentWidth = 3;    
        uint8_t spacing      = 5;    
        bool    repeating    = true; 
 
        // ---- GAUGE only, ignored by every other kind ----

        LevelFn read = nullptr;
        double  emptyAt = 0.0;    
        double  fullAt  = 100.0;  
        bool    wrap    = false;  
        uint8_t smoothing = 0;    
        GaugeStyle style = GaugeStyle::HEAT; 
        GaugeBlend blend = GaugeBlend::LERP; 
        std::vector<GaugeStop> stops;
    };

    struct MusicTrack {
        const uint8_t* samples;    
        uint16_t       frameCount; 
        uint16_t       frameMs;    
    };
 
    // ========================================================================
    // Custom animations (Compositions)
    // ========================================================================

 
    static constexpr uint8_t MAX_LAYERS       = 8;  
    static constexpr uint8_t MAX_DRIVERS      = 8;  
    static constexpr uint8_t MAX_BINDINGS     = 4;  
    static constexpr uint8_t CURVE_POINTS     = 17; 

    enum class LayerKind : uint8_t {
        OFF, SOLID, PULSE, FLASH, FLOW, RAINBOW, TWINKLE, BITSCROLL, GAUGE, METER, FRAMES
    };

    enum class LayerBlend : uint8_t {
        OVER,     
        KEY,      
        ADD,      
        SCREEN,   
        MULTIPLY, 
        MASK,     
    };

    enum class DriverKind : uint8_t {
        CONSTANT, 
        SENSOR,   
        MUSIC,    
        LFO,      
    };
 
    enum class LfoShape : uint8_t { TRIANGLE, SAW, RAMP_DOWN, SQUARE, SINE };

    enum class LayerParam : uint8_t {
        NONE, OPACITY, SPEED, RUN_LENGTH, LEVEL, START, WIDTH, DENSITY, MIX
    };

    struct LayerSpan {
        uint8_t start;   
        uint8_t width;   
        uint8_t stride;
        bool    continuous;
    };

    struct LayerMix { LayerBlend blend; uint8_t opacity; };

    struct Binding {
        LayerParam     param;   
        uint8_t        driver;  
        int16_t        atZero;
        int16_t        atFull;
        const uint8_t* curve;   
    };
 
    struct LayerPaint  { uint32_t color; uint32_t color2; uint32_t bgColor; };
    struct LayerMotion { uint8_t runLength; Speed speed; bool invert; bool bounce; bool seamless; };
    struct LayerFlash  { uint32_t onMs; uint32_t offMs; };

    struct LayerTime {
        uint32_t loopMs;     
        uint32_t startMs;
        uint32_t endMs;      
        uint16_t fadeInMs;
        uint16_t fadeOutMs;
        bool     retrigger;  
    };
 
    struct LayerSparkle {
        const uint32_t* palette;      
        uint8_t         paletteCount;
        uint8_t         densityPct;   
        uint8_t         fadeStep;     
    };
 
    struct LayerPattern {
        const BitScrollSegment* segments;      
        uint8_t                 segmentCount;
        uint8_t                 spacing;       
        bool                    repeating;     
    };
 
    struct LayerGauge {
        uint8_t    level;      
        bool       gradient;   
        GaugeStyle style;      
        GaugeBlend blend;
        const GaugeStop* stops;    
        uint8_t          stopCount;
        double           emptyAt;  
        double           fullAt;
    };

    struct LayerFrames {
        const uint8_t*  data;
        const uint16_t* index;        
        const uint32_t* palette;      
        uint8_t         paletteCount;
        uint8_t         width;        
        uint8_t         count;        
        uint16_t        frameMs;      
        const uint8_t*  scroll;
    };

    struct Layer {
        const char*  name;      
        LayerKind    kind;
        LayerSpan    span;
        LayerMix     mix;
        Binding      bindings[MAX_BINDINGS];
        LayerPaint   paint;
        LayerMotion  motion;
        LayerFlash   flash;
        LayerTime    time;
        LayerSparkle sparkle;
        LayerPattern pattern;
        LayerGauge   gauge;
        LayerFrames  frames;
    };

    struct Driver {
        const char*       name;
        DriverKind        kind;
        uint8_t           value;        
        LevelFn           read;         
        double            emptyAt;
        double            fullAt;
        bool              wrap;
        uint8_t           smoothing;    
        const MusicTrack* track;        
        uint8_t           sensitivity;
        bool              loop;
        LfoShape          shape;        
        uint32_t          periodMs;
        uint8_t           phasePct;     
    };

    struct Composition {
        const char*   name;
        const Layer*  layers;       
        uint8_t       layerCount;
        const Driver* drivers;
        uint8_t       driverCount;
        uint32_t      loopMs;       
        uint32_t      bgColor;      
    };


 
    // ========================================================================

    LedStrand(uint8_t adiPort, uint8_t length, uint32_t refreshMs = 20);

    LedStrand(ExpanderPort port, uint8_t length, uint32_t refreshMs = 20);

    LedStrand(uint8_t smartPort, uint8_t adiPort, uint8_t length, uint32_t refreshMs);

 
    // ========================================================================

    void init();

    void tick();

 
    // ========================================================================

    void off();

    void setColor(uint32_t color);

    void pulse(uint32_t color, uint8_t runLength, Speed speed,
               uint32_t bgColor = 0x000000, bool invert = false, bool bounce = false);

    void flash(uint32_t color, uint32_t onMs, uint32_t offMs, uint32_t bgColor = 0x000000);

    void flow(uint32_t color1, uint32_t color2, Speed speed, bool invert = false,
              bool seamless = true);

    void rainbow(Speed speed);

    void twinkle(const std::vector<uint32_t>& colors, uint8_t densityPct = 30,
                 uint8_t fadeStep = 16, uint32_t bgColor = 0x000000);

    void bitscroll(const std::vector<BitScrollSegment>& segments, Speed speed,
                   bool invert = false, uint32_t bgColor = 0x000000, bool bounce = false,
                   uint8_t spacing = 5, bool repeating = true);

 
    // ========================================================================

    void levelFill(uint32_t color, uint32_t color2 = 0x000000, bool gradient = false,
                   uint32_t bgColor = 0x000000, bool invert = false);

    void setLevel(uint8_t level);

    uint8_t getLevel() const { return levelValue; }

    void levelSource(LevelFn read, double emptyAt, double fullAt, bool wrap = false,
                     uint8_t smoothing = 0);

    void clearLevelSource();

    bool levelSourceActive() const { return levelRead != nullptr; }

    void musicSync(const MusicTrack& track, uint32_t color, uint32_t color2 = 0x000000,
                   bool gradient = false, uint32_t bgColor = 0x000000, bool invert = false,
                   uint8_t sensitivity = 100, bool loop = false);

    void musicSeek(uint32_t positionMs);

    void musicPause(bool paused = true);

    bool musicPlaying() const { return musicTrack != nullptr && !musicPaused; }

    uint32_t musicPositionMs() const;

    void setSensitivity(uint8_t pct);

 
    // ========================================================================

    void spliceMask(uint8_t sections, bool invert = false, bool alternating = false,
                    uint32_t altPeriodMs = 100, uint32_t bgColor = 0x000000,
                    bool useOverlay = false);

    void spliceMaskCustom(const std::vector<SpliceRegion>& regions);

    void setRegionLevel(uint8_t regionIdx, uint8_t level);

    static SpliceRegion motorHeatGauge(uint8_t start, uint8_t width, LevelFn read = nullptr);

    void clearSpliceMask();

 
    // ========================================================================

    void overlaySetColor(uint32_t color);

    void overlayPulse(uint32_t color, uint8_t runLength, Speed speed,
                      uint32_t bgColor = 0x000000);

    void overlayFlash(uint32_t color, uint32_t onMs, uint32_t offMs,
                      uint32_t bgColor = 0x000000);

    void overlayFlow(uint32_t color1, uint32_t color2, Speed speed, bool seamless = true);

    void overlayRainbow(Speed speed);

    void overlayTwinkle(const std::vector<uint32_t>& colors, uint8_t densityPct = 30,
                        uint8_t fadeStep = 16, uint32_t bgColor = 0x000000);

    void overlayBitscroll(const std::vector<BitScrollSegment>& segments, Speed speed,
                          bool invert = false, uint32_t bgColor = 0x000000,
                          uint8_t spacing = 5, bool repeating = true);

 
    // ========================================================================

    void setBrightness(uint8_t pct);

    uint8_t getBrightness() const { return brightnessPct; }

 
    // ========================================================================

    void attachProfile(const Profile* profile);

    void detachProfile();

    void activateMode(uint8_t modeIdx);

    void activateModeTimed(uint8_t modeIdx, uint32_t durationMs);

    void deactivateMode(uint8_t modeIdx);

 
    // ========================================================================
    // ========================================================================

    void compose(const Composition& comp);

    void clearComposition();

    bool composing() const { return composition != nullptr; }

    void setDriverLevel(uint8_t driverIdx, uint8_t value);

    uint8_t getDriverLevel(uint8_t driverIdx) const;

    void restartComposition();

    void composeMusicSeek(uint32_t positionMs);

    void composeMusicPause(bool paused = true);

    uint32_t composeMusicPositionMs() const;

 
    // ========================================================================

    uint8_t getLength() const { return length; }

 
    // ========================================================================
    // Maximum supported LEDs per strand.
    static constexpr uint8_t MAX_LEDS = 64;
 
private:
    // LedGroup sets refreshMs to the interval it actually ticks the strand at.
    friend class LedGroup;
 
    // ---- Hardware ----
    uint8_t  adiPort;
    uint8_t  smartPort  = 0;
    uint8_t  length;
    uint32_t refreshMs;
    platform::AdiLed* led = nullptr;
    platform::Mutex mutex;
 
    // The last frame actually written to the strip, and when. flushBuffer()
    // skips a frame identical to it, since the pixels hold what they were
    // sent, and every write costs a 12 ms slot on the shared ADI.
    uint32_t lastSent[MAX_LEDS] = {0};
    uint32_t lastSentMs         = 0;
    bool     lastSentValid      = false;
 
    // Called by LedGroup, which ticks the strand at its own interval: every
    // duration converted to ticks after this counts at that rate.
    void setRefreshMs(uint32_t ms);
 
    enum class AnimMode : uint8_t { STATIC, SHIFT, TWINKLE, FLASH, LEVEL };
 
    // Paces a moving animation: due() is true once every `hold` refresh
    // ticks. A hold of 1 - what a bare-number Speed gives - moves on every
    // tick, which is all `speed` could do before it could be slower.
    struct StepPacer {
        uint16_t hold    = 1;
        uint16_t counter = 0;
        void reset(uint16_t ticks) { hold = ticks ? ticks : 1; counter = 0; }
        void restart() { counter = 0; }
        bool due() {
            if (++counter < hold) return false;
            counter = 0;
            return true;
        }
    };
 
    // Base buffer
    AnimMode              animMode     = AnimMode::STATIC;
    int                   shiftStep    = 0;
    uint8_t               shiftVariant = 0;   // pixels per step, pre-reversed for invert
    StepPacer             shiftPacer;         // SHIFT, and both bounces
    std::vector<uint32_t> buffer;
 
    // Pulse bounce
    uint8_t  pulseRunLen = 0;
    uint32_t pulseColor  = 0;
    uint32_t pulseBg     = 0;
    uint8_t  pulseSpeed  = 1;
    int16_t  pulseOffset = 0;
    int8_t   pulseDir    = 1;
 
    // Flash - whole-strip blink driven by tick counts rather than a shifting
    // buffer, so the lit and blank halves can have independent durations.
    uint32_t flashColor    = 0;
    uint32_t flashBgColor  = 0;
    uint16_t flashOnTicks  = 1;
    uint16_t flashOffTicks = 1;
    uint16_t flashCounter  = 0;
    bool     flashLit      = true;
 
    // Bitscroll bounce
    std::vector<uint32_t> bitscrollMaster;
    int16_t               bounceScrollPos = 0;
    int8_t                bounceScrollDir = 1;
    uint8_t               bounceSpeed     = 1;
 
    // Twinkle - per-pixel fade state for one buffer. A struct rather than loose
    // members because three different buffers animate this way: the base
    // strand, the overlay, and any number of custom regions.
    struct TwinkleState {
        std::vector<uint8_t>  level;
        std::vector<uint8_t>  target;
        std::vector<uint8_t>  colorIdx;
        std::vector<uint8_t>  holdTicks;
        std::vector<uint32_t> palette;
        uint8_t  densityPct = 30;
        uint8_t  fadeStep   = 16;
        uint32_t bgColor    = 0x000000;
 
        void reset(uint8_t width, const std::vector<uint32_t>& colors, uint8_t density,
                   uint8_t fade, uint32_t bg);
    };
    static void advanceTwinkleInto(TwinkleState& t, std::vector<uint32_t>& buf);
 
    // advanceTwinkleInto() split in two, so a custom-animation layer can take
    // the per-pixel brightness in @c t.level as coverage and blend it over
    // whatever is beneath instead of over a single background color.
    // advanceTwinkleInto() is exactly these two in sequence.
    static void stepTwinkle(TwinkleState& t, uint8_t width);
    static void paintTwinkleInto(const TwinkleState& t, std::vector<uint32_t>& buf, uint8_t width);
 
    TwinkleState twinkleState;
 
    // Level meter - buffer holds the meter's colors across the whole strip and
    // levelValue picks how much of it is revealed, so changing the level costs
    // nothing until flush time.
    uint8_t  levelValue  = 0;
    uint32_t levelBg     = 0x000000;
    bool     levelInvert = false;
 
    // Live fill source - a reader polled once per tick plus the range that
    // maps what it returns onto 0-255. levelPrimed exists so the first sample
    // after levelSource() lands instantly instead of the bar crawling up to it
    // from empty through the smoothing filter.
    LevelFn  levelRead   = nullptr;
    double   levelEmptyAt = 0.0;
    double   levelFullAt  = 100.0;
    bool     levelWrap    = false;
    uint8_t  levelSmooth  = 0;
    bool     levelPrimed  = false;
 
    // Music sync - playback is a wall-clock anchor rather than a tick counter,
    // so a strand that misses a tick (or refreshes slowly) stays in step with
    // the music instead of drifting behind it.
    const MusicTrack* musicTrack   = nullptr;
    uint32_t musicAnchorMs         = 0;  // millis() that corresponds to position 0
    uint32_t musicPausedAt         = 0;  // position held while paused
    bool     musicPaused           = false;
    bool     musicLoop             = false;
    uint8_t  musicSensitivity      = 100;
 
    // Splice mask
    enum class SpliceMode : uint8_t { SPLIT, CUSTOM };
 
    // Runtime animation state for one CUSTOM-mode region, a scaled-down
    // version of the overlay buffer (buffer + shift step/speed), but one per
    // region instead of shared.
    struct SpliceRegionState {
        uint8_t                start = 0;
        std::vector<uint32_t>  buffer;
        int                    shiftStep  = 0;
        uint8_t                shiftSpeed = 0;
        StepPacer              shiftPacer;
        // Index in the vector the caller passed to spliceMaskCustom(), which
        // is what setRegionLevel() addresses. Not the index in spliceRegions:
        // SOLID and OFF regions never get a state, so the two disagree.
        uint8_t  userIdx = 0;
        // GAUGE - a per-region copy of the strand-wide meter's state, so each
        // segment follows its own reading at its own range and smoothing.
        bool       gauge       = false;
        LevelFn    levelRead   = nullptr;
        double     levelEmptyAt = 0.0;
        double     levelFullAt  = 100.0;
        bool       levelWrap    = false;
        uint8_t    levelSmooth  = 0;
        uint8_t    levelValue   = 0;
        bool       levelPrimed  = false;
        bool       gaugeInvert  = false;
        GaugeStyle gaugeStyle   = GaugeStyle::HEAT;
        GaugeBlend gaugeBlend   = GaugeBlend::LERP;
        uint32_t   gaugeBg      = 0x000000;
        // The scale, resolved onto the 0-255 axis levelValue lives on, so a
        // tick only has to bracket a byte rather than redo the mapping.
        std::vector<std::pair<uint8_t, uint32_t>> gaugeStops;
        // FLASH regions blink their whole buffer on a tick timer instead of
        // shifting it, mirroring the strand-wide flash state.
        bool     flashing      = false;
        uint32_t flashColor    = 0;
        uint32_t flashBgColor  = 0;
        uint16_t flashOnTicks  = 1;
        uint16_t flashOffTicks = 1;
        uint16_t flashCounter  = 0;
        bool     flashLit      = true;
        // TWINKLE regions repaint their buffer every tick rather than shifting
        // it, the same way the strand-wide twinkle does.
        bool         twinkling = false;
        TwinkleState twinkle;
    };
 
    bool              spliceActive      = false;
    SpliceMode        spliceMode        = SpliceMode::SPLIT;
    uint8_t           spliceSections    = 0;
    bool              spliceInvert      = false;
    bool              spliceAlternating = false;
    uint32_t          spliceAltMs       = 100;
    uint32_t          spliceBgColor     = 0x000000;
    bool              spliceUseOverlay  = false;
    bool              spliceAltPhase    = false;
    uint32_t          spliceLastToggleMs = 0;
    std::vector<bool>     spliceShowAnim;
    std::vector<uint32_t> splicePixelBg;
    std::vector<bool>     splicePixelUseOverlay;
    std::vector<int16_t>  splicePixelRegionIdx;  // CUSTOM mode: index into spliceRegions, or -1
    std::vector<SpliceRegionState> spliceRegions; // CUSTOM mode only
    // Bumped whenever the mask is replaced. advanceSpliceRegions() releases
    // the mutex to run a gauge's reader (user code, which may call back in),
    // and compares this afterwards to notice that the regions it was walking
    // are gone.
    uint32_t spliceGeneration = 0;
 
    // Overlay buffer
    AnimMode              overlayAnimMode   = AnimMode::STATIC;
    int                   overlayShiftStep  = 0;
    uint8_t               overlayShiftSpeed = 0;
    StepPacer             overlayShiftPacer;
    std::vector<uint32_t> overlayBuffer;
 
    // Overlay flash - mirrors the base flash state above.
    uint32_t overlayFlashColor    = 0;
    uint32_t overlayFlashBgColor  = 0;
    uint16_t overlayFlashOnTicks  = 1;
    uint16_t overlayFlashOffTicks = 1;
    uint16_t overlayFlashCounter  = 0;
    bool     overlayFlashLit      = true;
 
    // Overlay twinkle - mirrors the base twinkle state above.
    TwinkleState overlayTwinkleState;
 
    // Brightness
    uint8_t brightnessPct = 100;
 
    // Profile state
    struct ModeEntry {
        uint8_t  modeIdx;
        bool     persistent;
        uint32_t endMs;
    };
    const Profile*         activeProfile = nullptr;
    std::vector<ModeEntry> modeStack;
    int16_t                lastModeIdx = -1;
 
    // Internal implementations (no lock)
    void setColorNL(uint32_t color);
    void pulseNL(uint32_t color, uint8_t runLen, Speed speed, uint32_t bg, bool invert, bool bounce);
    void flashNL(uint32_t color, uint32_t onMs, uint32_t offMs, uint32_t bg);
    void flowNL(uint32_t c1, uint32_t c2, Speed speed, bool invert, bool seamless);
    void rainbowNL(Speed speed);
    void twinkleNL(const std::vector<uint32_t>& colors, uint8_t densityPct,
                   uint8_t fadeStep, uint32_t bgColor);
    void bitscrollNL(const std::vector<BitScrollSegment>& segments, Speed speed, bool invert,
                     uint32_t bgColor, bool bounce, uint8_t spacing, bool repeating);
 
    void overlaySetColorNL(uint32_t color);
    void overlayPulseNL(uint32_t color, uint8_t runLen, Speed speed, uint32_t bg);
    void overlayFlashNL(uint32_t color, uint32_t onMs, uint32_t offMs, uint32_t bg);
    void overlayFlowNL(uint32_t c1, uint32_t c2, Speed speed, bool seamless);
    void overlayRainbowNL(Speed speed);
    void overlayTwinkleNL(const std::vector<uint32_t>& colors, uint8_t densityPct,
                          uint8_t fadeStep, uint32_t bgColor);
    void overlayBitscrollNL(const std::vector<BitScrollSegment>& segments, Speed speed,
                            bool invert, uint32_t bgColor, uint8_t spacing, bool repeating);
 
    void levelFillNL(uint32_t color, uint32_t color2, bool gradient, uint32_t bg, bool invert);
 
    // One tile of a bitscroll pattern: the lit runs and the gaps between them.
    // `contentLen` comes back as the size up to the last lit pixel, i.e.
    // without the trailing gap, which only separates one tile from the next.
    static std::vector<uint32_t> buildBitscrollUnit(const std::vector<BitScrollSegment>& segments,
                                                    uint32_t bgColor, uint8_t spacing,
                                                    size_t& contentLen);
    // The same tile, from a plain array rather than a vector, because a custom
    // animation's segments live in a flash-resident table with no vector to
    // hand over. @p coverage, when given, comes back the same length as the
    // returned unit: 255 for a lit pixel and 0 for a gap, filled in the same
    // loop so it cannot drift from the colors. The vector overload forwards
    // here.
    static std::vector<uint32_t> buildBitscrollUnit(const BitScrollSegment* segments,
                                                    uint8_t count, uint32_t bgColor,
                                                    uint8_t spacing, size_t& contentLen,
                                                    std::vector<uint8_t>* coverage = nullptr);
    // Lay one tile into `buf` across `width` pixels - tiled when `repeating`,
    // a single copy on `bgColor` when not - and return the per-step shift that
    // scrolls it. Shared by the base, overlay, and per-region bitscrolls.
    static uint8_t fillBitscrollBuffer(std::vector<uint32_t>& buf,
                                       const std::vector<uint32_t>& unit, size_t contentLen,
                                       uint8_t width, uint32_t bgColor, uint8_t speed,
                                       bool invert, bool repeating);
 
    void advanceLevel();
    void advanceFlash();
    void advanceOverlayFlash();
    void advancePulseBounce();
    void advanceBitscrollBounce();
    void fillBitscrollFromMaster();
    void advanceSpliceAlternating(uint32_t nowMs);
    void advanceSpliceRegions();
    void paintGaugeRegion(SpliceRegionState& state);
    void rebuildSpliceMask();
 
    void     shiftBuffer();
    void     shiftOverlayBuffer();
    void     flushBuffer(uint32_t now);   // called with the mutex held; gives it back
    uint32_t levelPixel(uint8_t i, uint32_t full, uint8_t frac) const;
    uint8_t  sampleMusicNL(uint32_t positionMs) const;
    uint8_t  mapLevelNL(double raw) const;
    uint8_t  smoothLevelNL(uint8_t target) const;
 
    // The mapping and smoothing above, with the range passed in rather than
    // read off the strand, so a gauge region can reuse them for its own.
    static uint8_t mapLevelTo(double raw, double emptyAt, double fullAt, bool wrap);
    static uint8_t smoothLevelTo(uint8_t target, uint8_t current, uint8_t smoothing, bool wrap);
    static uint32_t gaugeColorAt(const SpliceRegionState& state, uint8_t level);
 
    // gaugeColorAt()'s scale lookup, with the stops passed in rather than read
    // off a region, so a custom-animation layer can carry its own scale.
    // gaugeColorAt() is a thin wrapper over this.
    static uint32_t scaleColorAt(const std::pair<uint8_t, uint32_t>* stops, uint8_t count,
                                 GaugeBlend blend, uint32_t bgColor, uint8_t level);
 
    // sampleMusicNL()'s body, with the track and playback options passed in
    // rather than read off the strand, so a custom-animation driver can play a
    // track of its own. sampleMusicNL() is a thin wrapper over this.
    static uint8_t sampleTrackNL(const MusicTrack* track, uint32_t positionMs,
                                 uint8_t sensitivity, bool loop);
 
    // One color from a two-color ramp: genGradient()'s loop body, extracted so
    // a custom-animation layer can sample a gradient without building the
    // whole buffer. genGradient() is written in terms of this, so the two can
    // never disagree.
    static uint32_t gradientPixel(uint32_t c1, uint32_t c2, uint8_t i, uint8_t len,
                                  bool seamless);
 
    // Blend @p fg over @p bg by @p level (0-255), and the NeoPixel-style hue
    // wheel. Private statics rather than file-local helpers so the custom
    // animation evaluator in led_custom.cpp can reach the same bodies the
    // presets use.
    static uint32_t lerpColor(uint32_t bg, uint32_t fg, uint8_t level);
    static uint32_t wheel(uint8_t pos);
 
    int16_t computeEffectiveMode() const;
    void    pruneExpired(uint32_t now);
    uint32_t applyBrightness(uint32_t color) const;
    uint16_t msToTicks(uint32_t ms) const;
    uint16_t stepTicks(Speed s) const { return s.stepMs ? msToTicks(s.stepMs) : 1; }

    static std::vector<uint32_t> genGradient(uint32_t c1, uint32_t c2, uint8_t len,
                                              bool seamless = false);
    static std::vector<uint32_t> genRainbow(uint8_t len);
 
    // ========================================================================
    // Custom animation state and evaluator (src/led_custom.cpp)
    // ========================================================================

    static constexpr uint32_t COVER_OPAQUE = 0xFF000000u;

    struct Resolved {
        uint8_t start;
        uint8_t width;
        uint8_t runLength;
        uint8_t speed;       
        uint8_t densityPct;
        uint8_t opacity;
        uint8_t level;
        uint8_t mix;
    };

    struct LayerState {
        uint16_t shiftAcc     = 0;   
        int16_t  bouncePos    = 0;
        int8_t   bounceDir    = 1;
        uint16_t flashCounter = 0;
        bool     flashLit     = true;
        bool     wasOpen      = false;  
        uint16_t frameIdx     = 0;      
        uint16_t frameCounter = 0;      
        StepPacer step;                 
        uint16_t scratchAt    = 0;      
        uint16_t scratchLen   = 0;      
        uint16_t contentLen   = 0;      
        uint8_t  maxSpan      = 0;      
        TwinkleState twinkle;           
        std::vector<std::pair<uint8_t, uint32_t>> stops;
    };
 
    const Composition* composition     = nullptr;
    uint32_t           composeAnchorMs = 0;
    uint32_t           composeGeneration    = 0;
    uint32_t           composeMusicPausedAt = 0;
    bool               composeMusicPaused   = false;
 
    std::vector<LayerState> layerStates;
    std::vector<uint32_t> composeArena;
    uint8_t driverValue[MAX_DRIVERS]  = {0};
    bool    driverPrimed[MAX_DRIVERS] = {false};
 
    void    advanceComposition(uint32_t nowMs);
    void    dropCompositionNL();
    uint32_t composeClockNL(uint32_t nowMs) const;
    bool    evalDriversNL(const Composition& c, uint32_t nowMs);
    void    resolveLayerNL(const Composition& c, const Layer& l, Resolved& p) const;
    uint8_t resolveSpan(const Resolved& p, const LayerState& st) const;
    uint8_t motionRing(const Layer& l, uint8_t span) const;
    void    prepareLayerNL(const Layer& l, LayerState& st, uint8_t span, uint16_t& arenaAt);
    void    buildLayerNL(const Layer& l, LayerState& st);
    void    resetLayerStateNL(const Layer& l, LayerState& st, uint8_t ring);
    void    advanceLayerNL(const Layer& l, LayerState& st, const Resolved& p, uint8_t ring);
    uint32_t layerPixel(const Layer& l, const LayerState& st, const Resolved& p,
                        uint8_t k, uint8_t span) const;
    void    compositeLayerNL(const Layer& l, const LayerState& st, const Resolved& p,
                             uint8_t span, uint8_t alpha);
    void    decodeFrameNL(const Layer& l, LayerState& st);
 
    static uint8_t  nominalSpan(const Layer& l, uint8_t len);
    static uint8_t  applyCurve(const uint8_t* curve, uint8_t v);
    static uint8_t  layerWindowAlpha(const Layer& l, uint32_t t, uint32_t period);
    static uint8_t  shiftFor(uint8_t speed, uint8_t ring, bool invert);
    static uint8_t  lfoValue(const Driver& d, uint32_t nowMs);
    static uint32_t blendPixel(LayerBlend m, uint32_t dst, uint32_t src, uint8_t a);
    static uint32_t addSat(uint32_t a, uint32_t b);
    static uint32_t screenColor(uint32_t a, uint32_t b);
    static uint32_t mulColor(uint32_t a, uint32_t b);
    static uint8_t  luma(uint32_t c);
};
 
} // namespace hitlib