init_binary_dithering()

template<EOrder RGB_ORDER, int LANES = 1, fl::u32 MASK = 0xFFFFFFFF>

void PixelController< RGB_ORDER, LANES, MASK >::init_binary_dithering ( )

inline

Set up the values for binary dithering.

See also

"TEMPORAL DITHERING: THE COMPLETE GUIDE" section above (line 195)

Definition at line 309 of file pixel_controller.h.

                                 {
#if !defined(NO_DITHERING) || (NO_DITHERING != 1)
        // STEP 1: Increment frame counter (creates temporal variation)
        static fl::u8 R = 0; // okay static in header
        ++R;
 
        // STEP 2: Wrap counter at 2^ditherBits (creates 8-frame cycle: 0,1,2,3,4,5,6,7,0...)
        fl::u8 ditherBits = VIRTUAL_BITS;
        R &= (0x01 << ditherBits) - 1;
 
        // STEP 3: Bit-reverse R to create maximally-spaced pattern Q
        // Why? Prevents visible ramping patterns. Turns 0,1,2,3,4,5,6,7 → 0,128,64,192,32,160,96,224
        fl::u8 Q = 0;
 
        // Bit reversal magic: mirrors bit positions (bit 0 ↔ bit 7, bit 1 ↔ bit 6, etc.)
        {
            if(R & 0x01) { Q |= 0x80; }
            if(R & 0x02) { Q |= 0x40; }
            if(R & 0x04) { Q |= 0x20; }
            if(R & 0x08) { Q |= 0x10; }
            if(R & 0x10) { Q |= 0x08; }
            if(R & 0x20) { Q |= 0x04; }
            if(R & 0x40) { Q |= 0x02; }
            if(R & 0x80) { Q |= 0x01; }
        }
 
        // STEP 4: Center the pattern (shifts values to middle of quantization bins)
        // Example: 0,128,64,192 becomes 16,144,80,208 (adds 16 when ditherBits=3)
        if( ditherBits < 8) {
            Q += 0x01 << (7 - ditherBits);
        }
 
        // STEP 5: Scale per-channel based on brightness
        // Key insight: Lower brightness needs BIGGER dithering offsets!
        // e[i] = max dither range (inversely proportional to brightness)
        // d[i] = current dither offset (Q scaled by e[i])
        for(int i = 0; i < 3; ++i) {
                fl::u8 s = mColorAdjustment.premixed.raw[i];  // Brightness scale factor
 
                // Calculate max dither range: e = 256/brightness
                // At 100% (255): e≈1 (tiny range), At 20% (51): e≈5 (large range)
                e[i] = s ? (256/s) + 1 : 0;
 
                // Scale Q by the dither range to get current offset
                d[i] = fl::scale8(Q, e[i]);
 
#if (FASTLED_SCALE8_FIXED == 1)
                // Adjust for scale8 implementation quirk
                if(d[i]) (--d[i]);
#endif
                // Finalize e[i] value for later toggling
                if(e[i]) --e[i];
        }
#endif
    }

References d, e, mColorAdjustment, and VIRTUAL_BITS.

Referenced by enable_dithering().

Here is the caller graph for this function: