submitFrame()

void fl::Channel::submitFrame ( const fl::shared_ptr< IChannelDriver > & driver )

private

Submit the encoded frame to driver: disabled-driver drop + one-shot diagnostic, enqueue, dither advance, and onChannelEnqueued (#4566).

Definition at line 976 of file channel.cpp.hpp.

                                                                                 {
    // #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);
    // Presented, per the driver contract: an accepted enqueue is the frame.
    ++mDitherPhase;
    auto& events = ChannelEvents::instance();
    // Reuse the name fetched for driverStatus() instead of a second getName().
    events.onChannelEnqueued(*this, driverName);
}

References fl::ChannelManager::driverStatus(), fl::FL_NO_EXCEPT, fl::ChannelEvents::instance(), fl::ChannelManager::instance(), mChannelData, mDisabledDriverWarned, mDitherPhase, mName, fl::ChannelManager::STATUS_DISABLED, and fl::ChannelManager::STATUS_ENABLED.

Referenced by showPixels().

Here is the call graph for this function:

Here is the caller graph for this function: