slim_bridge_controller.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/static_assert.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/vector.h"
 
#include "cpixel_ledcontroller.h"
#include "fl/channels/data.h"
#include "fl/channels/driver.h"
#include "fl/channels/manager.h"
#include "fl/channels/bus_traits.h"  // IWYU pragma: keep (DriverTraits<Bus::X> satisfies the DriverTraits contract)
#include "fl/channels/config.h"
#include "fl/chipsets/encoders/pixel_iterator.h"
#include "fl/log/log.h"
#include "fl/system/sketch_macros.h"

#ifndef FL_SLIM_BRIDGE_DIRECT_SHOW
#define FL_SLIM_BRIDGE_DIRECT_SHOW (!FL_PLATFORM_HAS_LARGE_MEMORY)
#endif
 
namespace fl {

template <bool DIRECT_SHOW>
struct SlimBridgeShowPolicy;

template <>
struct SlimBridgeShowPolicy<false> {
    template <typename DriverTraits>
    static void attach() FL_NO_EXCEPT { DriverTraits::registerWithManager(); }
    static bool enabled(IChannelDriver& driver) FL_NO_EXCEPT {
        return ChannelManager::registry().isDriverEnabled(driver.getName().c_str());
    }
    static void afterEnqueue(IChannelDriver&) FL_NO_EXCEPT {}
};

template <>
struct SlimBridgeShowPolicy<true> {
    template <typename DriverTraits>
    static void attach() FL_NO_EXCEPT {}
    static bool enabled(IChannelDriver&) FL_NO_EXCEPT { return true; }
    static void afterEnqueue(IChannelDriver& driver) FL_NO_EXCEPT { driver.show(); }
};

template <int DATA_PIN, typename TIMING, EOrder RGB_ORDER, int WAIT_TIME, typename DriverTraits,
          int XTRA0 = 0, bool DIRECT_SHOW = (FL_SLIM_BRIDGE_DIRECT_SHOW != 0)>
class SlimBridgeController : public CPixelLEDController<RGB_ORDER> {
    using Policy = SlimBridgeShowPolicy<DIRECT_SHOW>;
 
public:
    SlimBridgeController() FL_NO_EXCEPT {
        ChipsetTimingConfig timing = makeTimingConfig<TIMING>();
        // (A?) Fold WAIT_TIME (microseconds) into reset_us, mirroring the
        // historical ClocklessIdf4 behavior: the driver must honor whichever
        // is longer -- the chipset's own latch/reset requirement, or the
        // caller-requested minimum inter-frame wait.
        if (WAIT_TIME > 0 && static_cast<u32>(WAIT_TIME) > timing.reset_us) {
            timing.reset_us = static_cast<u32>(WAIT_TIME);
        }
        mData = ChannelData::create(DATA_PIN, timing, fl::vector_psram<u8>(),
                                     ChannelPixelFormat::RGB);
        FL_STATIC_ASSERT(XTRA0 >= 0 && XTRA0 <= 32, "XTRA0 out of range");
        mData->setExtraZeroBitsPerByte(static_cast<u8>(XTRA0));
        // Idempotent by contract -- safe to call from every instantiation's
        // constructor (mirrors ClocklessIdf5's registerWithManager() call).
        // A no-op in direct-show mode.
        Policy::template attach<DriverTraits>();
    }
 
    void init() FL_NO_EXCEPT override {}

    const ChannelDataPtr& channelData() const FL_NO_EXCEPT { return mData; }
 
protected:
    void showPixels(PixelController<RGB_ORDER>& pixels) FL_NO_EXCEPT override {
        IChannelDriver& driver = DriverTraits::instance();
 
        // (A1) Respect runtime driver enable/disable: ChannelManager is the
        // single source of truth. A disabled driver means "drop this frame",
        // not "enqueue and hope" -- silently enqueuing to a disabled driver
        // is the #2517 silent-drop failure mode.
        if (!Policy::enabled(driver)) {
            FL_WARN_ONCE("SlimBridgeController: driver '" << driver.getName().c_str() << "' is disabled - dropping frame");
            return;
        }
 
        // (A8) If the previous frame's buffer is still in flight, block
        // (bounded) until the driver reports it can accept more work rather
        // than racing the driver's in-progress DMA/RMT transfer.
        if (mData->isInUse()) {
            if (!driver.waitForReady()) {
                FL_WARN_ONCE("SlimBridgeController: driver '" << driver.getName().c_str() << "' did not become ready in time - dropping frame");
                return;
            }
        }
 
        // Give subclasses a chance to observe the accepted frame before it is
        // encoded (e.g. feeding ActiveStripTracker for stub/WASM channels).
        onBeforeEncode(pixels);
 
        // (A5) Publish the pixel byte layout so the driver (and any
        // downstream padding/diagnostic code) knows the encoded stride.
        if (this->getRgbww().active()) {
            mData->setPixelFormat(ChannelPixelFormat::RGBWW);
        } else if (this->getRgbw().active()) {
            mData->setPixelFormat(ChannelPixelFormat::RGBW);
        } else {
            mData->setPixelFormat(ChannelPixelFormat::RGB);
        }
 
        // (A3) Re-encode into the same buffer every frame -- clear() keeps
        // capacity, so steady-state operation is allocation-free.
        mData->getData().clear();
        fl::PixelIterator iterator(&pixels, this->getRgbw(), this->getRgbww());
        iterator.writeWS2812(&mData->getData());
 
        driver.enqueue(mData);
        Policy::afterEnqueue(driver);
    }

    virtual void onBeforeEncode(PixelController<RGB_ORDER>& pixels) FL_NO_EXCEPT { (void)pixels; }
 
private:
    ChannelDataPtr mData;
};
 
}  // namespace fl