pixel_controller.h

Go to the documentation of this file.

#pragma once

 
// Note that new code should use the PixelIterator concrete object to write out
// led data.
// Using this class deep in driver code is deprecated because it's templates will
// infact everything it touches. PixelIterator is concrete and doesn't have these
// problems. See PixelController::as_iterator() for how to create a PixelIterator.
 
 
#include "fl/math/intmap.h"
#include "fl/system/sketch_macros.h"  // IWYU pragma: keep  (FL_PLATFORM_HAS_TINY_MEMORY)
#include "fl/math/math8.h"
#include "platforms/is_platform.h"
 
#include "rgbw.h"
#include "fl/gfx/rgbww.h"
#include "fl/gfx/five_bit_hd_gamma.h"
#include "fl/log/log.h"
#include "fl/stl/compiler_control.h"
#include "fl/stl/static_assert.h"
#include "fl/math/scale8.h"
#include "fl/math/math8.h"
#include "eorder.h"
#include "dither_mode.h"
#include "pixel_iterator.h"
#include "crgb.h"
#include "fl/stl/variant.h"  // for PixelControllerAny.
#include "fl/gfx/binary_dither.h"  // last: reads NO_DITHERING, like the code it replaced
 
FL_DISABLE_WARNING_PUSH
FL_DISABLE_WARNING_SIGN_CONVERSION
FL_DISABLE_WARNING_IMPLICIT_INT_CONVERSION
FL_DISABLE_WARNING_FLOAT_CONVERSION
 
 
 
 

#define RO(X) RGB_BYTE(RGB_ORDER, X)

#define RGB_BYTE(RO,X) ((static_cast<int>(RO)>>(3*(2-(X)))) & 0x3)

#define RGB_BYTE0(RO) ((static_cast<int>(RO)>>6) & 0x3)
#define RGB_BYTE1(RO) ((static_cast<int>(RO)>>3) & 0x3)
#define RGB_BYTE2(RO) (static_cast<int>(RO) & 0x3)
 
// operator byte *(struct CRGB[] arr) { return (byte*)arr; }

struct ColorAdjustment {
    CRGB premixed;       
    #if FASTLED_HD_COLOR_MIXING
    CRGB color;          
    fl::u8 brightness;  
    #endif

    static ColorAdjustment noAdjustment() {
        ColorAdjustment adj;
        adj.premixed = CRGB(255, 255, 255);
        #if FASTLED_HD_COLOR_MIXING
        adj.color = CRGB(255, 255, 255);
        adj.brightness = 255;
        #endif
        return adj;
    }
};
 

template<EOrder RGB_ORDER, int LANES=1, fl::u32 MASK=0xFFFFFFFF>
struct PixelController {
    const fl::u8 *mData;    
    int mLen;                
    int mLenRemaining;       
    fl::u8 d[3];            
    fl::u8 e[3];            
    fl::i8 mAdvance;         
    int mOffsets[LANES];     
    ColorAdjustment mColorAdjustment;
 
    enum {
        kLanes = LANES,
        kMask = MASK
    };
    static constexpr EOrder kColorOrder = RGB_ORDER;
 
    FASTLED_FORCE_INLINE fl::PixelIterator as_iterator(const Rgbw& rgbw) {
        return fl::PixelIterator(this, rgbw);
    }
 
    void disableColorAdjustment() {
        #if FASTLED_HD_COLOR_MIXING
        mColorAdjustment.premixed = CRGB(mColorAdjustment.brightness, mColorAdjustment.brightness, mColorAdjustment.brightness);
        mColorAdjustment.color = CRGB(0xff, 0xff, 0xff);
        #endif
    }

    PixelController(const PixelController & other) {
        copy(other);
    }

    PixelController& operator=(const PixelController & other) {
        if (this != &other) {
            copy(other);
        }
        return *this;
    }
 
    template<EOrder RGB_ORDER_OTHER>
    PixelController(const PixelController<RGB_ORDER_OTHER, LANES, MASK> & other) {
        copy(other);
    }
 
    template<typename PixelControllerT>
    void copy(const PixelControllerT& other) {
        FL_STATIC_ASSERT(int(kLanes) == int(PixelControllerT::kLanes), "PixelController lanes must match or mOffsets will be wrong");
        FL_STATIC_ASSERT(int(kMask) == int(PixelControllerT::kMask), "PixelController mask must match or else one or the other controls different lanes");
        d[0] = other.d[0];
        d[1] = other.d[1];
        d[2] = other.d[2];
        e[0] = other.e[0];
        e[1] = other.e[1];
        e[2] = other.e[2];
        mData = other.mData;
        mColorAdjustment = other.mColorAdjustment;
        mAdvance = other.mAdvance;
        mLenRemaining = mLen = other.mLen;
        for(int i = 0; i < LANES; ++i) { mOffsets[i] = other.mOffsets[i]; }
    }

    void initOffsets(int len) {
        int nOffset = 0;
        for(int i = 0; i < LANES; ++i) {
            mOffsets[i] = nOffset;
            if((1<<i) & MASK) { nOffset += (len * mAdvance); }
        }
    }

    PixelController(
            const fl::u8 *d, int len, ColorAdjustment color_adjustment,
            EDitherMode dither, bool advance, fl::u8 skip)
                : mData(d), mLen(len), mLenRemaining(len), mColorAdjustment(color_adjustment) {
        enable_dithering(dither);
        mData += skip;
        mAdvance = (advance) ? 3+skip : 0;
        initOffsets(len);
    }

    PixelController(
            const CRGB *d, int len, ColorAdjustment color_adjustment,
            EDitherMode dither)
                : mData((const fl::u8*)d), mLen(len), mLenRemaining(len), mColorAdjustment(color_adjustment) {
        enable_dithering(dither);
        mAdvance = 3;
        initOffsets(len);
    }

    PixelController(
            const CRGB &d, int len, ColorAdjustment color_adjustment, EDitherMode dither)
                : mData((const fl::u8*)&d), mLen(len), mLenRemaining(len), mColorAdjustment(color_adjustment) {
        enable_dithering(dither);
        mAdvance = 0;
        initOffsets(len);
    }
 
    #if FASTLED_HD_COLOR_MIXING
    fl::u8 global_brightness() const {
        return mColorAdjustment.brightness;
    }
    #endif

    const fl::u8* getRawPixelData() const {
        return mData;
    }
 
 
    // ------------------------------------------------------------------------
    // Temporal dithering. The algorithm, its documentation and its tests live
    // in fl/gfx/binary_dither.h (#4672); these members only bind it to this
    // controller's `d`/`e` state and brightness. `NO_DITHERING=1` selects
    // fl::NoDither, under which all of them compile to nothing except the
    // zeroing of `d`/`e` that hand-written drivers read.
    // ------------------------------------------------------------------------

    void init_binary_dithering() {
        fl::u8 frame = 0;
        if (fl::Dither::kEnabled) {
#if FL_PLATFORM_HAS_TINY_MEMORY
            // Tiny targets retain their one-byte local phase counter.
            static fl::u8 R = 0; // okay static in header: preserves the tiny-target footprint
            frame = ++R;
#else
            // Other targets share a phase once per logical frame.
            frame = fl::detail::ditherFrame();
#endif
        }
        fl::Dither::init(d, e, mColorAdjustment.premixed.raw, frame);
    }

    void reseed_binary_dithering(fl::u8 R) {
        fl::Dither::reseed(d, e, R);
    }

    FASTLED_FORCE_INLINE bool ditherActive() const {
        return fl::Dither::active(e);
    }

    FASTLED_FORCE_INLINE bool has(int n) {
        return mLenRemaining >= n;
    }

    void enable_dithering(EDitherMode dither) {
        switch(dither) {
            case BINARY_DITHER: init_binary_dithering(); break;  // Initialize dithering algorithm
            default: fl::Dither::clear(d, e); break;            // Clear dither values (disabled)
        }
    }

    FASTLED_FORCE_INLINE int size() const { return mLen; }

    FASTLED_FORCE_INLINE int lanes() { return LANES; }

    FASTLED_FORCE_INLINE int advanceBy() { return mAdvance; }

    FASTLED_FORCE_INLINE void advanceData() { mData += mAdvance; --mLenRemaining;}

    FASTLED_FORCE_INLINE void stepDithering() {
            // Toggles d between two values: if d=2 and e=5, becomes 3, then back to 2, etc.
            // This spreads dithering spatially along the strip, preventing visible patterns
            fl::Dither::step(d, e);
    }

    FASTLED_FORCE_INLINE void preStepFirstByteDithering() {
        fl::Dither::stepChannel(d, e, RO(0));
    }

    
    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 loadByte(PixelController & pc) { return pc.mData[RO(SLOT)]; }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 loadByte(PixelController & pc, int lane) { return pc.mData[pc.mOffsets[lane] + RO(SLOT)]; }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 dither(PixelController & pc, fl::u8 b) { return fl::Dither::apply(b, pc.d[RO(SLOT)]); }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 dither(PixelController & , fl::u8 b, fl::u8 d) { return fl::Dither::apply(b, d); }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 scale(PixelController & pc, fl::u8 b) { return fl::scale8(b, pc.mColorAdjustment.premixed.raw[RO(SLOT)]); }
    
    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 scale(PixelController & , fl::u8 b, fl::u8 scale) { return fl::scale8(b, scale); }

 

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 loadAndScale(PixelController & pc) {
        return scale<SLOT>(pc, pc.dither<SLOT>(pc, pc.loadByte<SLOT>(pc)));
    }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 loadAndScale(PixelController & pc, int lane) {
        return scale<SLOT>(pc, pc.dither<SLOT>(pc, pc.loadByte<SLOT>(pc, lane)));
    }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 loadAndScale(PixelController & pc, int lane, fl::u8 d, fl::u8 scale) {
        return fl::scale8(pc.dither<SLOT>(pc, pc.loadByte<SLOT>(pc, lane), d), scale);
    }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 loadAndScale(PixelController & pc, int lane, fl::u8 scale) { return fl::scale8(pc.loadByte<SLOT>(pc, lane), scale); }
 

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 advanceAndLoadAndScale(PixelController & pc) { pc.advanceData(); return pc.loadAndScale<SLOT>(pc); }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 advanceAndLoadAndScale(PixelController & pc, int lane) { pc.advanceData(); return pc.loadAndScale<SLOT>(pc, lane); }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 advanceAndLoadAndScale(PixelController & pc, int lane, fl::u8 scale) { pc.advanceData(); return pc.loadAndScale<SLOT>(pc, lane, scale); }

 


    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 getd(PixelController & pc) { return pc.d[RO(SLOT)]; }

    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 getscale(PixelController & pc) { return pc.mColorAdjustment.premixed.raw[RO(SLOT)]; }

 

 
    // Helper functions to get around gcc stupidities
    FASTLED_FORCE_INLINE fl::u8 loadAndScale0(int lane, fl::u8 scale) { return loadAndScale<0>(*this, lane, scale); }  
    FASTLED_FORCE_INLINE fl::u8 loadAndScale1(int lane, fl::u8 scale) { return loadAndScale<1>(*this, lane, scale); }  
    FASTLED_FORCE_INLINE fl::u8 loadAndScale2(int lane, fl::u8 scale) { return loadAndScale<2>(*this, lane, scale); }  
    FASTLED_FORCE_INLINE fl::u8 advanceAndLoadAndScale0(int lane, fl::u8 scale) { return advanceAndLoadAndScale<0>(*this, lane, scale); }  
    FASTLED_FORCE_INLINE fl::u8 stepAdvanceAndLoadAndScale0(int lane, fl::u8 scale) { stepDithering(); return advanceAndLoadAndScale<0>(*this, lane, scale); }  
 
    FASTLED_FORCE_INLINE fl::u8 loadAndScale0(int lane) { return loadAndScale<0>(*this, lane); }  
    FASTLED_FORCE_INLINE fl::u8 loadAndScale1(int lane) { return loadAndScale<1>(*this, lane); }  
    FASTLED_FORCE_INLINE fl::u8 loadAndScale2(int lane) { return loadAndScale<2>(*this, lane); }  
    FASTLED_FORCE_INLINE fl::u8 advanceAndLoadAndScale0(int lane) { return advanceAndLoadAndScale<0>(*this, lane); }  
    FASTLED_FORCE_INLINE fl::u8 stepAdvanceAndLoadAndScale0(int lane) { stepDithering(); return advanceAndLoadAndScale<0>(*this, lane); }  
 
    // LoadAndScale0 loads the pixel data in the order specified by RGB_ORDER and then scales it by the color correction values
    // For example in color order GRB, loadAndScale0() will return the green channel scaled by the color correction value for green.
    FASTLED_FORCE_INLINE fl::u8 loadAndScale0() { return loadAndScale<0>(*this); }  
    FASTLED_FORCE_INLINE fl::u8 loadAndScale1() { return loadAndScale<1>(*this); }  
    FASTLED_FORCE_INLINE fl::u8 loadAndScale2() { return loadAndScale<2>(*this); }  
    FASTLED_FORCE_INLINE fl::u8 advanceAndLoadAndScale0() { return advanceAndLoadAndScale<0>(*this); }  
    FASTLED_FORCE_INLINE fl::u8 stepAdvanceAndLoadAndScale0() { stepDithering(); return advanceAndLoadAndScale<0>(*this); }  
 
    FASTLED_FORCE_INLINE fl::u8 getScale0() { return getscale<0>(*this); }  
    FASTLED_FORCE_INLINE fl::u8 getScale1() { return getscale<1>(*this); }  
    FASTLED_FORCE_INLINE fl::u8 getScale2() { return getscale<2>(*this); }  
 
    #if FASTLED_HD_COLOR_MIXING
    template<int SLOT>  FASTLED_FORCE_INLINE static fl::u8 getScaleFullBrightness(PixelController & pc) { return pc.mColorAdjustment.color.raw[RO(SLOT)]; }

    FASTLED_FORCE_INLINE void loadRGBScaleAndBrightness(fl::u8* c0, fl::u8* c1, fl::u8* c2, fl::u8* brightness) {
        *c0 = getScaleFullBrightness<0>(*this);
        *c1 = getScaleFullBrightness<1>(*this);
        *c2 = getScaleFullBrightness<2>(*this);
        *brightness = mColorAdjustment.brightness;
    }

    FL_DEPRECATED("Use loadRGBScaleAndBrightness() instead")
    FASTLED_FORCE_INLINE void getHdScale(fl::u8* c0, fl::u8* c1, fl::u8* c2, fl::u8* brightness) {
        loadRGBScaleAndBrightness(c0, c1, c2, brightness);
    }

    FASTLED_FORCE_INLINE fl::u8 getBrightness() {
        return mColorAdjustment.brightness;
    }
    #endif
 
    // NOTE: loadAndScale_APA102_HD() has been moved to src/fl/chipsets/encoders/apa102.h
    // Use fl::loadAndScale_APA102_HD<RGB_ORDER>(pixels, ...) instead
 
    FASTLED_FORCE_INLINE void loadAndScaleRGB(fl::u8 *b0_out, fl::u8 *b1_out,
                                              fl::u8 *b2_out) {
        *b0_out = loadAndScale0();
        *b1_out = loadAndScale1();
        *b2_out = loadAndScale2();
    }
 
    // NOTE: loadAndScale_WS2816_HD() has been moved to src/fl/chipsets/encoders/ws2816.h
    // Use fl::loadAndScale_WS2816_HD<RGB_ORDER>(pixels, ...) instead

    FASTLED_FORCE_INLINE fl::u8 loadAndScaleChannel(fl::u8 c) {
        const fl::u8 b = mData[c];
        return fl::scale8(fl::Dither::apply(b, d[c]), mColorAdjustment.premixed.raw[c]);
    }

    FASTLED_FORCE_INLINE void loadAndScaleRGBWUnordered(
        const Rgbw& rgbw, fl::u8 *r_out, fl::u8 *g_out, fl::u8 *b_out,
        fl::u8 *w_out) {
#ifdef FL_IS_AVR
        FL_UNUSED(rgbw);
        // No RGBW conversion on AVR; W stays black, as in loadAndScaleRGBW.
        *r_out = loadAndScaleChannel(0);
        *g_out = loadAndScaleChannel(1);
        *b_out = loadAndScaleChannel(2);
        *w_out = 0;
#else
        const CRGB rgb(mData[0], mData[1], mData[2]);
        *w_out = 0;
        fl::rgb_2_rgbw(rgbw,
                   rgb.r, rgb.g, rgb.b,
                   mColorAdjustment.premixed.r, mColorAdjustment.premixed.g, mColorAdjustment.premixed.b,
                   r_out, g_out, b_out, w_out);
#endif
    }

    FASTLED_FORCE_INLINE void loadAndScaleRGBWWUnordered(
        fl::Rgbww rgbww, fl::u8 *r_out, fl::u8 *g_out, fl::u8 *b_out,
        fl::u8 *ww_out, fl::u8 *wc_out) {
#ifdef FL_IS_AVR
        FL_UNUSED(rgbww);
        FL_WARN_ONCE("RGBWW colorimetric is not supported on AVR -- the warm "
                     "and cool white channels will be black. Use an ESP32 / "
                     "Teensy / RP2040 target for full RGBWW support.");
        *r_out = loadAndScaleChannel(0);
        *g_out = loadAndScaleChannel(1);
        *b_out = loadAndScaleChannel(2);
        *ww_out = 0;
        *wc_out = 0;
#else
        const CRGB rgb(mData[0], mData[1], mData[2]);
        *ww_out = 0;
        *wc_out = 0;
        fl::rgb_2_rgbww(rgbww,
                        rgb.r, rgb.g, rgb.b,
                        mColorAdjustment.premixed.r,
                        mColorAdjustment.premixed.g,
                        mColorAdjustment.premixed.b,
                        r_out, g_out, b_out, ww_out, wc_out);
#endif
    }
 
    FASTLED_FORCE_INLINE void loadAndScaleRGBW(
        const Rgbw& rgbw, fl::u8 *b0_out, fl::u8 *b1_out,
        fl::u8 *b2_out, fl::u8 *b3_out) {
#ifdef FL_IS_AVR
        // Don't do RGBW conversion for AVR, just set the W pixel to black.
        fl::u8 out[4] = {
            // Get the pixels in native order.
            loadAndScale0(),
            loadAndScale1(),
            loadAndScale2(),
            0,
        };
        EOrderW w_placement = rgbw.w_placement;
        // Apply w-component insertion.
        fl::rgbw_partial_reorder(
            w_placement, out[0], out[1], out[2],
            0, // Pre-ordered RGB data with a 0 white component.
            b0_out, b1_out, b2_out, b3_out);
#else
        const fl::u8 b0_index = RGB_BYTE0(RGB_ORDER);  // Needed to re-order RGB back into led native order.
        const fl::u8 b1_index = RGB_BYTE1(RGB_ORDER);
        const fl::u8 b2_index = RGB_BYTE2(RGB_ORDER);
        // Source-order RGB after white extraction, then the wire reorder.
        CRGB rgb;
        fl::u8 w = 0;
        loadAndScaleRGBWUnordered(rgbw, &rgb.r, &rgb.g, &rgb.b, &w);
        // Now finish the ordering so that the output is in the native led order for all of RGBW.
        fl::rgbw_partial_reorder(
            rgbw.w_placement,
            rgb.raw[b0_index],  // in-place re-ordering for the RGB data.
            rgb.raw[b1_index],
            rgb.raw[b2_index],
            w,  // The white component is not ordered in this call.
            b0_out, b1_out, b2_out, b3_out);  // RGBW data now in total native led order.
#endif
    }

    FASTLED_FORCE_INLINE void loadAndScaleRGBWW(fl::Rgbww rgbww,
                                                fl::u8 *b0_out, fl::u8 *b1_out,
                                                fl::u8 *b2_out, fl::u8 *b3_out,
                                                fl::u8 *b4_out) {
#ifdef FL_IS_AVR
        // AVR: float colorimetric math is too expensive on the 8-bit core;
        // the strip will get RGB-only output with both white channels black.
        // Surface this with a FL_WARN_ONCE so the silent dropout is visible
        // when debugging — a user configuring RGBWW on an AVR target almost
        // certainly didn't expect their warm/cool W channels to be inert.
        FL_WARN_ONCE("RGBWW colorimetric is not supported on AVR — the warm "
                     "and cool white channels will be black. Use an ESP32 / "
                     "Teensy / RP2040 target for full RGBWW support.");
        fl::u8 r_pre = loadAndScale0();
        fl::u8 g_pre = loadAndScale1();
        fl::u8 b_pre = loadAndScale2();
        fl::rgbww_partial_reorder(
            rgbww.w_placement,
            r_pre, g_pre, b_pre,
            0, 0,
            b0_out, b1_out, b2_out, b3_out, b4_out);
#else
        const fl::u8 b0_index = RGB_BYTE0(RGB_ORDER);
        const fl::u8 b1_index = RGB_BYTE1(RGB_ORDER);
        const fl::u8 b2_index = RGB_BYTE2(RGB_ORDER);
        CRGB rgb;
        fl::u8 ww = 0;
        fl::u8 wc = 0;
        loadAndScaleRGBWWUnordered(rgbww, &rgb.r, &rgb.g, &rgb.b, &ww, &wc);
        fl::rgbww_partial_reorder(
            rgbww.w_placement,
            rgb.raw[b0_index],
            rgb.raw[b1_index],
            rgb.raw[b2_index],
            ww, wc,
            b0_out, b1_out, b2_out, b3_out, b4_out);
#endif
    }
};
 
/*
using fl::RGB;
using fl::RBG;
using fl::GRB;
using fl::GBR;
using fl::BRG;
using fl::BGR;
*/
 
 
 
 
 
 
 
FL_DISABLE_WARNING_POP