led_strand.hpp

Go to the documentation of this file.

#pragma once
#include "led_profile.hpp"
#include "pros/adi.hpp"
#include "pros/rtos.hpp"
#include <cstdint>
#include <utility>
#include <vector>

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

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

    struct BitScrollSegment {
        uint32_t color; 
        uint8_t  width; 
    };

    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;        
        uint8_t  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;    
    };

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

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

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

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

    void init();

    void tick();

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

    void off();

    void setColor(uint32_t color);

    void pulse(uint32_t color, uint8_t runLength, uint8_t 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, uint8_t speed, bool invert = false,
              bool seamless = true);

    void rainbow(uint8_t 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, uint8_t 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, uint8_t 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, uint8_t speed, bool seamless = true);

    void overlayRainbow(uint8_t 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, uint8_t 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);

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

    uint8_t getLength() const { return length; }

 
    // ========================================================================
    // Maximum supported LEDs per strand.
    static constexpr uint8_t MAX_LEDS = 64;
 
private:
    // ---- Hardware ----
    uint8_t  adiPort;
    uint8_t  smartPort  = 0;
    uint8_t  length;
    uint32_t refreshMs;
    pros::adi::Led* led = nullptr;
    pros::Mutex mutex;
 
    enum class AnimMode : uint8_t { STATIC, SHIFT, TWINKLE, FLASH, LEVEL };
 
    // Base buffer
    AnimMode              animMode     = AnimMode::STATIC;
    int                   shiftStep    = 0;
    uint8_t               shiftVariant = 0;
    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);
 
    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;
        // 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;
    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, uint8_t 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, uint8_t speed, bool invert, bool seamless);
    void rainbowNL(uint8_t 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, uint8_t 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, uint8_t 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, uint8_t speed, bool seamless);
    void overlayRainbowNL(uint8_t 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, uint8_t 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);
    // Lay one tile into `buf` across `width` pixels - tiled when `repeating`,
    // a single copy on `bgColor` when not - and return the per-tick 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 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);
 
    int16_t computeEffectiveMode() const;
    void    pruneExpired(uint32_t now);
    uint32_t applyBrightness(uint32_t color) const;
    uint16_t msToTicks(uint32_t ms) const;
 
    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);
};
 
} // namespace hitlib