SBK_BarMeterAnimations.h

Go to the documentation of this file.

 
#pragma once
 
#include <Arduino.h>
 
// Maximum number of animations stored by each animation controller.
// Define before including SBK_BarDrive.h to select a smaller or larger queue.
#ifndef SBK_BARDRIVE_QUEUE_CAPACITY
#define SBK_BARDRIVE_QUEUE_CAPACITY 4
#endif
 
#if SBK_BARDRIVE_QUEUE_CAPACITY < 1 || SBK_BARDRIVE_QUEUE_CAPACITY > 255
#error "SBK_BARDRIVE_QUEUE_CAPACITY must be between 1 and 255"
#endif

template <typename BarMeterT>
class SBK_BarMeterAnimations
{
public:
    static constexpr uint8_t NO_QUEUE_INDEX = 0xFF;

    explicit SBK_BarMeterAnimations(BarMeterT &barMeter) : _barMeter(barMeter)
    {
        _initializeStorage();
    }
 
    ~SBK_BarMeterAnimations()
    {
        delete[] _animationWorkspace;
    }

    void setSegsNum(uint8_t n)
    {
        _segsNum = _minValue(n, _segmentCapacity);
        _maxTracker = _segsNum > 0 ? _segsNum - 1 : 0;
    }

    bool update(uint32_t syncTime = millis())
    {
        // Keep all animation deadlines on a clock that excludes paused time.
        if (_isPaused)
            return _queueActive;
 
        _currentTime = syncTime - _pausedTime;
 
        if (_queueEntryTimingPending)
        {
            _queueEntryStartedAt = _currentTime;
            _queueEntryTimingPending = false;
        }
 
        if (_isRunning && _currentFunc && _activeBlockEmissionStopAfter > 0 &&
            _currentTime - _queueEntryStartedAt >= _activeBlockEmissionStopAfter)
        {
            if (_currentFunc == &SBK_BarMeterAnimations::_mirrorBlocks ||
                _currentFunc == &SBK_BarMeterAnimations::_scrollingBlocks)
            {
                // Stop producing blocks at the deadline, but keep updating until
                // every block already in flight has naturally left the display.
                _emittingBlocksEnabled = false;
                _loop = false;
            }
            _activeBlockEmissionStopAfter = 0;
        }
 
        if (_isRunning && _currentFunc && _queueEntryDuration > 0 &&
            _currentTime - _queueEntryStartedAt >= _queueEntryDuration)
        {
            if (_queueActive)
                _startNextQueuedAnimation();
            else
            {
                _isRunning = false;
                _isPaused = false;
                _loop = false;
                _isLoopingNow = false;
                _currentFunc = nullptr;
                _init = true;
                _queueEntryDuration = 0;
            }
            return _isRunning;
        }
 
        if (!_isRunning || _isPaused || !_currentFunc)
            return _queueActive;
 
        if ((this->*_currentFunc)())
        {
            if (_loop)
            {
                if (_skipPending)
                    _isLoopingNow = false;
                else
                {
                    _isLoopingNow = true; // mark it so user can react
                    _init = true;
                }
            }
            else
            {
                if (_queueActive)
                    _startNextQueuedAnimation();
                else
                {
                    _isLoopingNow = false;
                    _isRunning = false;
                    _currentFunc = nullptr;
                    _queueActive = false;
                    _currentQueueIndex = NO_QUEUE_INDEX;
                    _queueEntryDuration = 0;
                    _activeBlockEmissionStopAfter = 0;
                }
            }
        }
        return _isRunning;
    }

    SBK_BarMeterAnimations &animInit()
    {
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &pause(uint32_t syncTime = millis())
    {
        if (!_isPaused)
        {
            _pausedAt = syncTime;
            _isPaused = true;
        }
        return *this;
    }

    SBK_BarMeterAnimations &resume(uint32_t syncTime = millis())
    {
        if (_isPaused)
        {
            _pausedTime += syncTime - _pausedAt;
            _isPaused = false;
        }
        return *this;
    }

    SBK_BarMeterAnimations &stop()
    {
        resume();
        _isRunning = false;
        _loop = false;
        _isLoopingNow = false;
        _skipPending = false;
        _currentFunc = nullptr;
        _animLogicSet = false;
        _init = true;
        _blockEmissionStopAfter = 0;
        _animationDuration = 0;
        _queueEntryDuration = 0;
        _activeBlockEmissionStopAfter = 0;
        clearQueue();
        _barMeter.clear();
        return *this;
    }

    SBK_BarMeterAnimations &enqueue()
    {
        if (!_currentFunc)
            return *this;
 
        if (_queueStoredCount < QUEUE_CAPACITY)
        {
            _captureQueueEntry(_queue[_queueTail], true, _animationDuration);
            _queueTail = (_queueTail + 1) % QUEUE_CAPACITY;
            _queueCount++;
            _queueStoredCount++;
        }
        else
        {
            _queueOverflow = true;
        }
 
        _isRunning = false;
        _currentFunc = nullptr;
        _blockEmissionStopAfter = 0;
        _animationDuration = 0;
        return *this;
    }

    SBK_BarMeterAnimations &enqueueFor(uint32_t duration)
    {
        if (!_currentFunc)
            return *this;
 
        if (_queueStoredCount < QUEUE_CAPACITY)
        {
            _captureQueueEntry(_queue[_queueTail], true, duration);
            _queueTail = (_queueTail + 1) % QUEUE_CAPACITY;
            _queueCount++;
            _queueStoredCount++;
        }
        else
        {
            _queueOverflow = true;
        }
 
        _isRunning = false;
        _currentFunc = nullptr;
        _blockEmissionStopAfter = 0;
        _animationDuration = 0;
        return *this;
    }

    SBK_BarMeterAnimations &forTime(uint32_t duration)
    {
        if (_currentFunc)
        {
            _animationDuration = duration;
            _queueEntryDuration = duration;
            _queueEntryTimingPending = true;
        }
        else if (_queueCount > 0)
        {
            const uint8_t previousIndex =
                (_queueTail + QUEUE_CAPACITY - 1) % QUEUE_CAPACITY;
            _queue[previousIndex].duration = duration;
        }
        return *this;
    }

    SBK_BarMeterAnimations &enqueueReverseAnim()
    {
        if (_queueCount == 0)
            return *this;
 
        if (_queueStoredCount >= QUEUE_CAPACITY)
        {
            _queueOverflow = true;
            return *this;
        }
 
        const uint8_t previousIndex =
            (_queueTail + QUEUE_CAPACITY - 1) % QUEUE_CAPACITY;
        QueueEntry &entry = _queue[_queueTail];
        entry = _queue[previousIndex];
        entry.loop = _loop;
        entry.animInitLogicIsInverted = !entry.animInitLogicIsInverted;
        entry.animRenderLogicIsInverted = !entry.animRenderLogicIsInverted;
        entry.resetRuntimeState = false;
        entry.duration = 0;
        entry.blockEmissionStopAfter = 0;
 
        _queueTail = (_queueTail + 1) % QUEUE_CAPACITY;
        _queueCount++;
        _queueStoredCount++;
        return *this;
    }

    SBK_BarMeterAnimations &loopQueue()
    {
        _queueLoop = true;
        return *this;
    }

    SBK_BarMeterAnimations &noLoopQueue()
    {
        _queueLoop = false;
        return *this;
    }

    SBK_BarMeterAnimations &startQueue()
    {
        if (_queueCount > 0)
        {
            if (!_queueActive)
                _queueStart = _queueHead;
            _queueActive = true;
            _startNextQueuedAnimation(true);
        }
        return *this;
    }

    SBK_BarMeterAnimations &clearQueue()
    {
        _queueHead = 0;
        _queueTail = 0;
        _queueCount = 0;
        _queueStoredCount = 0;
        _queueStart = 0;
        _queueLoop = false;
        _currentQueueIndex = NO_QUEUE_INDEX;
        _queueActive = false;
        _queueOverflow = false;
        return *this;
    }

    SBK_BarMeterAnimations &skipCurrent()
    {
        if (!_isRunning || !_currentFunc)
            return *this;
 
        _loop = false;
        resume();
        _isLoopingNow = false;
        _skipPending = false;
 
        if (_queueActive)
            _startNextQueuedAnimation();
        else
        {
            _isRunning = false;
            _currentFunc = nullptr;
            _queueActive = false;
            _currentQueueIndex = NO_QUEUE_INDEX;
        }
        return *this;
    }

    uint8_t queuedAnimations() const { return _queueCount; }

    bool isQueueRunning() const { return _queueActive; }

    uint8_t currentQueueIndex() const { return _currentQueueIndex; }

    bool isQueueIndexPlaying(uint8_t index) const
    {
        return _queueActive && _currentQueueIndex == index;
    }

    bool queueOverflowed() const { return _queueOverflow; }

    SBK_BarMeterAnimations &loop()
    {
        if (_currentFunc == &SBK_BarMeterAnimations::_wait)
            return *this;
        _loop = true;
        return *this;
    }

    SBK_BarMeterAnimations &noLoop()
    {
        _loop = false;
        return *this;
    }

    SBK_BarMeterAnimations &setDir(bool newDirection)
    {
        _animRenderDirIsReversed = newDirection;
        _animDirSet = true;
        return *this;
    }

    SBK_BarMeterAnimations &toggleDir()
    {
        _animRenderDirIsReversed = !_animRenderDirIsReversed;
        _animDirSet = true;
        return *this;
    }

    SBK_BarMeterAnimations &reverseDir()
    {
        _animRenderDirIsReversed = !_AnimInitDirIsReversed;
        _animDirSet = true;
        return *this;
    }

    SBK_BarMeterAnimations &resetDir()
    {
        _animRenderDirIsReversed = _AnimInitDirIsReversed;
        _animDirSet = false;
        return *this;
    }

    SBK_BarMeterAnimations &setLogic(bool newLogic)
    {
        if (_isNonInvertingLogicAnim)
            return *this;
        _animRenderLogicIsInverted = newLogic;
        _animLogicSet = true;
        return *this;
    }

    SBK_BarMeterAnimations &toggleLogic()
    {
        if (_isNonInvertingLogicAnim)
            return *this;
        _animRenderLogicIsInverted = !_animRenderLogicIsInverted;
        _animLogicSet = true;
        return *this;
    }

    SBK_BarMeterAnimations &invertLogic()
    {
        if (_isNonInvertingLogicAnim)
            return *this;
        _animRenderLogicIsInverted = !_AnimInitLogicIsInverted;
        _animLogicSet = true;
        return *this;
    }

    SBK_BarMeterAnimations &resetLogic()
    {
        if (_isNonInvertingLogicAnim)
            return *this;
        _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
        _animLogicSet = false;
        return *this;
    }

    SBK_BarMeterAnimations &stopBlockEmission()
    {
        _emittingBlocksEnabled = false;
        return *this;
    }

    SBK_BarMeterAnimations &resumeBlockEmission()
    {
        _emittingBlocksEnabled = true;
        return *this;
    }

    SBK_BarMeterAnimations &stopBlockEmissionAfter(uint32_t duration)
    {
        if (_currentFunc)
        {
            _blockEmissionStopAfter = duration;
            _activeBlockEmissionStopAfter = duration;
            _queueEntryTimingPending = true;
        }
        else if (_queueCount > 0)
        {
            const uint8_t previousIndex =
                (_queueTail + QUEUE_CAPACITY - 1) % QUEUE_CAPACITY;
            _queue[previousIndex].blockEmissionStopAfter = duration;
        }
        return *this;
    }

    SBK_BarMeterAnimations &waitTrailingSpace(bool enabled = true)
    {
        if (_currentFunc)
            _waitTrailingSpace = enabled;
        else if (_queueCount > 0)
            _queue[(_queueTail + QUEUE_CAPACITY - 1) % QUEUE_CAPACITY].waitTrailingSpace = enabled;
        return *this;
    }

    bool isRunning() const { return _isRunning; }

    bool isPaused() const { return _isPaused; }

    bool isLoopEnabled() const { return _loop; }

    SBK_BarMeterAnimations &setUpdateInterval(uint16_t interval)
    {
        _updateIntv1 = _maxValue(static_cast<uint16_t>(1), interval);
        return *this;
    }

    bool animPendingLoop()
    {
        if (_skipPending == true)
            _skipPending = false;
        else
        {
            if (_isLoopingNow)
            {
                _isLoopingNow = false; // auto-clear after read
                return true;
            }
        }
        return false;
    }

    bool isLogicInverted()
    {
        if (_AnimInitLogicIsInverted != _animRenderLogicIsInverted)
            return true;
        else
            return false;
    }

    bool isNonInvertingLogicAnim() { return _isNonInvertingLogicAnim; }

    bool isDirectionReversed()
    {
        if (_AnimInitDirIsReversed != _animRenderDirIsReversed)
            return true;
        else
            return false;
    }

    bool isBlockEmissionEnabled() const { return _emittingBlocksEnabled; }
 
    // Animation starters
    SBK_BarMeterAnimations &setAll(bool onff) { return onff ? setAllOn() : setAllOff(); }

    SBK_BarMeterAnimations &setAllOn()
    {
        _currentFunc = &SBK_BarMeterAnimations::_setAllOn;
        _isRunning = true;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &setAllOff()
    {
        _currentFunc = &SBK_BarMeterAnimations::_setAllOff;
        _isRunning = true;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &wait(uint16_t duration)
    {
        _updateIntv1 = duration;
        _loop = false;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_wait;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &blinkPixel(uint8_t index, uint16_t interval = 500, uint8_t blinkCount = 0)
    {
        return blinkPixel(index, interval, interval, blinkCount);
    }

    SBK_BarMeterAnimations &blinkPixel(uint8_t index, uint16_t onInterval, uint16_t offInterval, uint8_t blinkCount)
    {
        _param1 = index;
        _param2 = blinkCount;
        _updateIntv1 = _maxValue(static_cast<uint16_t>(1), onInterval);
        _updateIntv2 = _maxValue(static_cast<uint16_t>(1), offInterval);
        _isNonInvertingLogicAnim = true;
        _usePtr = false;
        _currentFunc = &SBK_BarMeterAnimations::_blinkPixel;
        _isRunning = true;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &fillUpDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        _updateIntv1 = _maxValue(5, duration / steps);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &fillUpIntv(uint16_t updateIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _usePtr = true;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &fillUpIntv(uint16_t updateIntv, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &fillDownDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        _updateIntv1 = _maxValue(5, duration / steps);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &fillDownIntv(uint16_t updateIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _usePtr = true;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
        _isRunning = true;
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &fillDownIntv(uint16_t updateIntv, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &emptyDownDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        return emptyDownIntv(duration / steps, maxPercent, minPercent);
    }

    SBK_BarMeterAnimations &emptyDownIntv(uint16_t updateIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _usePtr = true;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &emptyDownIntv(uint16_t updateIntv, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &emptyUpDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = true;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        _updateIntv1 = _maxValue(5, duration / steps);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &emptyUpIntv(uint16_t updateIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = true;
        _usePtr = true;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &emptyUpIntv(uint16_t updateIntv, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = true;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _isRunning = true;
        _updateIntv1 = _maxValue(5, updateIntv);
        _currentFunc = &SBK_BarMeterAnimations::_fillOrEmpty;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillUpDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0, uint16_t fillIntv = 0)
    {
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        uint16_t emptyIntv = fillIntv;
        if (fillIntv == 0)
        {
            fillIntv = _maxValue(5, duration) / (2 * steps);
            emptyIntv = fillIntv;
        }
        else
        {
            emptyIntv = _maxValue(5, duration - fillIntv * steps) / steps;
        }
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFill;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillUpIntv(uint16_t fillIntv, uint16_t emptyIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = false;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _usePtr = true;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
        _updateIntv1 = _maxValue(5, fillIntv);  // Starting interval
        _updateIntv2 = _updateIntv1;      // Fill intv
        _updateIntv3 = _maxValue(5, emptyIntv); // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFill;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillUpIntv(uint16_t fillIntv = 10, uint16_t emptyIntv = 10, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _updateIntv1 = _maxValue(5, fillIntv);  // Starting interval
        _updateIntv2 = _updateIntv1;      // Fill intv
        _updateIntv3 = _maxValue(5, emptyIntv); // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFill;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillDownDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0, uint16_t fillIntv = 0)
    {
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        uint16_t emptyIntv = fillIntv;
        if (fillIntv == 0)
        {
            fillIntv = _maxValue(5, duration) / (2 * steps);
            emptyIntv = fillIntv;
        }
        else
        {
            emptyIntv = _maxValue(5, duration - fillIntv * steps) / steps;
        }
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFill;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillDownIntv(uint16_t fillIntv, uint16_t emptyIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _usePtr = true;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
        _updateIntv1 = _maxValue(5, fillIntv);  // Starting interval
        _updateIntv2 = _updateIntv1;      // Fill intv
        _updateIntv3 = _maxValue(5, emptyIntv); // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFill;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillDownIntv(uint16_t fillIntv = 10, uint16_t emptyIntv = 10, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, 0, _segsNum - 1);
        _updateIntv1 = _maxValue(5, fillIntv);  // Starting interval
        _updateIntv2 = _updateIntv1;      // Fill intv
        _updateIntv3 = _maxValue(5, emptyIntv); // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFill;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillFromCenterDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0, uint16_t fillIntv = 0)
    {
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
        _mirrorHalfRangeDir = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, (_segsNum / 2) - 1, 0);
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        uint16_t emptyIntv = fillIntv;
        if (fillIntv == 0)
        {
            fillIntv = _maxValue(5, duration) / (2 * steps);
            emptyIntv = fillIntv;
        }
        else
        {
            emptyIntv = _maxValue(5, duration - fillIntv * steps) / steps;
        }
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFillHalfRangeMirrorCenter;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillFromCenterIntv(uint16_t fillIntv, uint16_t emptyIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
        _mirrorHalfRangeDir = false;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _usePtr = true;
        _mapMinMaxTrackerFromPtr(minPercentPtr, maxPercentPtr, (_segsNum / 2) - 1, 0);
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFillHalfRangeMirrorCenter;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillFromCenterIntv(uint16_t fillIntv = 25, uint16_t emptyIntv = 25, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
        _mirrorHalfRangeDir = false;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, (_segsNum / 2) - 1, 0);
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFillHalfRangeMirrorCenter;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillFromEdgesDur(uint16_t duration, uint8_t maxPercent = 100, uint8_t minPercent = 0, uint16_t fillIntv = 0)
    {
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
        _mirrorHalfRangeDir = true;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, (_segsNum / 2) - 1, 0);
        uint8_t steps = _maxValue(1, _maxTracker - _minTracker + 1);
        uint16_t emptyIntv = fillIntv;
        if (fillIntv == 0)
        {
            fillIntv = _maxValue(5, duration) / (2 * steps);
            emptyIntv = fillIntv;
        }
        else
        {
            emptyIntv = _maxValue(5, duration - fillIntv * steps) / steps;
        }
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFillHalfRangeMirrorCenter;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillFromEdgesIntv(uint16_t fillIntv, uint16_t emptyIntv, const uint8_t *maxPercentPtr, const uint8_t *minPercentPtr = nullptr)
    {
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
        _mirrorHalfRangeDir = true;
        _valuePtr1 = maxPercentPtr;
        _valuePtr2 = minPercentPtr;
        _usePtr = true;
        _mapMinMaxTrackerFromPtr(minPercentPtr, maxPercentPtr, (_segsNum / 2) - 1, 0);
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFillHalfRangeMirrorCenter;
        return *this;
    }

    SBK_BarMeterAnimations &bounceFillFromEdgesIntv(uint16_t fillIntv = 25, uint16_t emptyIntv = 25, uint8_t maxPercent = 100, uint8_t minPercent = 0)
    {
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
        _mirrorHalfRangeDir = true;
        _usePtr = false;
        _valuePtr2 = nullptr;
        _valuePtr1 = nullptr;
        _mapMinMaxTracker(minPercent, maxPercent, (_segsNum / 2) - 1, 0);
        _updateIntv1 = fillIntv;     // Starting interval
        _updateIntv2 = _updateIntv1; // Fill intv
        _updateIntv3 = emptyIntv;    // Empty intv
        _sequenceState = 0;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_bounceFillHalfRangeMirrorCenter;
        return *this;
    }

    SBK_BarMeterAnimations &beatPulse(uint8_t *bpmPtr) // bouncing from bottom (maybe like a volume meter with the music)
    {
        _valuePtr1 = bpmPtr;
        _updateIntv1 = 60000UL / (bpmPtr ? _maxValue(1, *bpmPtr) : 116);
        _param2 = _minValue(35 * (_segsNum - 1) / 100, 255); // MIN_BASE_LEVEL
        _param3 = _minValue(67 * (_segsNum - 1) / 100, 255); // MIN_PEAK_LEVEL
        _param4 = 150;                                 // PEAK_HOLD_TIME
        _usePtr = true;
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
 
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_beatPulseLive;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &beatPulse(uint8_t bpm = 116) // bouncing from bottom (maybe like a volume meter with the music)
    {
        _param1 = _maxValue(1, bpm);
        _updateIntv1 = 60000UL / _param1;
        _param2 = _minValue(35 * (_segsNum - 1) / 100, 255); // MIN_BASE_LEVEL
        _param3 = _minValue(67 * (_segsNum - 1) / 100, 255); // MIN_PEAK_LEVEL
        _param4 = 150;                                 // PEAK_HOLD_TIME
        _valuePtr1 = nullptr;
        _usePtr = false;
        _isNonInvertingLogicAnim = true;
        _AnimInitLogicIsInverted = false;
        _animRenderDirIsReversed = false;
 
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_beatPulse;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &explodingBlocks(uint16_t intv = 50, uint8_t blockLength = 2, uint8_t blockSpacing = 1, uint8_t numBlocks = 0)
    {
        _waitTrailingSpace = false;
        _trailingSpacePending = false;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = numBlocks;
        _param4 = ((_segsNum / 2) / (blockLength + blockSpacing)) + 2;
        _param4 = constrain(_param4, 2, 32);
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_mirrorBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &collidingBlocks(uint16_t intv = 50, uint8_t blockLength = 2, uint8_t blockSpacing = 1, uint8_t numBlocks = 0)
    {
 
        _waitTrailingSpace = false;
        _trailingSpacePending = false;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = numBlocks;
        _param4 = ((_segsNum / 2) / (blockLength + blockSpacing)) + 2;
        _param4 = constrain(_param4, 2, 32);
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_mirrorBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &scrollingUpBlocks(uint16_t intv = 50, uint8_t blockLength = 2, uint8_t blockSpacing = 1, uint8_t numBlocks = 0)
    {
        _waitTrailingSpace = false;
        _trailingSpacePending = false;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = numBlocks;
        _param4 = (_segsNum / (blockLength + blockSpacing)) + 2;
        _param4 = constrain(_param4, 2, 64);
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_scrollingBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &scrollingDownBlocks(uint16_t intv = 50, uint8_t blockLength = 2, uint8_t blockSpacing = 1, uint8_t numBlocks = 0)
    {
        _waitTrailingSpace = false;
        _trailingSpacePending = false;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = numBlocks;
        _param4 = (_segsNum / (blockLength + blockSpacing)) + 2;
        _param4 = constrain(_param4, 2, 64);
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_scrollingBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &downStackingBlocks(uint16_t intv = 50, uint8_t blockLength = 1, uint8_t blockSpacing = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = 0; // requested number of blocks
        _param4 = 1; // aka maximum blocks number
        if (_init)
            _emittingBlocksEnabled = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_stackingBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &upUnstackingBlocks(uint16_t intv = 50, uint8_t blockLength = 1, uint8_t blockSpacing = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = 0; // aka requested number of blocks
        _param4 = 1; // aka maximum blocks number
        if (_init)
            _emittingBlocksEnabled = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_stackingBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &upStackingBlocks(uint16_t intv = 50, uint8_t blockLength = 1, uint8_t blockSpacing = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = 0; // aka requested number of blocks
        _param4 = 1; // aka maximum blocks number
        if (_init)
            _emittingBlocksEnabled = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_stackingBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &downUnstackingBlocks(uint16_t intv = 50, uint8_t blockLength = 1, uint8_t blockSpacing = 0)
    {
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = true;
        _updateIntv1 = _maxValue(5, intv);
        _param1 = blockLength;
        _param2 = blockSpacing;
        _param3 = 0; // aka requested number of blocks
        _param4 = 1; // aka maximum blocks number
        if (_init)
            _emittingBlocksEnabled = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_stackingBlocks;
        return *this;
    }

    SBK_BarMeterAnimations &followSignalSmooth(const uint16_t *sigPtr, uint16_t updateIntv = 100, uint16_t minMap = 0, uint16_t maxMap = 1023, uint8_t smoothingFactor = 30, uint16_t samplingIntv = 5)
    {
 
        _valuePtr1 = sigPtr;
        _updateIntv1 = _maxValue(10, updateIntv);
        _minMap = _maxValue(0, minMap);
        _maxMap = _maxValue(0, maxMap);
        _correctSwapOrEqualMinMax(_minMap, _maxMap);
        _param1 = constrain(smoothingFactor, 0, 100);
        _updateIntv2 = samplingIntv;
 
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _isRunning = true;
        _init = true;
        _currentFunc = &SBK_BarMeterAnimations::_followSignalSmooth;
        return *this;
    }

    SBK_BarMeterAnimations &followSignalWithPointer(const uint16_t *sigPtr, uint16_t updateIntv = 100, uint16_t minMap = 0, uint16_t maxMap = 1023, uint8_t smoothingFactor = 30, uint16_t samplingIntv = 5)
    {
        _valuePtr1 = sigPtr;
        _updateIntv1 = _maxValue(10, updateIntv);
        _minMap = _maxValue(0, minMap);
        _maxMap = _maxValue(0, maxMap);
        _correctSwapOrEqualMinMax(_minMap, _maxMap);
        _param1 = constrain(smoothingFactor, 0, 100);
        _updateIntv2 = samplingIntv;
 
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _isRunning = true;
        _init = true;
        _currentFunc = &SBK_BarMeterAnimations::_followSignalWithPointer;
        return *this;
    }

    SBK_BarMeterAnimations &followDualSignalFromCenter(const uint16_t *sig1Ptr, uint16_t updateIntv = 100, const uint16_t *sig2Ptr = nullptr, uint16_t minMap = 0, uint16_t maxMap = 1023, uint8_t smoothingFactor = 30, uint16_t samplingIntv = 5)
    {
        _valuePtr1 = sig1Ptr;
        _updateIntv1 = _maxValue(10, updateIntv);
        _valuePtr2 = sig2Ptr ? sig2Ptr : sig1Ptr;
        _minMap = _maxValue(0, minMap);
        _maxMap = _maxValue(0, maxMap);
        _correctSwapOrEqualMinMax(_minMap, _maxMap);
        _param1 = constrain(smoothingFactor, 0, 100);
        _updateIntv2 = samplingIntv;
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        //_mirrorHalfRangeDir = false;
        _isRunning = true;
        _init = true;
        _currentFunc = &SBK_BarMeterAnimations::_followDualSignalCenterMirror;
        return *this;
    }

    SBK_BarMeterAnimations &followDualSignalFromEdges(const uint16_t *sig1Ptr, uint16_t updateIntv = 100, const uint16_t *sig2Ptr = nullptr, uint16_t minMap = 0, uint16_t maxMap = 1023, uint8_t smoothingFactor = 30, uint16_t samplingIntv = 5)
    {
        _valuePtr1 = sig1Ptr;
        _updateIntv1 = _maxValue(10, updateIntv);
        _valuePtr2 = sig2Ptr ? sig2Ptr : sig1Ptr;
        _minMap = _maxValue(0, minMap);
        _maxMap = _maxValue(0, maxMap);
        _correctSwapOrEqualMinMax(_minMap, _maxMap);
        _param1 = constrain(smoothingFactor, 0, 100);
        _updateIntv2 = samplingIntv;
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = true;
        _AnimInitLogicIsInverted = false;
        //_mirrorHalfRangeDir = true;
        _isRunning = true;
        _init = true;
        _currentFunc = &SBK_BarMeterAnimations::_followDualSignalCenterMirror;
        return *this;
    }

    SBK_BarMeterAnimations &followSignalFloatingPeak(const uint16_t *sigPtr, uint8_t peakHoldTime = 20, uint16_t updateIntv = 100, uint16_t minMap = 0, uint16_t maxMap = 1023, uint8_t smoothingFactor = 30, uint16_t samplingIntv = 5)
    {
 
        _valuePtr1 = sigPtr;
        _updateIntv3 = _maxValue(20, peakHoldTime);
        _updateIntv1 = _maxValue(10, updateIntv);
        _minMap = _maxValue(0, minMap);
        _maxMap = _maxValue(0, maxMap);
        _correctSwapOrEqualMinMax(_minMap, _maxMap);
        _param1 = constrain(smoothingFactor, 0, 100);
        _updateIntv2 = samplingIntv;
 
        _isNonInvertingLogicAnim = true;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _isRunning = true;
        _init = true;
        _currentFunc = &SBK_BarMeterAnimations::_followSignalFloatingPeak;
        return *this;
    }

    SBK_BarMeterAnimations &randomFill(uint16_t interval = 30)
    {
        _updateIntv1 = interval;
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = false;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_randomPixelUpdater;
        _init = true;
        return *this;
    }

    SBK_BarMeterAnimations &randomEmpty(uint16_t interval = 30)
    {
        _updateIntv1 = interval;
 
        _isNonInvertingLogicAnim = false;
        _animRenderDirIsReversed = false;
        _AnimInitLogicIsInverted = true;
        _isRunning = true;
        _currentFunc = &SBK_BarMeterAnimations::_randomPixelUpdater;
        _init = true;
        return *this;
    }
 
protected:
    BarMeterT &_barMeter;
    uint8_t _segsNum = 0;
 
    // Active animation update function
    using AnimUpdateFn = bool (SBK_BarMeterAnimations::*)();
    AnimUpdateFn _currentFunc = nullptr;
 
    static constexpr uint8_t QUEUE_CAPACITY = SBK_BARDRIVE_QUEUE_CAPACITY;
    struct QueueEntry
    {
        AnimUpdateFn function = nullptr;
        uint16_t updateIntv1 = 10, updateIntv2 = 10, updateIntv3 = 10;
        uint16_t minMap = 0, maxMap = 1023;
        const void *valuePtr1 = nullptr;
        const void *valuePtr2 = nullptr;
        int8_t minTracker = 0, maxTracker = 1;
        uint8_t param1 = 0, param2 = 0, param3 = 0, param4 = 0, param5 = 0;
        bool loop = false;
        bool animInitLogicIsInverted = false;
        bool animRenderLogicIsInverted = false;
        bool isNonInvertingLogicAnim = false;
        bool mirrorHalfRangeDir = false;
        bool animLogicSet = false;
        bool animRenderDirIsReversed = false;
        bool animInitDirIsReversed = false;
        bool animDirSet = false;
        bool usePtr = false;
        bool emittingBlocksEnabled = true;
        bool waitTrailingSpace = false;
        bool resetRuntimeState = true;
        uint32_t duration = 0;
        uint32_t blockEmissionStopAfter = 0;
    };
    QueueEntry _queue[QUEUE_CAPACITY];
    uint8_t _queueHead = 0;
    uint8_t _queueTail = 0;
    uint8_t _queueCount = 0;
    uint8_t _queueStoredCount = 0;
    uint8_t _queueStart = 0;
    bool _queueLoop = false;
    uint8_t _currentQueueIndex = NO_QUEUE_INDEX;
    bool _queueActive = false;
    bool _queueOverflow = false;
    uint32_t _queueEntryDuration = 0;
    uint32_t _queueEntryStartedAt = 0;
    uint32_t _activeBlockEmissionStopAfter = 0;
    bool _queueEntryTimingPending = false;
 
    // Control flags
    bool _init = true; // true = init function
    bool _isRunning = false;
    bool _isPaused = false;
    bool _loop = false;
    bool _isLoopingNow = false;
    bool _AnimInitLogicIsInverted = false;
    bool _animRenderLogicIsInverted = false;
    bool _prevAnimRenderLogic = false;
    bool _isNonInvertingLogicAnim = false;
    bool _mirrorHalfRangeDir = false;
    bool _animLogicSet = false;
    bool _skipPending = false;
    bool _animRenderDirIsReversed = false;
    bool _AnimInitDirIsReversed = false;
    bool _animDirSet = false;
    bool _usePtr = false;
    bool _emittingBlocksEnabled = true;
    bool _waitTrailingSpace = false;
    bool _trailingSpacePending = false;
    uint32_t _animationDuration = 0;
    uint32_t _blockEmissionStopAfter = 0;
 
    // Time trackings
    uint32_t _currentTime = 0;
    uint32_t _pausedAt = 0;
    uint32_t _pausedTime = 0;
    uint32_t _lastUpdate1 = 0, _lastUpdate2 = 0, _lastUpdate3 = 0;
 
    // Animations update interval trackers
    uint16_t _updateIntv1 = 10, _updateIntv2 = 10, _updateIntv3 = 10;
 
    // Animations trackers
    uint8_t _sequenceState = 0;
    int8_t _ledTracker1 = 0, _ledTracker2 = 0, _ledTracker3 = 0;
    int8_t _minTracker = 0, _maxTracker = 1;
    uint8_t _param1 = 0, _param2 = 0, _param3 = 0, _param4 = 0, _param5 = 0;
    uint16_t _smoothedValue1 = 0, _smoothedValue2 = 0;
    uint16_t _minMap = 0, _maxMap = 1023;
    uint8_t _counter1 = 0, _counter2 = 0;
    // Generic live-value pointers. Their type is determined by the active animation.
    const void *_valuePtr1 = nullptr, *_valuePtr2 = nullptr;
    // Blocks related helpers
    struct Block
    {
        Block() : position(-1), active(false) {}
        int8_t position;
        bool active;
    };
    static constexpr uint8_t MAX_BLOCK_CAPACITY = 64;
    Block *_animationWorkspace = nullptr;
    uint8_t _segmentCapacity = 0;
    uint8_t _blockCapacity = 0;
    uint8_t _randomCursor = 0;
 
    void _captureQueueEntry(QueueEntry &entry, bool resetRuntimeState,
                            uint32_t duration)
    {
        entry.function = _currentFunc;
        entry.updateIntv1 = _updateIntv1;
        entry.updateIntv2 = _updateIntv2;
        entry.updateIntv3 = _updateIntv3;
        entry.minMap = _minMap;
        entry.maxMap = _maxMap;
        entry.valuePtr1 = _valuePtr1;
        entry.valuePtr2 = _valuePtr2;
        entry.minTracker = _minTracker;
        entry.maxTracker = _maxTracker;
        entry.param1 = _param1;
        entry.param2 = _param2;
        entry.param3 = _param3;
        entry.param4 = _param4;
        entry.param5 = _param5;
        entry.loop = _loop;
        entry.animInitLogicIsInverted = _AnimInitLogicIsInverted;
        entry.animRenderLogicIsInverted = _animRenderLogicIsInverted;
        entry.isNonInvertingLogicAnim = _isNonInvertingLogicAnim;
        entry.mirrorHalfRangeDir = _mirrorHalfRangeDir;
        entry.animLogicSet = _animLogicSet;
        entry.animRenderDirIsReversed = _animRenderDirIsReversed;
        entry.animInitDirIsReversed = _AnimInitDirIsReversed;
        entry.animDirSet = _animDirSet;
        entry.usePtr = _usePtr;
        entry.emittingBlocksEnabled = _emittingBlocksEnabled;
        entry.waitTrailingSpace = _waitTrailingSpace;
        entry.resetRuntimeState = resetRuntimeState;
        entry.duration = duration;
        entry.blockEmissionStopAfter = _blockEmissionStopAfter;
    }
 
    void _loadQueueEntry(const QueueEntry &entry, bool forceReset = false)
    {
        const bool resetRuntimeState = forceReset || entry.resetRuntimeState;
        const bool previousRenderLogic = _animRenderLogicIsInverted;
 
        _currentFunc = entry.function;
        _updateIntv1 = entry.updateIntv1;
        _updateIntv2 = entry.updateIntv2;
        _updateIntv3 = entry.updateIntv3;
        _minMap = entry.minMap;
        _maxMap = entry.maxMap;
        _valuePtr1 = entry.valuePtr1;
        _valuePtr2 = entry.valuePtr2;
        _minTracker = entry.minTracker;
        _maxTracker = entry.maxTracker;
        _param1 = entry.param1;
        _param2 = entry.param2;
        _param3 = entry.param3;
        _param4 = entry.param4;
        if (resetRuntimeState)
            _param5 = entry.param5;
        _loop = entry.loop;
        _AnimInitLogicIsInverted = entry.animInitLogicIsInverted;
        _animRenderLogicIsInverted =
            (!resetRuntimeState && !entry.animLogicSet)
                ? entry.animInitLogicIsInverted
                : entry.animRenderLogicIsInverted;
        _prevAnimRenderLogic = resetRuntimeState
                                   ? entry.animRenderLogicIsInverted
                                   : previousRenderLogic;
        _isNonInvertingLogicAnim = entry.isNonInvertingLogicAnim;
        _mirrorHalfRangeDir = entry.mirrorHalfRangeDir;
        _animLogicSet = entry.animLogicSet;
        _animRenderDirIsReversed = entry.animRenderDirIsReversed;
        _AnimInitDirIsReversed = entry.animInitDirIsReversed;
        _animDirSet = entry.animDirSet;
        _usePtr = entry.usePtr;
        _emittingBlocksEnabled = entry.emittingBlocksEnabled;
        _waitTrailingSpace = entry.waitTrailingSpace;
        _trailingSpacePending = false;
        _queueEntryDuration = entry.duration;
        _activeBlockEmissionStopAfter = entry.blockEmissionStopAfter;
        _queueEntryTimingPending = true;
 
        _isRunning = _currentFunc != nullptr;
        resume();
        _isLoopingNow = false;
        _skipPending = false;
        if (resetRuntimeState)
        {
            _init = true;
            _sequenceState = 0;
            _ledTracker1 = _ledTracker2 = _ledTracker3 = 0;
            _counter1 = _counter2 = 0;
            _smoothedValue1 = _smoothedValue2 = 0;
            _lastUpdate1 = _lastUpdate2 = _lastUpdate3 = _currentTime;
        }
        else
        {
            _init = false;
        }
    }
 
    void _startNextQueuedAnimation(bool forceReset = false)
    {
        if (_queueCount == 0 && _queueLoop && _queueStoredCount > 0)
        {
            _queueHead = _queueStart;
            _queueCount = _queueStoredCount;
            forceReset = true;
        }
        if (_queueCount == 0)
        {
            _queueStoredCount = 0;
            _queueActive = false;
            _isRunning = false;
            _currentFunc = nullptr;
            _currentQueueIndex = NO_QUEUE_INDEX;
            _activeBlockEmissionStopAfter = 0;
            return;
        }
 
        _currentQueueIndex = _queueHead;
        _loadQueueEntry(_queue[_queueHead], forceReset);
        _queueHead = (_queueHead + 1) % QUEUE_CAPACITY;
        _queueCount--;
    }
 
    void _initializeStorage()
    {
        _segmentCapacity = _barMeter.getSegsNum();
        _segsNum = _segmentCapacity;
        _maxTracker = _segsNum > 0 ? _segsNum - 1 : 0;
 
        const uint16_t requestedCapacity = static_cast<uint16_t>(_segmentCapacity) + 2U;
        _blockCapacity = _minValue(requestedCapacity,
                             static_cast<uint16_t>(MAX_BLOCK_CAPACITY));
        const uint8_t randomOrderBlocks =
            (_segmentCapacity + sizeof(Block) - 1U) / sizeof(Block);
        const uint8_t workspaceBlocks = _maxValue(_blockCapacity, randomOrderBlocks);
        if (workspaceBlocks > 0)
            _animationWorkspace = new Block[workspaceBlocks];
    }
 
    uint8_t *_randomOrder()
    {
        return reinterpret_cast<uint8_t *>(_animationWorkspace);
    }
 
    void _resetBlocks(uint8_t &blockCapacity)
    {
        if (!_animationWorkspace)
        {
            blockCapacity = 0;
            return;
        }
        blockCapacity = _minValue(blockCapacity, _blockCapacity);
        for (uint8_t i = 0; i < blockCapacity; ++i)
            _animationWorkspace[i] = Block();
    }
 
    // Animation helpers
    // Arduino cores differ: AVR defines min/max macros, while ESP cores use
    // same-type templates. Preserve ordinary arithmetic promotion on all cores.
    template <typename A, typename B>
    static auto _minValue(A a, B b) -> decltype(true ? A() : B())
    {
        return a < b ? a : b;
    }
 
    template <typename A, typename B>
    static auto _maxValue(A a, B b) -> decltype(true ? A() : B())
    {
        return a > b ? a : b;
    }
 
    static inline void _normalizePercentRange(uint8_t &minP, uint8_t &maxP)
    {
        minP = constrain(minP, 0, 100);
        maxP = constrain(maxP, 0, 100);
        if (minP > maxP)
        {
            uint8_t t = maxP;
            maxP = minP;
            minP = t;
        }
        if (minP == maxP)
        {
            if (maxP < 100)
                maxP = minP + 1;
            else
                minP--;
        }
    }
    const uint8_t *_percentMaxPtr() const { return static_cast<const uint8_t *>(_valuePtr1); }
    const uint8_t *_percentMinPtr() const { return static_cast<const uint8_t *>(_valuePtr2); }
    const uint8_t *_liveBpmPtr() const { return static_cast<const uint8_t *>(_valuePtr1); }
    const uint16_t *_signalPtr1() const { return static_cast<const uint16_t *>(_valuePtr1); }
    const uint16_t *_signalPtr2() const { return static_cast<const uint16_t *>(_valuePtr2); }
 
    inline void _mapMinMaxTrackerFromPtr(const uint8_t *minPercPtr, const uint8_t *maxPercPtr, int8_t minR, uint8_t maxR)
    {
        if (!_usePtr)
            return;
        uint8_t minP = minPercPtr ? *minPercPtr : 0;
        uint8_t maxP = maxPercPtr ? *maxPercPtr : 100;
        _normalizePercentRange(minP, maxP);
        _minTracker = map(minP, 0, 100, minR, maxR);
        _maxTracker = map(maxP, 0, 100, minR, maxR);
    }
    inline void _mapMinMaxTracker(uint8_t minP, uint8_t maxP, uint8_t minR, uint8_t maxR)
    {
        _normalizePercentRange(minP, maxP);
        _minTracker = map(minP, 0, 100, minR, maxR);
        _maxTracker = map(maxP, 0, 100, minR, maxR);
    }
    inline uint8_t _corrPixelToDir(uint8_t pixel)
    {
        return _animRenderDirIsReversed ? (_segsNum - 1) - pixel : pixel;
    }
    inline uint8_t _corrPixelToDirForHalfRange(uint8_t pixel)
    {
        if (!_mirrorHalfRangeDir)
            return pixel;
 
        const uint8_t half = _segsNum / 2;
        return abs((half - 1) - pixel);
    }
    static inline void _correctSwapOrEqualMinMax(uint16_t &minVal, uint16_t &maxVal)
    {
        if (minVal > maxVal)
        {
            uint16_t temp = maxVal;
            maxVal = minVal;
            minVal = temp;
        }
        if (minVal == maxVal) // avoid division by zero in map()
        {
            if (maxVal < 65535)
            {
                maxVal = minVal + 1;
            }
            else
            {
                minVal--;
            }
        }
    }
    static inline uint8_t _getMappedSignal(uint16_t sig, uint16_t minM, uint16_t maxM, uint8_t minR, uint8_t maxR)
    {
        uint8_t mapped = map(sig, minM, maxM, minR, maxR);
        return constrain(mapped, minR, maxR); // avoid edge overshoot
    }
 
    // Animation update functions
 
    bool _setAllOn()
    {
        _init = false;
        for (uint8_t i = 0; i < _segsNum; i++)
            _barMeter.setPixel(i, true);
        return true;
    }
    bool _setAllOff()
    {
        _init = false;
        _barMeter.clear();
        return true;
    }
 
    bool _wait()
    {
        if (_init)
        {
            _init = false;
            _lastUpdate1 = _currentTime;
        }
        return _currentTime - _lastUpdate1 >= _updateIntv1;
    }
 
    bool _blinkPixel()
    {
        const uint8_t index = _param1;
        const uint8_t blinkCount = _param2;
 
        if (index >= _segsNum)
            return true;
 
        if (_init)
        {
            _init = false;
            _sequenceState = 1; // ON phase
            _counter1 = 0;
            _lastUpdate1 = _currentTime;
            _barMeter.setPixel(index, true);
            return false;
        }
 
        const uint16_t interval = _sequenceState ? _updateIntv1 : _updateIntv2;
        if (_currentTime - _lastUpdate1 < interval)
            return false;
 
        _lastUpdate1 = _currentTime;
        if (_sequenceState)
        {
            _sequenceState = 0;
            _barMeter.setPixel(index, false);
            _counter1++;
            return blinkCount > 0 && _counter1 >= blinkCount;
        }
 
        _sequenceState = 1;
        _barMeter.setPixel(index, true);
        return false;
    }
 
    bool _fillOrEmpty()
    {
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), 0, _segsNum - 1);
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            // Pre-fill for emptyDown mode
            if (_animRenderLogicIsInverted)
            {
                _ledTracker1 = _maxTracker;
                for (uint8_t i = 0; i < _segsNum; ++i)
                {
                    if (i <= _maxTracker)
                        _barMeter.setPixel(_corrPixelToDir(i), true);
                    else
                        _barMeter.setPixel(_corrPixelToDir(i), false);
                }
            }
            else // Pre-fill fillUp, light up to _minTracker inclusively
            {
                _ledTracker1 = _minTracker;
                for (uint8_t i = 0; i < _segsNum; ++i)
                {
                    if (i <= _minTracker)
                        _barMeter.setPixel(_corrPixelToDir(i), true);
                    else
                        _barMeter.setPixel(_corrPixelToDir(i), false);
                }
            }
            return false;
        }
 
        if (_animRenderLogicIsInverted != _prevAnimRenderLogic)
        {
            _prevAnimRenderLogic = _animRenderLogicIsInverted;
 
            //  Clamp if inverted logic and tracker is beyond maxTracker
            if (_animRenderLogicIsInverted && _ledTracker1 > _maxTracker)
                _ledTracker1 = _maxTracker;
 
            // Clamp in normal logic mode
            if (!_animRenderLogicIsInverted && _ledTracker1 < _minTracker)
                _ledTracker1 = _minTracker;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            if (_animRenderLogicIsInverted)
            {
                if (_ledTracker1 >= _minTracker && _ledTracker1 < _segsNum)
                {
                    _barMeter.setPixel(_corrPixelToDir(_ledTracker1), false);
                    _ledTracker1--;
                }
                else
                    return true; // now done!
            }
            else
            {
                if (_ledTracker1 <= _maxTracker && _ledTracker1 < _segsNum)
                {
                    _barMeter.setPixel(_corrPixelToDir(_ledTracker1), true);
                    _ledTracker1++;
                }
                else
                    return true; // done lighting up all
            }
        }
        return false;
    }
 
    bool _bounceFill()
    {
        switch (_sequenceState)
        {
        case 0: // Fill Up
 
            _skipPending = false;
            if (_fillOrEmpty())
            {
                _animRenderLogicIsInverted = !_AnimInitLogicIsInverted;
                _sequenceState = 1;
                _updateIntv1 = _updateIntv3; // Empty update interval
            }
            return false;
 
        case 1: // Fill Down
 
            _skipPending = true;
            if (_fillOrEmpty())
            {
                _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
                _sequenceState = 0;
                _updateIntv1 = _updateIntv2; // Fill up  update interval
                return true;
            }
            return false;
        }
 
        return true; // Shouldn’t reach here
    }
 
    bool _fillFromOrEmptyToCenter()
    {
        const uint8_t center = _segsNum / 2;
        _mapMinMaxTrackerFromPtr(_percentMinPtr(), _percentMaxPtr(), center - 1, 0);
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            if (_animRenderLogicIsInverted)
            {
                _ledTracker1 = _maxTracker;
 
                // Start fully lit
                for (uint8_t i = 0; i < center; ++i)
                {
                    if (i >= _maxTracker)
                    {
                        _barMeter.setPixel(_corrPixelToDirForHalfRange(i), true);
                        _barMeter.setPixel((_segsNum - 1) - _corrPixelToDirForHalfRange(i), true);
                    }
                    else
                    {
                        _barMeter.setPixel(_corrPixelToDirForHalfRange(i), false);
                        _barMeter.setPixel((_segsNum - 1) - _corrPixelToDirForHalfRange(i), false);
                    }
                }
            }
            else
            {
 
                _ledTracker1 = _minTracker;
 
                // Start with minimum fill
                for (uint8_t i = 0; i < center; ++i)
                {
                    if (i > _minTracker)
                    {
                        _barMeter.setPixel(_corrPixelToDirForHalfRange(i), true);
                        _barMeter.setPixel((_segsNum - 1) - _corrPixelToDirForHalfRange(i), true);
                    }
                    else
                    {
                        _barMeter.setPixel(_corrPixelToDirForHalfRange(i), false);
                        _barMeter.setPixel((_segsNum - 1) - _corrPixelToDirForHalfRange(i), false);
                    }
                }
            }
            return false;
        }
 
        if (_animRenderLogicIsInverted != _prevAnimRenderLogic)
        {
            _prevAnimRenderLogic = _animRenderLogicIsInverted;
 
            // A completed phase leaves the tracker one step past its endpoint.
            // Move it back into the active range before reversing direction.
            if (_animRenderLogicIsInverted && _ledTracker1 < _maxTracker)
                _ledTracker1 = _maxTracker;
            if (!_animRenderLogicIsInverted && _ledTracker1 > _minTracker)
                _ledTracker1 = _minTracker;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
            if (!_animRenderLogicIsInverted)
            {
                if (_ledTracker1 >= _maxTracker && _ledTracker1 >= 0)
                {
                    _barMeter.setPixel(_corrPixelToDirForHalfRange(_ledTracker1), true);
                    _barMeter.setPixel((_segsNum - 1) - _corrPixelToDirForHalfRange(_ledTracker1), true);
                    _ledTracker1--;
                }
                else
                    return true; // finished filling
            }
            else
            {
                if (_ledTracker1 <= _minTracker && _ledTracker1 < center)
                {
                    _barMeter.setPixel(_corrPixelToDirForHalfRange(_ledTracker1), false);
                    _barMeter.setPixel((_segsNum - 1) - _corrPixelToDirForHalfRange(_ledTracker1), false);
                    _ledTracker1++;
                }
                else
                    return true; // finished clearing
            }
        }
 
        return false;
    }
 
    bool _bounceFillHalfRangeMirrorCenter()
    {
        switch (_sequenceState)
        {
        case 0: // Fill from center
 
            _skipPending = true;
            if (_fillFromOrEmptyToCenter())
            {
                _animRenderLogicIsInverted = !_AnimInitLogicIsInverted;
                _updateIntv1 = _updateIntv3; // Empty update interval
                _sequenceState = 1;
            }
            return false;
 
        case 1: // Empty to center
 
            _skipPending = false;
            if (_fillFromOrEmptyToCenter())
            {
                _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
                _updateIntv1 = _updateIntv2; // Empty update interval
                _sequenceState = 0;
                return true; // one full bounce cycle completed
            }
            return false;
        }
 
        return true; // should not happen
    }
 
#define bpm _param1
#define MIN_BASE_LEVEL _param2
#define MIN_PEAK_LEVEL _param3
#define PEAK_HOLD_TIME _param4
#define bpmPtr _liveBpmPtr()
#define currentLevel _ledTracker1
#define peakLevel _ledTracker2
#define beat _updateIntv1
#define lastBeat _lastUpdate1
#define lastRandomUpdate _lastUpdate2
#define prevPeakUpdate _lastUpdate3
    bool _beatPulse() // bouncing from bottom (maybe like a volume meter with the music)
    {
        static int8_t randomOffset;
        static bool isPeak = false;
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _setAllOff();
            currentLevel = MIN_BASE_LEVEL;
            peakLevel = MIN_PEAK_LEVEL;
        }
 
        // Update at bpm pulse
        if (_currentTime - lastBeat >= beat)
        {
            lastBeat = _currentTime;
            isPeak = !isPeak; // Toggle between peak and base level
        }
 
        // Smooth transition between base and peak levels
        if (isPeak && currentLevel <= MIN_PEAK_LEVEL)
        {
            currentLevel += random(3, 5); // Gradual increase
        }
        else if (!isPeak && currentLevel >= MIN_BASE_LEVEL)
        {
            currentLevel -= random(0, 4); // Gradual decrease
        }
 
        // Randomized additional LEDs on top at a random interval
        if (_currentTime - lastRandomUpdate >= uint16_t(random(50, 300)))
        {
            lastRandomUpdate = _currentTime;
            randomOffset = random(-4, 4); // 0 to 5 extra LEDs
        }
 
        uint8_t finalLevel = currentLevel + randomOffset;
        finalLevel = constrain(finalLevel, 0, _segsNum);
        if (finalLevel > _segsNum)
            finalLevel = _segsNum;
        if (finalLevel < 0)
            finalLevel = 0;
 
        // Update peak level
        if (finalLevel > peakLevel)
        {
            peakLevel = _minValue(finalLevel, _segsNum - 1);
            prevPeakUpdate = _currentTime; // Reset decay timer
        }
        else if (_currentTime - prevPeakUpdate >= PEAK_HOLD_TIME && peakLevel > finalLevel)
        {
            peakLevel--;                   // Slowly drop peak
            prevPeakUpdate = _currentTime; // Reset decay timer
        }
 
        // Update LED states
        for (uint8_t i = 0; i < _segsNum; i++)
        {
            _barMeter.setPixel(_corrPixelToDir(i), (i < finalLevel));
        }
 
        // Ensure peak LED stays on
        if (peakLevel < _segsNum)
        {
            _barMeter.setPixel(_corrPixelToDir(peakLevel), true);
        }
        return false; // Continuous pulse animation, never auto-terminates
    }
 
    bool _beatPulseLive()
    {
        bpm = bpmPtr ? _maxValue(1, *bpmPtr) : 116;
        beat = 60000UL / bpm;
        return _beatPulse();
    }
#undef bpm
#undef MIN_BASE_LEVEL
#undef MIN_PEAK_LEVEL
#undef PEAK_HOLD_TIME
#undef bpmPtr
#undef currentLevel
#undef peakLevel
#undef beat
#undef lastBeat
#undef lastRandomUpdate
#undef prevPeakUpdate
 
#define blockLength _param1
#define blockSpacing _param2
#define requestedNumBlocks _param3
#define maxBlocks _param4
#define emitIndex _param5
#define emittedBlocksCount _counter1
#define emitCooldown _counter2
    bool _blocksComplete()
    {
        if ((requestedNumBlocks == 0 || emittedBlocksCount < requestedNumBlocks) && _emittingBlocksEnabled)
        {
            _trailingSpacePending = false;
            return false;
        }
        for (uint8_t i = 0; i < maxBlocks; ++i)
        {
            if (_animationWorkspace[i].active)
            {
                _trailingSpacePending = false;
                return false;
            }
        }
        if (!_waitTrailingSpace || blockSpacing == 0)
            return true;
        if (!_trailingSpacePending)
        {
            // These block animations do not otherwise use the second timer.
            _lastUpdate2 = _currentTime;
            _trailingSpacePending = true;
        }
        return _currentTime - _lastUpdate2 >= static_cast<uint32_t>(blockSpacing) * _updateIntv1;
    }
 
    void _emitBlock(int8_t pos)
    {
        if (!_animationWorkspace || maxBlocks < 1)
            return;
 
        if (emitCooldown > 0)
        {
            emitCooldown--;
            return;
        }
 
        if (requestedNumBlocks > 0 && emittedBlocksCount >= requestedNumBlocks)
            return;
 
        for (uint8_t i = 0; i < maxBlocks; ++i)
        {
            uint8_t idx = (emitIndex + i) % maxBlocks;
            Block &b = _animationWorkspace[idx];
 
            if (!b.active)
            {
                b.position = pos;
                b.active = true;
                emittedBlocksCount++;
 
                emitCooldown = blockLength + blockSpacing - 1;
                emitIndex = (emitIndex + 1) % maxBlocks;
                return;
            }
        }
    }
 
    static inline int8_t _calculateSwitchPosition(int8_t pos, uint8_t blockL, uint8_t range)
    {
        // Compute switched block head position
        return (range - 1) - pos + (blockL - 1);
    }
 
    int8_t _calculateSwitchedEmitTickCounter(uint8_t range)
    {
        const int8_t emitInterval = blockLength + blockSpacing;
 
        int8_t closestSwp = -127; // Track the nearest visible block from new side
 
        for (uint8_t i = 0; i < maxBlocks; ++i)
        {
            Block &b = _animationWorkspace[i];
 
            if (!b.active)
                continue;
 
            int8_t p = b.position; // head position before switching
 
            // Step 1: compute switched block head position
            int8_t swp = _calculateSwitchPosition(p, blockLength, range);
 
            b.position = swp;
 
            // Step 2: if out of visible range, deactivate block
            if (swp < 0)
            {
                b.active = false;
                continue;
            }
 
            // // Step 3: Keep the first (closest to emit side) visible block
            if (closestSwp == -127 || swp < closestSwp)
                closestSwp = swp;
        }
 
        if (closestSwp >= 0)
            return (emitInterval - 1) - closestSwp;
        else
            return 0; // fallback if no visible block found
    }
 
    bool _mirrorBlocks()
    {
        const uint8_t center = _segsNum / 2;
 
        if (_init)
        {
            _init = false;
            _trailingSpacePending = false;
            _emittingBlocksEnabled = true;
 
            emittedBlocksCount = 0;
            emitCooldown = 0;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _resetBlocks(maxBlocks);
            return false;
        }
 
        if (_prevAnimRenderLogic != _animRenderLogicIsInverted)
        {
            emitCooldown = _calculateSwitchedEmitTickCounter(_segsNum / 2);
            emittedBlocksCount = requestedNumBlocks;
            _prevAnimRenderLogic = _animRenderLogicIsInverted;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
            // _frameCounter++;
            _barMeter.clear();
 
            if ((requestedNumBlocks == 0 || emittedBlocksCount < requestedNumBlocks) && _emittingBlocksEnabled)
                _emitBlock(-1); // The new block moves to position 0 on its first update.
 
            for (uint8_t i = 0; i < maxBlocks; ++i)
            {
                Block &b = _animationWorkspace[i];
                if (!b.active)
                    continue;
 
                b.position++;
 
                // Only render to lower half (0 to _centerTracker - 1)
                uint16_t clamped = _maxValue(0, (int16_t)b.position + 1);
                uint8_t pixelsVisible = _minValue(blockLength, (uint8_t)clamped);
                for (uint8_t j = 0; j < pixelsVisible; ++j)
                {
                    int8_t pos = _animRenderLogicIsInverted ? center - 1 - b.position : b.position;
                    int8_t tailOffset = _animRenderLogicIsInverted ? pos + j : pos - j;
 
                    if (tailOffset < 0)
                        continue;
 
                    int8_t idx = tailOffset;
                    if (idx >= center)
                        continue;
 
                    int8_t mirrorIdx = _segsNum - 1 - idx;
 
                    if (idx >= 0 && idx < _segsNum)
                    {
                        _barMeter.setPixel(idx, true);
                    }
                    if (mirrorIdx != idx && mirrorIdx >= 0 && mirrorIdx < _segsNum)
                    {
                        _barMeter.setPixel(mirrorIdx, true);
                    }
                }
 
                // Deactivate block if head has passed the visual range
                if (b.position >= center - 1 + blockLength)
                    b.active = false;
            }
        }
        // The animation ends after emission stops and all active blocks have cleared.
        return _blocksComplete();
    }
 
    bool _scrollingBlocks()
    {
        if (_init)
        {
            _init = false;
            _trailingSpacePending = false;
            _emittingBlocksEnabled = true;
 
            emittedBlocksCount = 0;
            emitCooldown = 0;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _resetBlocks(maxBlocks);
            return false;
        }
 
        if (_prevAnimRenderLogic != _animRenderLogicIsInverted)
        {
            emitCooldown = _calculateSwitchedEmitTickCounter(_segsNum);
            emittedBlocksCount = requestedNumBlocks;
            _prevAnimRenderLogic = _animRenderLogicIsInverted;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
            _setAllOff();
 
            if ((requestedNumBlocks == 0 || emittedBlocksCount < requestedNumBlocks) && _emittingBlocksEnabled)
                _emitBlock(-1); // Start fully off-screen left
 
            for (uint8_t i = 0; i < maxBlocks; ++i)
            {
                Block &b = _animationWorkspace[i];
                if (!b.active)
                    continue;
 
                b.position++;
 
                for (uint8_t j = 0; j < blockLength; ++j)
                {
                    int8_t pos = _animRenderLogicIsInverted ? (_segsNum - 1) - b.position : b.position;
                    int8_t tailOffset = _animRenderLogicIsInverted ? pos + j : pos - j;
 
                    if (tailOffset < 0)
                        continue;
 
                    int8_t idx = tailOffset;
                    if (idx >= _segsNum)
                        continue;
 
                    if (idx >= 0 && idx < _segsNum)
                        _barMeter.setPixel(_corrPixelToDir(idx), true);
                }
 
                // Deactivate block if head has passed the visual range
                if (b.position >= (_segsNum - 1) + blockLength)
                    b.active = false;
            }
        }
 
        return _blocksComplete();
    }
 
#define stackLevel _ledTracker1
    bool _stackingBlocks()
    {
        const uint8_t blockInterval = blockLength + blockSpacing;
        bool hasActive = false; // active block tracker
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            maxBlocks = 1;
            _resetBlocks(maxBlocks);
 
            emitIndex = 0;
            emitCooldown = 0;
 
            stackLevel = 0;
            if (!_animRenderLogicIsInverted)
            {
                _barMeter.clear();
                // Falling blocks
                // stackLevel = 0;
            }
            else
            {
                // Flying upward - fill pattern first
                while (stackLevel < _segsNum)
                    stackLevel += blockInterval;
                for (uint8_t i = 0; i < stackLevel; i++)
                {
                    if ((i % blockInterval) < blockLength)
                        _barMeter.setPixel(_corrPixelToDir(i), true);
                    else
                        _barMeter.setPixel(_corrPixelToDir(i), false);
                }
            }
 
            return false;
        }
 
        if (_animRenderLogicIsInverted != _prevAnimRenderLogic)
        {
            _prevAnimRenderLogic = _animRenderLogicIsInverted;
            if (_animRenderLogicIsInverted)
                stackLevel += blockInterval;
            else
                stackLevel -= blockInterval;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            // Only clear pixels of active blocks, not the whole bar
            for (uint8_t i = 0; i < maxBlocks; ++i)
            {
                Block &b = _animationWorkspace[i];
                if (!b.active)
                    continue;
 
                for (uint8_t j = 0; j < blockLength; ++j)
                {
                    int8_t seg = b.position + j;
                    if (seg >= 0 && seg < _segsNum)
                        _barMeter.setPixel(_corrPixelToDir(seg), false);
                }
            }
 
            // Emit one block if none active
            for (uint8_t i = 0; i < maxBlocks; ++i)
            {
                if (_animationWorkspace[i].active)
                {
                    hasActive = true;
                    break;
                }
            }
            if (!hasActive)
            {
                emitCooldown = 0; // emit blocks on demand
                if (!_animRenderLogicIsInverted && stackLevel <= _segsNum)
                    _emitBlock(_segsNum); // fall from top
                else if (_animRenderLogicIsInverted && stackLevel >= 0)
                    _emitBlock(stackLevel - blockInterval);
            }
 
            // Update and draw all active blocks
            for (uint8_t i = 0; i < maxBlocks; ++i)
            {
                Block &b = _animationWorkspace[i];
                if (!b.active)
                    continue;
 
                // Clear trailing pixel of previous frame
                int8_t clearPos = b.position;
                if (clearPos >= 0 && clearPos < _segsNum)
                    _barMeter.setPixel(_corrPixelToDir(clearPos), false);
 
                // Move block
                if (!_animRenderLogicIsInverted)
                    b.position--;
                else
                    b.position++;
 
                for (uint8_t j = 0; j < blockLength; ++j)
                {
                    int8_t seg = b.position + j;
                    if (seg >= 0 && seg < _segsNum)
                        _barMeter.setPixel(_corrPixelToDir(seg), true);
                }
 
                if (!_animRenderLogicIsInverted)
                {
                    if (b.position <= stackLevel)
                    {
                        stackLevel += blockInterval;
                        b.active = false;
                    }
                }
                else
                {
                    if (b.position >= _segsNum)
                    {
                        stackLevel -= blockInterval;
                        b.active = false;
                    }
                }
            }
 
            // Draw base for stacking
            if (stackLevel == 0)
            {
                _barMeter.setPixel(_corrPixelToDir(0), false);
            }
            if (!_animRenderLogicIsInverted)
            {
                for (int8_t i = 0; i < stackLevel - blockInterval; ++i)
                {
                    if ((i % blockInterval) < blockLength)
                        _barMeter.setPixel(_corrPixelToDir(i), true);
                    else
                        _barMeter.setPixel(_corrPixelToDir(i), false);
                }
            }
            else
            {
                for (uint8_t i = 0; i < stackLevel - blockInterval; i++)
                {
                    if ((i % blockInterval) < blockLength)
                        _barMeter.setPixel(_corrPixelToDir(i), true);
                    else
                        _barMeter.setPixel(_corrPixelToDir(i), false);
                }
            }
            if (!_animRenderLogicIsInverted)
            {
                if (stackLevel >= _segsNum - 1 && !hasActive)
                    return true;
            }
            else
            {
                if (stackLevel <= 0 && !hasActive)
                    return true;
            }
        }
        return false;
    }
#undef stackLevel
#undef blockLength
#undef blockSpacing
#undef requestedNumBlocks
#undef maxBlocks
#undef emitIndex
#undef emittedBlocksCount
#undef emitCooldown
 
#define smoothingFactor _param1
    bool _followSignalSmooth()
    {
        if (!_signalPtr1())
        {
            _setAllOff();
            return true;
        }
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _smoothedValue1 = *_signalPtr1();
            _lastUpdate1 = _currentTime;
            _setAllOff();
            return false;
        }
 
        // Signal sampling
        if (_currentTime - _lastUpdate2 >= _updateIntv2)
        {
            uint16_t raw = *_signalPtr1();
            _smoothedValue1 = (raw * smoothingFactor + _smoothedValue1 * (100 - smoothingFactor)) / 100;
            _lastUpdate2 = _currentTime;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            uint8_t level = _getMappedSignal(_smoothedValue1, _minMap, _maxMap, 0, _segsNum);
 
            for (uint8_t i = 0; i < _segsNum; i++)
            {
                _barMeter.setPixel(_corrPixelToDir(i), i < level);
            }
        }
        return false; // continuous animation
    }
    bool _followSignalWithPointer()
    {
        if (!_signalPtr1())
        {
            _setAllOff();
            return true;
        }
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _smoothedValue1 = *_signalPtr1();
            _lastUpdate1 = _currentTime;
            _setAllOff();
            return false;
        }
 
        // Signal sampling
        if (_currentTime - _lastUpdate2 >= _updateIntv2)
        {
            uint16_t raw = *_signalPtr1();
            _smoothedValue1 = (raw * smoothingFactor + _smoothedValue1 * (100 - smoothingFactor)) / 100;
            _lastUpdate2 = _currentTime;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            uint8_t avg = _getMappedSignal(_smoothedValue1, _minMap, _maxMap, 0, _segsNum);
            uint8_t pointer = _getMappedSignal(*_signalPtr1(), _minMap, _maxMap, 0, _segsNum);
 
            // First, fill up to moving average
            for (uint8_t i = 0; i < _segsNum; i++)
            {
                _barMeter.setPixel(_corrPixelToDir(i), i < avg);
            }
 
            // Then selectively clear area around pointer
            if (pointer < avg && pointer > 0)
                _barMeter.setPixel(_corrPixelToDir(pointer - 1), false); // clear just below if pointer is inside the fill
 
            if (pointer < avg - 2)
                _barMeter.setPixel(_corrPixelToDir(pointer + 1), false); // clear just above
 
            // Finally, show the pointer
            _barMeter.setPixel(_corrPixelToDir(pointer), true);
        }
        return false; // continuous animation
    }
    bool _followDualSignalCenterMirror()
    {
        if (!_signalPtr1() && !_signalPtr2())
        {
            _setAllOff();
            return true;
        }
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _mirrorHalfRangeDir = _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _smoothedValue1 = *_signalPtr1();
            if (_signalPtr2())
                _smoothedValue2 = *_signalPtr2();
            _lastUpdate1 = _currentTime;
            _setAllOff();
            return false;
        }
 
        if (_animRenderLogicIsInverted != _prevAnimRenderLogic)
            _prevAnimRenderLogic = _animRenderLogicIsInverted;
 
        // Signals sampling
        if (_currentTime - _lastUpdate2 >= _updateIntv2)
        {
            _lastUpdate2 = _currentTime;
 
            uint16_t raw1 = *_signalPtr1();
            _smoothedValue1 = (uint16_t)(((uint32_t)smoothingFactor * raw1 + (uint32_t)(100 - smoothingFactor) * _smoothedValue1) / 100);
 
            if (_signalPtr2())
            {
                uint16_t raw2 = *_signalPtr2();
                _smoothedValue2 = (uint16_t)(((uint32_t)smoothingFactor * raw2 + (uint32_t)(100 - smoothingFactor) * _smoothedValue2) / 100);
            }
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            uint16_t raw1 = *_signalPtr1();
            _smoothedValue1 = (uint16_t)(((uint32_t)smoothingFactor * raw1 + (uint32_t)(100 - smoothingFactor) * _smoothedValue1) / 100);
            uint8_t level1 = _getMappedSignal(_smoothedValue1, _minMap, _maxMap, 0, _segsNum / 2);
 
            uint8_t level2 = level1;
            if (_signalPtr2())
                level2 = _getMappedSignal(_smoothedValue2, _minMap, _maxMap, 0, _segsNum / 2);
 
            for (uint8_t i = 0; i < _segsNum; i++)
            {
                //_barMeter.setPixel(_corrPixelToDirForHalfRange(i), i >= (_segsNum / 2 - 1) - level1 && i <= ((_segsNum / 2) + level2));
                if (_animRenderLogicIsInverted)
                    _barMeter.setPixel(i, i < (_segsNum / 2 - 1) - level1 || i > ((_segsNum / 2) + level2));
                else
                    _barMeter.setPixel(i, i >= (_segsNum / 2 - 1) - level1 && i <= ((_segsNum / 2) + level2));
            }
        }
        return false; // continuous animation
    }
 
#define currentLevel _ledTracker1
#define peakLevel _ledTracker3
#define baseUpdate _updateIntv1
#define lastBaseUpdate _lastUpdate1
#define peakHoldTime _updateIntv3
#define lastPeakUpdate _lastUpdate3
    bool _followSignalFloatingPeak() // bouncing from bottom (maybe like a volume meter with the music)
    {
 
        if (!_signalPtr1())
        {
            _setAllOff();
            return true;
        }
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            _setAllOff();
            _smoothedValue1 = *_signalPtr1();
            lastBaseUpdate = _currentTime;
            lastPeakUpdate = _currentTime;
            currentLevel = 0;
            peakLevel = 0;
            return false;
        }
 
        // Signal smoothing update
        if (_currentTime - _lastUpdate2 >= _updateIntv2)
        {
            _lastUpdate2 = _currentTime;
 
            uint16_t raw = *_signalPtr1();
            _smoothedValue1 = (raw * smoothingFactor + _smoothedValue1 * (100 - smoothingFactor)) / 100;
            currentLevel = _getMappedSignal(_smoothedValue1, _minMap, _maxMap, 0, _segsNum);
        }
 
        // Pixel + peak update
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            // Peak logic
            if (currentLevel > peakLevel)
            {
                peakLevel = _minValue(currentLevel, _segsNum - 1);
                lastPeakUpdate = _currentTime; // Reset decay timer
            }
            else if (_currentTime - lastPeakUpdate >= peakHoldTime && peakLevel > currentLevel)
            {
                peakLevel--;                   // Slowly drop peak
                lastPeakUpdate = _currentTime; // Reset decay timer
            }
 
            // Draw bar
            for (uint8_t i = 0; i < _segsNum; i++)
            {
                _barMeter.setPixel(_corrPixelToDir(i), (i <= currentLevel));
            }
 
            // Draw peak
            if (peakLevel < _segsNum)
            {
                _barMeter.setPixel(_corrPixelToDir(peakLevel), true);
            }
        }
        return false; // Continuous pulse animation, never auto-terminates
    }
#undef currentLevel
#undef peakLevel
#undef baseUpdate
#undef lastBaseUpdate
#undef peakHoldTime
#undef lastPeakUpdate
 
#undef smoothingFactor
 
    bool _randomPixelUpdater()
    {
        uint8_t *pixelOrder = _randomOrder();
        if (_segsNum == 0 || !pixelOrder)
            return true;
 
        if (_init)
        {
            _init = false;
 
            if (!_animLogicSet)
                _prevAnimRenderLogic = _animRenderLogicIsInverted = _AnimInitLogicIsInverted;
 
            if (_animRenderLogicIsInverted)
                _setAllOn();
            else
                _setAllOff();
 
            for (uint8_t i = 0; i < _segsNum; ++i)
                pixelOrder[i] = i;
 
            for (uint8_t i = _segsNum - 1; i > 0; --i)
            {
                uint8_t j = random(0, i + 1);
                uint8_t tmp = pixelOrder[i];
                pixelOrder[i] = pixelOrder[j];
                pixelOrder[j] = tmp;
            }
 
            _randomCursor = 0;
            _lastUpdate1 = _currentTime;
 
            return false;
        }
 
        if (_currentTime - _lastUpdate1 >= _updateIntv1)
        {
            _lastUpdate1 = _currentTime;
 
            uint8_t retries = 0;
            while (_randomCursor < _segsNum && retries++ < _segsNum - 1)
            {
                uint8_t seg = pixelOrder[_randomCursor];
                bool currentState = _barMeter.getPixelState(seg);
                bool shouldChange = (!_AnimInitLogicIsInverted && !currentState) || (_AnimInitLogicIsInverted && currentState);
 
                if (shouldChange)
                {
                    _barMeter.setPixel(seg, !_AnimInitLogicIsInverted);
                    _randomCursor++;
                    break; // Change only one pixel per interval
                }
                else
                {
                    _randomCursor++; // Move on to next even if it doesn't need change
                }
            }
        }
        if (_randomCursor >= _segsNum)
        {
            return true;
        }
        return false;
    }
};