◆ showPixels()

void fl::Channel::showPixels ( PixelController< RGB, 1, 0xFFFFFFFF > & pixels )
overrideprotected
Definition at line 449 of file channel.cpp.hpp.
                                                                    {
    FL_SCOPED_TRACE;
 
    // Safety check: don't modify buffer if driver is currently transmitting it
    if (mChannelData->isInUse()) {
        FL_WARN("Channel '" << mName << "': showPixels() called while mChannelData is in use by driver, attempting to wait");
        auto driver = mDriver.lock();
        if (!driver) {
            FL_ERROR("Channel '" << mName << "': No driver bound yet the mChannelData is in use - cannot transmit");
            return;
        }
        // wait until the driver is in a READY state.
        bool ok = driver->waitForReady();
        if (!ok) {
            FL_ERROR("Channel '" << mName << "': Timeout occurred while waiting for driver to become READY");
            return;
        }
        FL_WARN("Channel '" << mName << "': Engine became READY after waiting");
    }
 
    // Phase 5b of #2428: if the driver was pre-bound via setDriver() (legacy
    // addLeds<>-style controllers naming BusTraits<Bus::X>::instancePtr() in
    // their constructor), bypass ChannelManager entirely. Channels created via
    // the manager-based API (Channel::create(cfg) without affinity) keep their
    // existing per-frame re-selection so users can swap drivers at runtime.
    //
    // **Fast path (#2773 item 2.1):** the legacy `addLeds<NEOPIXEL>` flow is
    // by far the hot per-frame path on stock Blink. It needs no busKey
    // construction, no dynamic driver lookup, no busKey-miss diagnostics,
    // and no fallback `FL_ERROR` reporting — the driver was already pre-bound
    // in the controller's constructor. Pulling all of that boilerplate out
    // of `showPixels` lets the compiler keep the hot path compact and lets
    // the slow path's `fl::string` ops / `ChannelManager::selectDriverForChannel`
    // / diagnostic literals tree-shake on the slow-path branch's coldness.
    fl::shared_ptr<IChannelDriver> driver;
    if (mDriverPreBound) {
        driver = mDriver.lock();
        if (!driver) {
            // Pre-bound driver got destroyed (singleton shutdown, etc.). Silent
            // bail — this is unrecoverable from showPixels.
            return;
        }
    } else {
#if !defined(FASTLED_DISABLE_DYNAMIC_DRIVER) || !FASTLED_DISABLE_DYNAMIC_DRIVER
        driver = resolveDynamicDriver();
        if (!driver) {
            return;
        }
#else
        // Dynamic-driver lookup gated out via FASTLED_DISABLE_DYNAMIC_DRIVER
        // (#2926). The else branch is dead at runtime for every legacy
        // `addLeds<>` flavor — those pre-bind their driver in the ctor. The
        // gate lets `--gc-sections` drop the resolveDynamicDriver body plus
        // the ChannelManager::findDriverByName / selectDriverForChannel
        // chain (~400-900 B). Channels created via `Channel::create(cfg)`
        // without a pre-bound driver silently emit nothing under this flag —
        // user accepts the constraint.
        return;
#endif
    }
 
    // Build pixel iterator with optional addressing transformation
    // (#2558) Pass both Rgbw and Rgbww from the channel options; the iterator
    // carries both, and the encoder dispatch below picks the right path based
    // on which variant alternative ChannelOptions::mWhiteCfg holds.
    ReorderingPixelIteratorAny iterator(pixels, mScreenMap.getXYMap(), mRgbOrder,
                                        mSettings.rgbw(), mSettings.rgbww(),
                                        mName);
    PixelIterator& pixelIterator = iterator.get();
 
    // Encode pixels based on chipset type
    auto& data = mChannelData->getData();
    data.clear();
 
    if (mChipset.is<ClocklessChipset>()) {
        // Clockless chipsets: dispatch based on encoder type
        const ClocklessChipset* clockless = mChipset.ptr<ClocklessChipset>();
        switch (clockless->encoder) {
            case ClocklessEncoder::CLOCKLESS_ENCODER_WS2812:
                pixelIterator.writeWS2812(&data);
                break;
#if !defined(FASTLED_DISABLE_UCS7604) || !FASTLED_DISABLE_UCS7604
            // Gated by FASTLED_DISABLE_UCS7604 (#2920). For WS2812-only
            // sketches the UCS7604 case is dead at runtime, but each
            // `writeUCS7604(...)` reference is statically reachable,
            // keeping the encoder bodies linked. Setting
            // `-DFASTLED_DISABLE_UCS7604=1` drops the case + the
            // `encodeUCS7604_16bit_RGB` / `encodeUCS7604_16bit_RGBW`
            // template instantiations (~400-600 B). When the gate is
            // enabled, calling showPixels() on a UCS7604 channel
            // silently emits nothing.
            case ClocklessEncoder::CLOCKLESS_ENCODER_UCS7604_8BIT:
            case ClocklessEncoder::CLOCKLESS_ENCODER_UCS7604_16BIT:
            case ClocklessEncoder::CLOCKLESS_ENCODER_UCS7604_16BIT_1600:
                writeUCS7604(&data, pixelIterator, clockless->encoder,
                             mSettings, mRgbOrder);
                break;
#endif  // !FASTLED_DISABLE_UCS7604
        }
#if !defined(FASTLED_DISABLE_SPI_CHIPSETS) || !FASTLED_DISABLE_SPI_CHIPSETS
    } else if (mChipset.is<SpiChipsetConfig>()) {
        // SPI chipsets: dispatch based on chipset type (zero allocation).
        //
        // Gated by FASTLED_DISABLE_SPI_CHIPSETS (#2913). For NEOPIXEL-only
        // sketches on ESP32-S3 the SPI branch is dead at runtime, but the
        // compiler cannot prove that — each pixelIterator.writeXXX(...)
        // reference below is statically reachable, keeping ~720 B of
        // encoder bodies (writeAPA102, writeSK9822, writeLPD8806,
        // writeSM16716) plus the 11-case switch table linked. Setting
        // `-DFASTLED_DISABLE_SPI_CHIPSETS=1` in build_flags drops the
        // whole branch and recovers ~1.0-1.2 KB on a NEOPIXEL Blink.
        //
        // When the gate is enabled, calling showPixels() on an
        // SpiChipsetConfig channel silently emits nothing — the user
        // accepts that constraint by setting the flag.
        const SpiChipsetConfig* spi = mChipset.ptr<SpiChipsetConfig>();
        const SpiEncoder& config = spi->timing;
 
        // Switch on enum WITHOUT default case - compiler will warn if new enum values are added
        // TODO: Consolidate these PixelIterator methods with template controllers in src/fl/chipsets/
        switch (config.chipset) {
            case SpiChipset::APA102:
            case SpiChipset::DOTSTAR:
            case SpiChipset::HD107:
                pixelIterator.writeAPA102(&data, false);
                break;
 
            case SpiChipset::APA102HD:
            case SpiChipset::DOTSTARHD:
            case SpiChipset::HD107HD:
                pixelIterator.writeAPA102(&data, true);
                break;
 
            case SpiChipset::SK9822:
                pixelIterator.writeSK9822(&data, false);
                break;
 
            case SpiChipset::SK9822HD:
                pixelIterator.writeSK9822(&data, true);
                break;
 
            case SpiChipset::WS2801:
                pixelIterator.writeWS2801(&data);
                break;
 
            case SpiChipset::WS2803:
                pixelIterator.writeWS2803(&data);
                break;
 
            case SpiChipset::P9813:
                pixelIterator.writeP9813(&data);
                break;
 
            case SpiChipset::LPD8806:
                pixelIterator.writeLPD8806(&data);
                break;
 
            case SpiChipset::LPD6803:
                pixelIterator.writeLPD6803(&data);
                break;
 
            case SpiChipset::SM16716:
                pixelIterator.writeSM16716(&data);
                break;
 
            case SpiChipset::HD108:
                pixelIterator.writeHD108(&data);
                break;
        }
        // No default case - compiler will error if any enum value is missing
    }
#endif  // !FASTLED_DISABLE_SPI_CHIPSETS
 
    // Fire event after encoding completes
    {
        auto& events = ChannelEvents::instance();
        events.onChannelDataEncoded(*this, *mChannelData);
    }
 
 
 
    // #2517: detect the silent-drop scenario before enqueuing — if the
    // resolved driver is registered with ChannelManager but currently
    // disabled (typically by `FastLED.setExclusiveDriver<OtherBus>()`),
    // `ChannelManager::onEndFrame()` will skip its `show()` call and the
    // frame is silently dropped on the floor. Emit an actionable
    // FL_ERROR so users can diagnose the missing output.
    //
    // One-shot via `mDisabledDriverWarned` to avoid per-frame spam.
    // Reset the latch whenever the driver returns to ENABLED so a later
    // disable re-emits the diagnostic.
    fl::string driverName = driver->getName();
    auto status = ChannelManager::instance().driverStatus(driverName);
    if (status == ChannelManager::DriverStatus::STATUS_DISABLED) {
#if FASTLED_LOG_RUNTIME_ENABLED
        if (!mDisabledDriverWarned) {
            emitDisabledDriverError(
                mName, driverName,
                ChannelManager::instance().exclusiveDriverName());
            mDisabledDriverWarned = true;
        }
#endif
        // Skip the enqueue — the data wouldn't be sent anyway, and dropping
        // it here matches the existing behaviour (rather than leaving stale
        // bytes in the driver's pending queue across an enable/disable flip).
        // The drop happens in both debug and release; only the diagnostic
        // and the one-shot latch are gated. In release, the empty
        // emitDisabledDriverError + the exclusiveDriverName() call + the
        // 3-arg fl::string chain dead-strip (see #2950).
        return;
    } else if (status == ChannelManager::DriverStatus::STATUS_ENABLED) {
#if FASTLED_LOG_RUNTIME_ENABLED
        // Reset the one-shot guard so a future disable re-emits the diagnostic.
        mDisabledDriverWarned = false;
#endif
    }
    // NOT_REGISTERED: driver is not managed by ChannelManager (e.g. a custom
    // test driver, or one that was removed). Fall through to enqueue and let
    // the driver decide what to do — this is the historic behaviour.
 
    // Enqueue for transmission (will be sent when driver->show() is called)
    driver->enqueue(mChannelData);
    auto& events = ChannelEvents::instance();
    events.onChannelEnqueued(*this, driver->getName());
}
Here is the call graph for this function: