cled_controller.h

Go to the documentation of this file.

#pragma once

 
#include "color.h"
#include "pixel_controller.h"  // IWYU pragma: keep  (ColorAdjustment)
 
#include "fl/stl/compiler_control.h"
#include "dither_mode.h"
#include "fl/system/engine_events.h"
#include "fl/math/screenmap.h"
#include "fl/stl/int.h"
#include "fl/stl/bit_cast.h"
#include "fl/channels/legacy_settings.h"
#include "fl/log/log.h"
#include "platforms/is_platform.h"  // for FL_IS_ESP32, FL_IS_AVR
#include "fl/stl/span.h"
#include "fl/stl/noexcept.h"
#include "fl/spi_bus.h"

//
// LED Controller interface definition
//

 
namespace fl {
 
class Channel;
 
namespace detail {
void enable_rgbw_power_estimate() FL_NO_EXCEPT;
}  // namespace detail
 
class CLEDController {
protected:
    friend class CFastLED;
    fl::span<CRGB> mLeds;     
    CLEDController *mPNext = nullptr;   
    LegacySettings mLegacySettings;
    // Bit-fields share one byte; a fixed-white flag costs no RAM and no
    // vtable slot on AVR (#4788).
    bool mEnabled : 1;
    bool mFixedWhiteChannel : 1;  
 
    enum class SettingsChange : u8 { Correction, Temperature, Dither, White };
#ifndef FL_IS_AVR
    // Derived APIs can react to settings changed through a base reference.
    // AVR has neither this slot nor a notification call.
    virtual void onSettingsChanged(SettingsChange change) FL_NO_EXCEPT {
        FL_UNUSED(change);
    }
#endif
    void settingsChanged(SettingsChange change) FL_NO_EXCEPT {
#ifndef FL_IS_AVR
        onSettingsChanged(change);
#else
        FL_UNUSED(change);
#endif
    }
    static CLEDController *mPHead;  

    enum class RegistrationMode {
        AutoRegister,   
        DeferRegister   
    };

    CLEDController(RegistrationMode mode) FL_NO_EXCEPT;
 
    void applyRgbw(const Rgbw& arg) FL_NO_EXCEPT {
        if (!arg.active()) {
            mLegacySettings.mWhiteCfg.reset();
        } else {
            prepare_rgbw_colorimetric(arg);
            detail::enable_rgbw_power_estimate();
            mLegacySettings.mWhiteCfg = arg;
        }
    }

    void setFixedRgbw(const Rgbw& arg) FL_NO_EXCEPT {
        applyRgbw(arg);
        mFixedWhiteChannel = true;
    }
 
    bool rejectFixedWhiteChannelChange(const char* operation) const FL_NO_EXCEPT {
        FL_UNUSED(operation);  // only consumed by FL_WARN, a no-op on small platforms
        if (!mFixedWhiteChannel) {
            return false;
        }
        FL_WARN("Chipset has fixed R,G,B,W output; " << operation << " is unsupported and was ignored");
        return true;
    }
 
public:
#ifndef FL_IS_AVR
    // Identify Channels without retaining Channels configuration in this base.
    // Standalone Channels need the same integration as registered Channels.
    virtual const Channel* asChannel() const FL_NO_EXCEPT { return nullptr; }
#endif
#if defined(FL_IS_ESP32)
    virtual
#endif
    CLEDController &setSpiBus(Esp32SpiBus bus) FL_NO_EXCEPT {
        (void)bus;
        return *this;
    }

    void addToList() FL_NO_EXCEPT;

    bool isInList() const FL_NO_EXCEPT;

    virtual void showColor(const CRGB & data, int nLeds, fl::u8 brightness) FL_NO_EXCEPT = 0;

    virtual void show(const CRGB *data, int nLeds, fl::u8 brightness) FL_NO_EXCEPT = 0;
 
    CLEDController& setRgbw(const Rgbw& arg = RgbwDefault::value()) FL_NO_EXCEPT {
        if (rejectFixedWhiteChannelChange("setRgbw()")) {
            return *this;
        }
        // (#2558) mLegacySettings.mWhiteCfg is now a fl::variant<Empty, Rgbw, Rgbww>;
        // assigning Rgbw selects the 4-channel alternative. The legacy
        // "setRgbw(RgbwInvalid::value()) → disable" semantics are preserved
        // by translating an inactive Rgbw into Empty so observers see the
        // same "no white channel" state they did before the variant migration.
        if (arg.active()) {
            // Covers an Rgbw made active by assigning rgbw_mode (#4795).
            detail::enable_rgbw_conversion();
        }
        applyRgbw(arg);
        settingsChanged(SettingsChange::White);
        return *this;  // builder pattern.
    }

    CLEDController& setRgbww(const Rgbww& arg = RgbwwDefault::value()) FL_NO_EXCEPT {
        if (rejectFixedWhiteChannelChange("setRgbww()")) {
            return *this;
        }
        if (!arg.active()) {
            mLegacySettings.mWhiteCfg.reset();
        } else {
            detail::enable_rgbww_conversion();  // see setRgbw (#4795)
            mLegacySettings.mWhiteCfg = arg;
        }
        settingsChanged(SettingsChange::White);
        return *this;
    }

    CLEDController& clearWhiteChannel() FL_NO_EXCEPT {
        if (rejectFixedWhiteChannelChange("clearWhiteChannel()")) {
            return *this;
        }
        mLegacySettings.mWhiteCfg.reset();
        settingsChanged(SettingsChange::White);
        return *this;
    }
 
    void setEnabled(bool enabled) FL_NO_EXCEPT { mEnabled = enabled; }
    bool getEnabled() FL_NO_EXCEPT { return mEnabled; }
 
    CLEDController() FL_NO_EXCEPT;
    // If we added virtual to the AVR boards then we are going to add 600 bytes of memory to the binary
    // flash size. This is because the virtual destructor pulls in malloc and free, which are the largest
    // Testing shows that this virtual destructor adds a 600 bytes to the binary on
    // attiny85 and about 1k for the teensy 4.X series.
    // Attiny85:
    //   With CLEDController destructor virtual: 11018 bytes to binary.
    //   Without CLEDController destructor virtual: 10666 bytes to binary.
    VIRTUAL_IF_NOT_AVR ~CLEDController() FL_NO_EXCEPT;

    Rgbw getRgbw() const FL_NO_EXCEPT { return mLegacySettings.rgbw(); }

    const Rgbw* rgbwConfig() const FL_NO_EXCEPT {
        return mLegacySettings.mWhiteCfg.ptr<Rgbw>();
    }

    Rgbww getRgbww() const FL_NO_EXCEPT { return mLegacySettings.rgbww(); }

    virtual void init() FL_NO_EXCEPT = 0;

    VIRTUAL_IF_NOT_AVR void clearLeds(int nLeds = -1) FL_NO_EXCEPT {
        clearLedDataInternal(nLeds);
        showLeds(0);
    }
 
    // Compatibility with the 3.8.x codebase.
    VIRTUAL_IF_NOT_AVR void showLeds(fl::u8 brightness) FL_NO_EXCEPT {
        fl::EngineEvents::onBeginFrame();
        void* data = beginShowLeds(mLeds.size());
        showLedsInternal(brightness);
        endShowLeds(data);
        fl::EngineEvents::onEndFrame();
#if FASTLED_HAS_ENGINE_EVENTS
        fl::EngineEvents::onEndShowLeds();
#endif
    }
 
    ColorAdjustment getAdjustmentData(fl::u8 brightness) FL_NO_EXCEPT;

    void showInternal(const CRGB *data, int nLeds, fl::u8 brightness) FL_NO_EXCEPT {
        if (getEnabled()) {
           show(data, nLeds,brightness);
        }
    }

    void showColorInternal(const CRGB &data, int nLeds, fl::u8 brightness) FL_NO_EXCEPT {
        if (getEnabled()) {
            showColor(data, nLeds, brightness);
        }
    }

    void showLedsInternal(fl::u8 brightness) FL_NO_EXCEPT {
        if (getEnabled()) {
            show(mLeds.data(), mLeds.size(), brightness);
        }
    }

    void showColorInternal(const CRGB & data, fl::u8 brightness) FL_NO_EXCEPT {
        if (getEnabled()) {
            showColor(data, mLeds.size(), brightness);
        }
    }

    static CLEDController *head() FL_NO_EXCEPT { return mPHead; }

    CLEDController *next() FL_NO_EXCEPT { return mPNext; }

    template<typename Visitor>
    static void visitControllers(Visitor&& visitor) FL_NO_EXCEPT {
        const CLEDController *pCur = head();
        while(pCur) {
            visitor(pCur, fl::span<const CRGB>(pCur->leds(), pCur->size()));
            pCur = pCur->next();
        }
    }

    const CLEDController *next() const FL_NO_EXCEPT { return mPNext; }

    CLEDController & setLeds(CRGB *data, int nLeds) FL_NO_EXCEPT {
        mLeds = fl::span<CRGB>(data, nLeds);
        return *this;
    }

    CLEDController & setLeds(fl::span<CRGB> leds) FL_NO_EXCEPT {
        mLeds = leds;
        return *this;
    }

    void clearLedDataInternal(int nLeds = -1) FL_NO_EXCEPT;

    void removeFromDrawList() FL_NO_EXCEPT {
        removeFromList(this);
    }

    static void removeFromList(CLEDController* controller) FL_NO_EXCEPT;

    // Not virtual on AVR: no AVR controller overrides it (#4788).
    VIRTUAL_IF_NOT_AVR int size() const FL_NO_EXCEPT { return mLeds.size(); }

    virtual int lanes() FL_NO_EXCEPT { return 1; }

    CRGB* leds() FL_NO_EXCEPT { return mLeds.data(); }

    const CRGB* leds() const FL_NO_EXCEPT { return mLeds.data(); }

    fl::span<CRGB> ledsSpan() FL_NO_EXCEPT { return mLeds; }

    CRGB &operator[](int x) FL_NO_EXCEPT { return mLeds[x]; }

    inline CLEDController & setDither(fl::u8 ditherMode = BINARY_DITHER) FL_NO_EXCEPT { mLegacySettings.mDitherMode = ditherMode; settingsChanged(SettingsChange::Dither); return *this; }
 
    CLEDController& setScreenMap(const fl::XYMap& map, float diameter = -1.f) FL_NO_EXCEPT {
        // EngineEvents::onCanvasUiSet(this, map);
        fl::ScreenMap screenmap = map.toScreenMap();
        if (diameter <= 0.0f) {
            screenmap.setDiameter(.15f); // Assume small matrix is being used.
        }
        fl::EngineEvents::onCanvasUiSet(this, screenmap);
        return *this;
    }
 
    CLEDController& setScreenMap(const fl::ScreenMap& map) FL_NO_EXCEPT {
        fl::EngineEvents::onCanvasUiSet(this, map);
        return *this;
    }
 
    CLEDController& setScreenMap(fl::u16 width, fl::u16 height, float diameter = -1.f) FL_NO_EXCEPT {
        fl::XYMap xymap = fl::XYMap::constructRectangularGrid(width, height);
        return setScreenMap(xymap, diameter);
    }

    inline fl::u8 getDither() const FL_NO_EXCEPT { return mLegacySettings.mDitherMode; }
 
    // Not virtual on AVR (#4788). Its only overrides are the RGBW/WS2816
    // wrappers, which forward to a disabled inner controller; on AVR the base
    // version saves and restores the wrapper's own dither instead. Custom AVR
    // controllers cannot hook these, or size().
    VIRTUAL_IF_NOT_AVR void* beginShowLeds(int size) FL_NO_EXCEPT {
        FASTLED_UNUSED(size);
        // By default, emit an integer. This integer will, by default, be passed back.
        // If you override beginShowLeds() then
        // you should also override endShowLeds() to match the return state.
        //
        // For async led controllers this should be used as a sync point to block
        // the caller until the leds from the last draw frame have completed drawing.
        // for each controller:
        //   beginShowLeds();
        // for each controller:
        //   showLeds();
        // for each controller:
        //   endShowLeds();
        uintptr_t d = getDither();
        void* out = fl::int_to_ptr<void>(d);
        return out;
    }
 
    VIRTUAL_IF_NOT_AVR void endShowLeds(void* data) FL_NO_EXCEPT {
        // By default recieves the integer that beginShowLeds() emitted.
        //For async controllers this should be used to signal the controller
        // to begin transmitting the current frame to the leds.
        uintptr_t d = fl::ptr_to_int(data);
        setDither(static_cast<fl::u8>(d));
    }

    CLEDController & setCorrection(CRGB correction) FL_NO_EXCEPT {
        mLegacySettings.mCorrection = correction;
        settingsChanged(SettingsChange::Correction);
        return *this;
    }

    CLEDController & setCorrection(LEDColorCorrection correction) FL_NO_EXCEPT {
        mLegacySettings.mCorrection = correction;
        settingsChanged(SettingsChange::Correction);
        return *this;
    }

    CRGB getCorrection() FL_NO_EXCEPT { return mLegacySettings.mCorrection; }

    CLEDController & setTemperature(CRGB temperature) FL_NO_EXCEPT {
        mLegacySettings.mTemperature = temperature;
        settingsChanged(SettingsChange::Temperature);
        return *this;
    }

    CLEDController & setTemperature(ColorTemperature temperature) FL_NO_EXCEPT {
        mLegacySettings.mTemperature = temperature;
        settingsChanged(SettingsChange::Temperature);
        return *this;
    }

    CRGB getTemperature() FL_NO_EXCEPT { return mLegacySettings.mTemperature; }

    CRGB getAdjustment(fl::u8 scale) FL_NO_EXCEPT {
        return CRGB::computeAdjustment(scale, mLegacySettings.mCorrection, mLegacySettings.mTemperature);
    }

    virtual fl::u16 getMaxRefreshRate() const FL_NO_EXCEPT { return 0; }
};
 
#ifdef FL_IS_AVR
// Legacy controllers must stay compact even when Channels gains new options.
FL_STATIC_ASSERT(sizeof(CLEDController) <= 32, "Legacy AVR controller grew beyond its settings budget");
#endif
 
}  // namespace fl