NeoPixelBus.h

/*-------------------------------------------------------------------------
NeoPixel library 

Written by Michael C. Miller.

I invest time and resources providing this open source code,
please support me by donating (see https://github.com/Makuna/NeoPixelBus)

-------------------------------------------------------------------------
This file is part of the Makuna/NeoPixelBus library.

NeoPixelBus is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.

NeoPixelBus is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with NeoPixel.  If not, see
<http://www.gnu.org/licenses/>.
-------------------------------------------------------------------------*/
#pragma once

#include <Arduino.h>

// standard neo definitions
// 
const uint8_t NEO_DIRTY = 0x80; // a change was made to pixel data that requires a show
const uint16_t PixelIndex_OutOfBounds = 0xffff;

#include "internal/NeoUtil.h"
#include "internal/animations/NeoEase.h"
#include "internal/NeoSettings.h"
#include "internal/NeoColors.h"
#include "internal/NeoColorFeatures.h"
#include "internal/NeoTopologies.h"
#include "internal/NeoBuffers.h"
#include "internal/NeoBusChannel.h"
#include "internal/NeoMethods.h"
#include "internal/XMethods.h"

template<typename T_COLOR_FEATURE, typename T_METHOD> class NeoPixelBus
{
public:
    // Constructor: number of LEDs, pin number
    // NOTE:  Pin Number maybe ignored due to hardware limitations of the method.
   
    NeoPixelBus(uint16_t countPixels, uint8_t pin) :
        _countPixels(countPixels),
        _state(0),
        _method(pin, countPixels, T_COLOR_FEATURE::PixelSize, T_COLOR_FEATURE::SettingsSize)
    {
    }

    NeoPixelBus(uint16_t countPixels, uint8_t pin, NeoBusChannel channel) :
        _countPixels(countPixels),
        _state(0),
        _method(pin, countPixels, T_COLOR_FEATURE::PixelSize, T_COLOR_FEATURE::SettingsSize, channel)
    {
    }

    NeoPixelBus(uint16_t countPixels, uint8_t pinClock, uint8_t pinData) :
        _countPixels(countPixels),
        _state(0),
        _method(pinClock, pinData, countPixels, T_COLOR_FEATURE::PixelSize, T_COLOR_FEATURE::SettingsSize)
    {
    }

    NeoPixelBus(uint16_t countPixels, uint8_t pinClock, uint8_t pinData, uint8_t pinLatch, uint8_t pinOutputEnable = NOT_A_PIN) :
        _countPixels(countPixels),
        _state(0),
        _method(pinClock, pinData, pinLatch, pinOutputEnable, countPixels, T_COLOR_FEATURE::PixelSize, T_COLOR_FEATURE::SettingsSize)
    {
    }

    NeoPixelBus(uint16_t countPixels) :
        _countPixels(countPixels),
        _state(0),
        _method(countPixels, T_COLOR_FEATURE::PixelSize, T_COLOR_FEATURE::SettingsSize)
    {
    }

    NeoPixelBus(uint16_t countPixels, Stream* pixieStream) :
        _countPixels(countPixels),
        _state(0),
        _method(countPixels, T_COLOR_FEATURE::PixelSize, T_COLOR_FEATURE::SettingsSize, pixieStream)
    {
    }

    ~NeoPixelBus()
    {
    }

    operator NeoBufferContext<T_COLOR_FEATURE>()
    {
        Dirty(); // we assume you are playing with bits
        return NeoBufferContext<T_COLOR_FEATURE>(_pixels(), PixelsSize());
    }

    void Begin()
    {
        _method.Initialize();
        ClearTo(0);
    }

    // used by DotStarSpiMethod/DotStarEsp32DmaSpiMethod if pins can be configured
    void Begin(int8_t sck, int8_t miso, int8_t mosi, int8_t ss)
    {
        _method.Initialize(sck, miso, mosi, ss);
        ClearTo(0);
    }

    // used by DotStarEsp32DmaSpiMethod if pins can be configured - reordered and extended version supporting quad SPI
    void Begin(int8_t sck, int8_t dat0, int8_t dat1, int8_t dat2, int8_t dat3, int8_t ss)
    {
        _method.Initialize(sck, dat0, dat1, dat2, dat3, ss);
        ClearTo(0);
    }

    // used by DotStarEsp32DmaSpiMethod if pins can be configured - reordered and extended version supporting oct SPI
    void Begin(int8_t sck, int8_t dat0, int8_t dat1, int8_t dat2, int8_t dat3, int8_t dat4, int8_t dat5, int8_t dat6, int8_t dat7, int8_t ss)
    {
        _method.Initialize(sck, dat0, dat1, dat2, dat3, dat4, dat5, dat6, dat7, ss);
        ClearTo(0);
    }

    void Show(bool maintainBufferConsistency = true)
    {
        if (!IsDirty() && !_method.AlwaysUpdate())
        {
            return;
        }

        _method.Update(maintainBufferConsistency);

        ResetDirty();
    }

    inline bool CanShow() const
    { 
        return _method.IsReadyToUpdate();
    };

    bool IsDirty() const
    {
        return  (_state & NEO_DIRTY);
    };

    void Dirty()
    {
        _state |= NEO_DIRTY;
    };

    void ResetDirty()
    {
        _state &= ~NEO_DIRTY;
    };

    uint8_t* Pixels() 
    {
        return _pixels();
    };

    size_t PixelsSize() const
    {
        return _method.getDataSize() - T_COLOR_FEATURE::SettingsSize;
    };

    size_t PixelSize() const
    {
        return T_COLOR_FEATURE::PixelSize;
    };

    uint16_t PixelCount() const
    {
        return _countPixels;
    };

    void SetPixelColor(uint16_t indexPixel, typename T_COLOR_FEATURE::ColorObject color)
    {
        if (indexPixel < _countPixels)
        {
            T_COLOR_FEATURE::applyPixelColor(_pixels(), indexPixel, color);
            Dirty();
        }
    };

    typename T_COLOR_FEATURE::ColorObject GetPixelColor(uint16_t indexPixel) const
    {
        if (indexPixel < _countPixels)
        {
            return T_COLOR_FEATURE::retrievePixelColor(_pixels(), indexPixel);
        }
        else
        {
            // Pixel # is out of bounds, this will get converted to a 
            // color object type initialized to 0 (black)
            return 0;
        }
    };

    template <typename T_COLOROBJECT> T_COLOROBJECT GetPixelColor(uint16_t indexPixel) const
    {
        return T_COLOROBJECT(GetPixelColor(indexPixel));
    }

    void ClearTo(typename T_COLOR_FEATURE::ColorObject color)
    {
        uint8_t temp[T_COLOR_FEATURE::PixelSize]; 
        uint8_t* pixels = _pixels();

        T_COLOR_FEATURE::applyPixelColor(temp, 0, color);

        T_COLOR_FEATURE::replicatePixel(pixels, temp, _countPixels);

        Dirty();
    };

    void ClearTo(typename T_COLOR_FEATURE::ColorObject color, uint16_t first, uint16_t last)
    {
        if (first < _countPixels &&
            last < _countPixels &&
            first <= last)
        {
            uint8_t temp[T_COLOR_FEATURE::PixelSize];
            uint8_t* pixels = _pixels();
            uint8_t* pFront = T_COLOR_FEATURE::getPixelAddress(pixels, first);

            T_COLOR_FEATURE::applyPixelColor(temp, 0, color);

            T_COLOR_FEATURE::replicatePixel(pFront, temp, last - first + 1);

            Dirty();
        }
    }

    void RotateLeft(uint16_t rotationCount)
    {
        if ((_countPixels - 1) >= rotationCount)
        {
            _rotateLeft(rotationCount, 0, _countPixels - 1);
        }
    }

    void RotateLeft(uint16_t rotationCount, uint16_t first, uint16_t last)
    {
        if (first < _countPixels &&
            last < _countPixels &&
            first < last &&
            (last - first) >= rotationCount)
        {
            _rotateLeft(rotationCount, first, last);
        }
    }

    void ShiftLeft(uint16_t shiftCount)
    {
        if ((_countPixels - 1) >= shiftCount)
        {
            _shiftLeft(shiftCount, 0, _countPixels - 1);
            Dirty();
        }
    }

    void ShiftLeft(uint16_t shiftCount, uint16_t first, uint16_t last)
    {
        if (first < _countPixels && 
            last < _countPixels && 
            first < last &&
            (last - first) >= shiftCount)
        {
            _shiftLeft(shiftCount, first, last);
            Dirty();
        }
    }

    void RotateRight(uint16_t rotationCount)
    {
        if ((_countPixels - 1) >= rotationCount)
        {
            _rotateRight(rotationCount, 0, _countPixels - 1);
        }
    }

    void RotateRight(uint16_t rotationCount, uint16_t first, uint16_t last)
    {
        if (first < _countPixels &&
            last < _countPixels &&
            first < last &&
            (last - first) >= rotationCount)
        {
            _rotateRight(rotationCount, first, last);
        }
    }

    void ShiftRight(uint16_t shiftCount)
    {
        if ((_countPixels - 1) >= shiftCount)
        {
            _shiftRight(shiftCount, 0, _countPixels - 1);
            Dirty();
        }
    }

    void ShiftRight(uint16_t shiftCount, uint16_t first, uint16_t last)
    {
        if (first < _countPixels &&
            last < _countPixels &&
            first < last &&
            (last - first) >= shiftCount)
        {
            _shiftRight(shiftCount, first, last);
            Dirty();
        }
    }
    
    void SwapPixelColor(uint16_t indexPixelOne, uint16_t indexPixelTwo)
    {
        auto colorOne = GetPixelColor(indexPixelOne);
        auto colorTwo = GetPixelColor(indexPixelTwo);

        SetPixelColor(indexPixelOne, colorTwo);
        SetPixelColor(indexPixelTwo, colorOne);
    };

    void SetPixelSettings(const typename T_COLOR_FEATURE::SettingsObject& settings)
    {
        T_COLOR_FEATURE::applySettings(_method.getData(), _method.getDataSize(), settings);
        if (_method.SwapBuffers())
        {
            // some methods have two internal buffers
            // so need to swap so settings are stored in both copies
            //
            T_COLOR_FEATURE::applySettings(_method.getData(), _method.getDataSize(), settings);
            // swap back to minimize inconsistencies
            _method.SwapBuffers();
        }
        Dirty();
    };

    void SetMethodSettings(const typename T_METHOD::SettingsObject& settings)
    {
        _method.applySettings(settings);
        Dirty();
    };
 
    uint32_t CalcTotalMilliAmpere(const typename T_COLOR_FEATURE::ColorObject::SettingsObject& settings)
    {
        uint32_t total = 0; // in 1/10th milliamps

        for (uint16_t index = 0; index < _countPixels; index++)
        {
            auto color = GetPixelColor(index);
            total += color.CalcTotalTenthMilliAmpere(settings);
        }

        return total / 10; // return millamps
    }

protected:
    const uint16_t _countPixels; // Number of RGB LEDs in strip

    uint8_t _state;     // internal state
    T_METHOD _method;

    uint8_t* _pixels()
    {
        // get pixels data within the data stream
        return T_COLOR_FEATURE::pixels(_method.getData(), _method.getDataSize());
    }

    const uint8_t* _pixels() const
    {
        // get pixels data within the data stream
        return T_COLOR_FEATURE::pixels(_method.getData(), _method.getDataSize());
    }

    void _rotateLeft(uint16_t rotationCount, uint16_t first, uint16_t last)
    {
        // store in temp
        uint8_t temp[rotationCount * T_COLOR_FEATURE::PixelSize];
        uint8_t* pixels = _pixels();

        uint8_t* pFront = T_COLOR_FEATURE::getPixelAddress(pixels, first);

        T_COLOR_FEATURE::movePixelsInc(temp, pFront, rotationCount);

        // shift data
        _shiftLeft(rotationCount, first, last);

        // move temp back
        pFront = T_COLOR_FEATURE::getPixelAddress(pixels, last - (rotationCount - 1));
        T_COLOR_FEATURE::movePixelsInc(pFront, temp, rotationCount);

        Dirty();
    }

    void _shiftLeft(uint16_t shiftCount, uint16_t first, uint16_t last)
    {
        uint16_t front = first + shiftCount;
        uint16_t count = last - front + 1;

        uint8_t* pixels = _pixels();
        uint8_t* pFirst = T_COLOR_FEATURE::getPixelAddress(pixels, first);
        uint8_t* pFront = T_COLOR_FEATURE::getPixelAddress(pixels, front);

        T_COLOR_FEATURE::movePixelsInc(pFirst, pFront, count);

        // intentional no dirty
    }

    void _rotateRight(uint16_t rotationCount, uint16_t first, uint16_t last)
    {
        // store in temp
        uint8_t temp[rotationCount * T_COLOR_FEATURE::PixelSize];
        uint8_t* pixels = _pixels();

        uint8_t* pFront = T_COLOR_FEATURE::getPixelAddress(pixels, last - (rotationCount - 1));

        T_COLOR_FEATURE::movePixelsDec(temp, pFront, rotationCount);

        // shift data
        _shiftRight(rotationCount, first, last);

        // move temp back
        pFront = T_COLOR_FEATURE::getPixelAddress(pixels, first);
        T_COLOR_FEATURE::movePixelsDec(pFront, temp, rotationCount);

        Dirty();
    }

    void _shiftRight(uint16_t shiftCount, uint16_t first, uint16_t last)
    {
        uint16_t front = first + shiftCount;
        uint16_t count = last - front + 1;

        uint8_t* pixels = _pixels();
        uint8_t* pFirst = T_COLOR_FEATURE::getPixelAddress(pixels, first);
        uint8_t* pFront = T_COLOR_FEATURE::getPixelAddress(pixels, front);

        T_COLOR_FEATURE::movePixelsDec(pFront, pFirst, count);
        // intentional no dirty
    }
};