channel.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/noexcept.h"
 
#include "cpixel_ledcontroller.h"
#include "fl/channels/bus.h"
#include "fl/channels/ichannel.h"
#include "fl/channels/options.h"
#include "fl/gfx/pipeline.h"
#include "fl/stl/unique_ptr.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/string.h"
#include "fl/stl/weak_ptr.h"
#include "fl/stl/stdint.h"
#include "fl/channels/config.h"
#include "fl/channels/channel_events.h"
#include "fl/stl/compiler_control.h"
 
namespace fl {
 
// Forward declarations
class IChannelDriver;
class ChannelData;
class PixelIterator;
template <typename T> class vector_psram;
struct ChannelOptions;  // IWYU pragma: keep
class Channel;
template<const EmitterProfile& Profile> class StaticProfileChannel;
class XMap;
enum class ColorProfileStatus : u8 { Unconfigured, Configured, Fallback, Rejected };
enum class ProfileId : u8 { WS2812B };
FASTLED_SHARED_PTR(Channel);
FASTLED_SHARED_PTR(ChannelData);
 
#if FL_COLOR_PIPELINE_SHARED
shared_ptr<StreamingPipelineQ16> channelColorPipeline(const CLEDController& controller) FL_NO_EXCEPT;
#endif

class Channel: public CPixelLEDController<RGB>, public IChannel {
public:
    static ChannelPtr create(const ChannelConfig& config) FL_NO_EXCEPT;
    template<const EmitterProfile& Profile>
    static ChannelPtr create(const ChannelConfig& config) FL_NO_EXCEPT {
#ifdef FL_IS_AVR
        FL_STATIC_ASSERT(&Profile == nullptr, "Color profiles are unsupported on AVR");
#endif
        ChannelConfig rebound(config);
#if FL_COLOR_PROFILE_RUNTIME
        rebound.options.clearColorProfile();
        installColorPipelineHooks();
        rebound.options.mColorProfile.mStaticProfile = &Profile;
        rebound.options.mColorProfile.mRequested = true;
#else
#endif
        auto channel = fl::make_shared<StaticProfileChannel<Profile>>(rebound);
        channel->mName = makeName(channel->mId, rebound.mName);
        auto& events = ChannelEvents::instance();
#if FL_COLOR_PROFILE_RUNTIME
        if (channel->reconcileColorProfile(rebound.options)) {
            events.onColorProfileFallback(
                ColorProfileEvent{channel->id(), channel->colorProfileStatus(), {}});
        }
#endif
        events.onChannelCreated(*channel);
        return channel;
    }
    template<ProfileId Id>
    static ChannelPtr create(const ChannelConfig& config) FL_NO_EXCEPT {
        return create<profiles::WS2812B>(config);
    }

    virtual ~Channel() FL_NO_EXCEPT;

    i32 id() const FL_NO_EXCEPT override { return mId; }

    const fl::string& name() const FL_NO_EXCEPT override { return mName; }

    int getPin() const FL_NO_EXCEPT;

    int getClockPin() const FL_NO_EXCEPT;

    Channel& setGamma(float gamma) FL_NO_EXCEPT;

    fl::optional<float> getGamma() const FL_NO_EXCEPT;

    const ChipsetTimingConfig& getTiming() const FL_NO_EXCEPT;

    const ChipsetVariant& getChipset() const FL_NO_EXCEPT { return mChipset; }

    EOrder getRgbOrder() const FL_NO_EXCEPT { return mRgbOrder; }

    bool isClockless() const FL_NO_EXCEPT { return mChipset.is<ClocklessChipset>(); }

    bool isSpi() const FL_NO_EXCEPT { return mChipset.is<SpiChipsetConfig>(); }

    void applyConfig(const ChannelConfig& config) FL_NO_EXCEPT;
 
    // Re-expose protected base class methods for external access
    void addToDrawList() FL_NO_EXCEPT;

    void removeFromDrawList() FL_NO_EXCEPT;

    int size() const FL_NO_EXCEPT OVERRIDE_IF_NOT_AVR;
 
#if FL_COLOR_PROFILE_RUNTIME
#if FL_COLOR_PIPELINE_SHARED
    using ColorPipelineStorage = fl::shared_ptr<StreamingPipelineQ16>;
#else
    // Small tiers: sync-only readers, so single ownership is provably safe
    // and saves the control block (FL_COLOR_PIPELINE_SHARED).
    using ColorPipelineStorage = fl::unique_ptr<StreamingPipelineQ16>;
#endif
#endif

    void showLeds(u8 brightness = 255) FL_NO_EXCEPT OVERRIDE_IF_NOT_AVR;

    bool isInDrawList() const FL_NO_EXCEPT;

    CLEDController* asController() FL_NO_EXCEPT { return static_cast<CLEDController*>(this); }
    const CLEDController* asController() const FL_NO_EXCEPT { return static_cast<const CLEDController*>(this); }
#ifndef FL_IS_AVR
    const Channel* asChannel() const FL_NO_EXCEPT override { return this; }
#endif

    fl::span<CRGB> leds() FL_NO_EXCEPT;

    fl::span<const CRGB> leds() const FL_NO_EXCEPT;

    CRGB getCorrection() FL_NO_EXCEPT;

    CRGB getTemperature() FL_NO_EXCEPT;

    u8 getDither() FL_NO_EXCEPT;

    Rgbw getRgbw() const FL_NO_EXCEPT;
 
    bool hasColorProfile() const FL_NO_EXCEPT { return emitterProfile() != nullptr; }
    bool isColorManaged() const FL_NO_EXCEPT {
#if FL_COLOR_PROFILE_RUNTIME
        return mPipeline != nullptr;
#else
        return false;
#endif
    }
    const EmitterProfile* emitterProfile() const FL_NO_EXCEPT {
#ifdef FL_IS_AVR
        return nullptr;
#else
        const EmitterProfile* profile = staticEmitterProfile();
        return profile != nullptr && !mStaticProfileCleared
            ? profile : mSettings.emitterProfile();
#endif
    }
    const SourceProfile& sourceProfile() const FL_NO_EXCEPT {
#if FL_COLOR_PROFILE_RUNTIME
        return mSettings.mColorProfile.mSource;
#else
        return detail::defaultSourceProfile();
#endif
    }
    Chromaticity targetWhite() const FL_NO_EXCEPT { return mSettings.targetWhite(); }
 
#if FL_COLOR_PIPELINE_SHARED
    fl::shared_ptr<StreamingPipelineQ16> colorPipeline() const FL_NO_EXCEPT;
#endif
    bool isEnabled() const FL_NO_EXCEPT { return const_cast<Channel*>(this)->getEnabled(); }
    u8 ditherPhase() const FL_NO_EXCEPT;
    bool hasColorProfileFallback() const FL_NO_EXCEPT {
#if FL_COLOR_PROFILE_RUNTIME
        return mColorProfileFallback;
#else
        return false;
#endif
    }
    bool profileBindingAccepted() const FL_NO_EXCEPT {
#if FL_COLOR_PROFILE_RUNTIME
        return mProfileBindingAccepted;
#else
        return true;
#endif
    }
    ColorProfileStatus colorProfileStatus() const FL_NO_EXCEPT {
#if FL_COLOR_PROFILE_RUNTIME
        if (mColorProfileFallback) return mProfileBindingAccepted ? ColorProfileStatus::Fallback : ColorProfileStatus::Rejected;
#endif
        return hasColorProfile() ? ColorProfileStatus::Configured : ColorProfileStatus::Unconfigured;
    }

    fl::string getEngineName() const FL_NO_EXCEPT;

    Channel& setScreenMap(const fl::XYMap& map, float diameter = -1.f) FL_NO_EXCEPT;

    Channel& setScreenMap(const fl::ScreenMap& map) FL_NO_EXCEPT;

    Channel& setScreenMap(fl::u16 width, fl::u16 height, float diameter = -1.f) FL_NO_EXCEPT;

    Channel& setScreenMap(const fl::XMap& map) FL_NO_EXCEPT;

    const fl::ScreenMap& getScreenMap() const FL_NO_EXCEPT;

    bool hasScreenMap() const FL_NO_EXCEPT;
 
private:
    template<typename T, typename... Args>
    friend fl::shared_ptr<T> fl::adl_barrier::make_shared(Args&&... args) FL_NO_EXCEPT;  // see fl/stl/adl_barrier.h
    template<const EmitterProfile& Profile>
    friend class StaticProfileChannel;
 
protected:
    // CPixelLEDController interface implementation - protected so subclass delegates
    // (e.g., UCS7604's DelegateController) can call through the base class chain.
    void showPixels(PixelController<RGB, 1, 0xFFFFFFFF>& pixels) FL_NO_EXCEPT override;
    void init() FL_NO_EXCEPT override;
    using PixelEncoder = void (*)(Channel&, PixelIterator&, bool,
                                  fl::vector_psram<u8>&);
 
private:
    FL_NO_INLINE fl::shared_ptr<IChannelDriver> resolveDynamicDriver() FL_NO_EXCEPT;

    FL_NO_INLINE bool waitForInUseBuffer() FL_NO_EXCEPT;

    FL_NO_INLINE void encodeFrame(PixelController<RGB, 1, 0xFFFFFFFF>& pixels) FL_NO_EXCEPT;

    FL_NO_INLINE void submitFrame(const fl::shared_ptr<IChannelDriver>& driver) FL_NO_EXCEPT;

    static PixelEncoder selectPixelEncoder(const ChipsetVariant&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeWS2812(Channel&, PixelIterator&, bool,
                                         fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeTM1812RGBWW(Channel&, PixelIterator&, bool,
                                               fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeTM1908(Channel&, PixelIterator&, bool,
                                         fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeUCS7604(Channel&, PixelIterator&, bool,
                                           fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeAPA102(Channel&, PixelIterator&, bool,
                                          fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeSK9822(Channel&, PixelIterator&, bool,
                                          fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeWS2801(Channel&, PixelIterator&, bool,
                                          fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeWS2803(Channel&, PixelIterator&, bool,
                                          fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeP9813(Channel&, PixelIterator&, bool,
                                         fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeLPD8806(Channel&, PixelIterator&, bool,
                                           fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeLPD6803(Channel&, PixelIterator&, bool,
                                           fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeSM16716(Channel&, PixelIterator&, bool,
                                           fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeHD108(Channel&, PixelIterator&, bool,
                                         fl::vector_psram<u8>&) FL_NO_EXCEPT;
    FL_NO_INLINE static void encodeMY9221(Channel&, PixelIterator&, bool,
                                          fl::vector_psram<u8>&) FL_NO_EXCEPT;
 
private:
    Channel(const ChipsetVariant& chipset, fl::span<CRGB> leds,
            EOrder rgbOrder, const ChannelOptions& options) FL_NO_EXCEPT;

    Channel(int pin, const ChipsetTimingConfig& timing, fl::span<CRGB> leds,
            EOrder rgbOrder, const ChannelOptions& options) FL_NO_EXCEPT;
 
    // Non-copyable, non-movable
    Channel(const Channel&) FL_NO_EXCEPT = delete;
    Channel& operator=(const Channel&) FL_NO_EXCEPT = delete;
    Channel(Channel&&) FL_NO_EXCEPT = delete;
    Channel& operator=(Channel&&) FL_NO_EXCEPT = delete;
 
    static i32 nextId() FL_NO_EXCEPT;
    static fl::string makeName(i32 id, const fl::optional<fl::string>& configName = fl::optional<fl::string>()) FL_NO_EXCEPT;
 
    ChipsetVariant mChipset;         // Chipset configuration (clockless or SPI)
    PixelEncoder mPixelEncoder = nullptr;  // Bound once from mChipset at construction.
    EOrder mRgbOrder;
#if FL_COLOR_PROFILE_RUNTIME
    ColorPipelineStorage mPipeline;
#endif
    fl::weak_ptr<IChannelDriver> mDriver;  // Cached dynamic driver (weak, prevents dangling pointers).
                                     // Re-resolved by resolveDynamicDriver() on every showPixels()
                                     // call so users can swap drivers at runtime.
    Bus mBus = Bus::AUTO;            // Typed driver selection (#2459). `Bus::AUTO` falls through
                                     // to `ChannelManager` priority dispatch; any other value
                                     // pins this channel to `busName(mBus)`.
    fl::u8 mBusWhich = 0;            // Instance selector for portable buses.
    bool mBusWarned = false;         // One-shot guard for the #2455 FL_ERROR. Flipped on the
                                     // first showPixels() that observes a `mBus` miss (the
                                     // named driver wasn't registered with ChannelManager).
                                     // Subsequent shows on the same channel skip the warn even
                                     // though the priority-dispatch fallback re-runs every frame.
    u8 mDitherPhase = 0;
    bool mDisabledDriverWarned = false;  // One-shot guard for the #2517 FL_ERROR. Flipped on the
                                         // first showPixels() that would have enqueued data to a
                                         // driver disabled by `setExclusiveDriver(...)` (or
                                         // `setDriverEnabled(name, false)`). Cleared whenever the
                                         // resolved driver returns to ENABLED so a subsequent
                                         // disable re-emits the diagnostic.
    const i32 mId;
    fl::string mName;               // User-specified or auto-generated name
    ChannelDataPtr mChannelData;
    fl::ScreenMap mScreenMap;        // Screen map for JS canvas visualization
    ChannelOptions mSettings;
#ifndef FL_IS_AVR
    bool mStaticProfileCleared = false;
#endif
    void syncLegacySettings() FL_NO_EXCEPT;
#ifndef FL_IS_AVR
    void onSettingsChanged(SettingsChange change) FL_NO_EXCEPT override;
    virtual const EmitterProfile* staticEmitterProfile() const FL_NO_EXCEPT { return nullptr; }
#endif
 
#if FL_COLOR_PROFILE_RUNTIME
    // Recompute the color-profile verdict from the current mSettings and
    // apply its consequences. Runs on both creation and reconfiguration, so
    // applyConfig() cannot leave a channel reporting the verdict of the
    // configuration it just replaced. Returns true when the binding fell back.
    // Reads the requested configuration from `options`; mSettings may receive
    // the current global source default while deriving the installed pipeline.
    bool reconcileColorProfile(const ChannelOptions& options) FL_NO_EXCEPT;

    void raiseColorProfileFallback(const char* reason) FL_NO_EXCEPT;
 
    bool mColorProfileFallback = false;
    bool mProfileBindingAccepted = true;
    // C5 asks for the fallback warning to be one-time. Set on the first
    // emission and never cleared: a channel reconfigured repeatedly while
    // still unable to bind should say so once, not once per configure
    // (#4333).
    bool mWarnedColorProfileFallback = false;
#endif
};

template<const EmitterProfile& Profile>
class StaticProfileChannel final : public Channel {
public:
    explicit StaticProfileChannel(const ChannelConfig& config) FL_NO_EXCEPT
        : Channel(config.chipset, config.mLeds, config.rgb_order, config.options) {
#ifdef FL_IS_AVR
        FL_STATIC_ASSERT(&Profile == nullptr, "Color profiles are unsupported on AVR");
#endif
    }
 
protected:
#ifndef FL_IS_AVR
    const EmitterProfile* staticEmitterProfile() const FL_NO_EXCEPT override {
#if FL_COLOR_PROFILE_RUNTIME
        return nullptr;
#else
        return &Profile;
#endif
    }
#endif
};

IChannelDriver* getStubChannelEngine() FL_NO_EXCEPT;
 
}  // namespace fl