ucs7604.h

Go to the documentation of this file.

#pragma once

 
#include "fl/stl/stdint.h"
#include "fl/math/ease.h"
#include "fl/chipsets/encoders/pixel_iterator_adapters.h"
#include "fl/stl/compiler_control.h"  // IWYU pragma: keep  (FL_UNUSED)
#include "fl/stl/noexcept.h"
#include "fl/system/sketch_macros.h"  // IWYU pragma: keep  (FL_PLATFORM_HAS_TINY_MEMORY)
 
namespace fl {

enum class UCS7604Mode {
    UCS7604_MODE_8BIT_800KHZ = 0x03,
    UCS7604_MODE_16BIT_800KHZ = 0x8B,
    UCS7604_MODE_16BIT_1600KHZ = 0x9B // not implemented because of timing difference.
};

struct UCS7604CurrentControl {
    u8 r;  
    u8 g;  
    u8 b;  
    u8 w;  

    UCS7604CurrentControl() FL_NO_EXCEPT : r(0xF), g(0xF), b(0xF), w(0xF) {}

    explicit UCS7604CurrentControl(u8 brightness)
        FL_NO_EXCEPT : r(brightness & 0xF), g(brightness & 0xF), b(brightness & 0xF), w(brightness & 0xF) {}

    UCS7604CurrentControl(u8 r_, u8 g_, u8 b_, u8 w_)
        FL_NO_EXCEPT : r(r_ & 0xF), g(g_ & 0xF), b(b_ & 0xF), w(w_ & 0xF) {}
};

template <typename OutputIterator>
void buildUCS7604Preamble(OutputIterator out, UCS7604Mode mode,
                          u8 r_current, u8 g_current,
                          u8 b_current, u8 w_current) FL_NO_EXCEPT {
    // Sync pattern (6 bytes)
    *out++ = 0xFF;
    *out++ = 0xFF;
    *out++ = 0xFF;
    *out++ = 0xFF;
    *out++ = 0xFF;
    *out++ = 0xFF;
 
    // Header (2 bytes)
    *out++ = 0x00;
    *out++ = 0x03;
 
    // Mode byte
    *out++ = static_cast<u8>(mode);
 
    // Current control (4 bytes, 4-bit each, wire order RGBW)
    *out++ = r_current & 0x0F;
    *out++ = g_current & 0x0F;
    *out++ = b_current & 0x0F;
    *out++ = w_current & 0x0F;
 
    // Reserved (2 bytes)
    *out++ = 0x00;
    *out++ = 0x00;
}

template <typename InputIterator, typename OutputIterator>
void encodeUCS7604_8bit_RGB(InputIterator first, InputIterator last, OutputIterator out) FL_NO_EXCEPT {
    while (first != last) {
        const auto& pixel = *first;
        *out++ = pixel[0];  // R
        *out++ = pixel[1];  // G
        *out++ = pixel[2];  // B
        ++first;
    }
}

template <typename InputIterator, typename OutputIterator>
void encodeUCS7604_8bit_RGBW(InputIterator first, InputIterator last, OutputIterator out) FL_NO_EXCEPT {
    while (first != last) {
        const auto& pixel = *first;
        *out++ = pixel[0];  // R
        *out++ = pixel[1];  // G
        *out++ = pixel[2];  // B
        *out++ = pixel[3];  // W
        ++first;
    }
}

template <typename InputIterator, typename OutputIterator>
void encodeUCS7604_16bit_RGB(InputIterator first, InputIterator last, OutputIterator out,
                              const Gamma8& gamma) FL_NO_EXCEPT {
    while (first != last) {
        const auto& pixel = *first;
 
        // Apply gamma correction for 16-bit output
        u8 rgb_in[3] = { pixel[0], pixel[1], pixel[2] };
        u16 rgb_out[3];
        gamma.convert(fl::span<const u8>(rgb_in, 3), fl::span<u16>(rgb_out, 3));
 
        // Write big-endian 16-bit values
        *out++ = rgb_out[0] >> 8;
        *out++ = rgb_out[0] & 0xFF;
        *out++ = rgb_out[1] >> 8;
        *out++ = rgb_out[1] & 0xFF;
        *out++ = rgb_out[2] >> 8;
        *out++ = rgb_out[2] & 0xFF;
        ++first;
    }
}

#if !FL_PLATFORM_HAS_TINY_MEMORY
template <typename OutputIterator>
void encodeUCS7604_16bit_RGB_wide(PixelIterator& pixels, OutputIterator out) FL_NO_EXCEPT {
    while (pixels.has(1)) {
        u16 r16, g16, b16;
        pixels.loadAndScaleRGB16(&r16, &g16, &b16);
        *out++ = r16 >> 8;
        *out++ = r16 & 0xFF;
        *out++ = g16 >> 8;
        *out++ = g16 & 0xFF;
        *out++ = b16 >> 8;
        *out++ = b16 & 0xFF;
        pixels.stepDithering();
        pixels.advanceData();
    }
}
#endif  // !FL_PLATFORM_HAS_TINY_MEMORY

template <typename InputIterator, typename OutputIterator>
void encodeUCS7604_16bit_RGBW(InputIterator first, InputIterator last, OutputIterator out,
                               const Gamma8& gamma) FL_NO_EXCEPT {
    while (first != last) {
        const auto& pixel = *first;
 
        // Apply gamma correction for 16-bit output
        u8 rgbw_in[4] = { pixel[0], pixel[1], pixel[2], pixel[3] };
        u16 rgbw_out[4];
        gamma.convert(fl::span<const u8>(rgbw_in, 4), fl::span<u16>(rgbw_out, 4));
 
        // Write big-endian 16-bit values
        *out++ = rgbw_out[0] >> 8;
        *out++ = rgbw_out[0] & 0xFF;
        *out++ = rgbw_out[1] >> 8;
        *out++ = rgbw_out[1] & 0xFF;
        *out++ = rgbw_out[2] >> 8;
        *out++ = rgbw_out[2] & 0xFF;
        *out++ = rgbw_out[3] >> 8;
        *out++ = rgbw_out[3] & 0xFF;
        ++first;
    }
}

inline size_t ucs7604BytesPerLed(UCS7604Mode mode, bool is_rgbw) FL_NO_EXCEPT {
    if (mode == UCS7604Mode::UCS7604_MODE_8BIT_800KHZ) {
        return is_rgbw ? 4u : 3u;
    }
    return is_rgbw ? 8u : 6u;
}

inline size_t ucs7604FrameBytes(size_t num_leds, UCS7604Mode mode,
                                bool is_rgbw) FL_NO_EXCEPT {
    constexpr size_t kPreambleLen = 15;
    const size_t total = kPreambleLen + num_leds * ucs7604BytesPerLed(mode, is_rgbw);
    // The protocol requires the total to be divisible by 3.
    return total + (3u - (total % 3u)) % 3u;
}

template <typename OutputIterator>
void encodeUCS7604(PixelIterator& pixel_iter, size_t num_leds, OutputIterator out,
                   UCS7604Mode mode, const UCS7604CurrentControl& current, bool is_rgbw,
                   const Gamma8* gamma = nullptr,
                   bool wide_source = false) FL_NO_EXCEPT {
    constexpr size_t PREAMBLE_LEN = 15;
 
#if FL_PLATFORM_HAS_TINY_MEMORY
    // No wide encoder exists on TINY, so the flag selects nothing there.
    FL_UNUSED(wide_source);
#endif
 
    // Padding comes from ucs7604FrameBytes() so the length callers predict and
    // the length written here are the same number by construction.
    const size_t led_data_size = num_leds * ucs7604BytesPerLed(mode, is_rgbw);
    const size_t padding =
        ucs7604FrameBytes(num_leds, mode, is_rgbw) - PREAMBLE_LEN - led_data_size;
 
    // Build preamble (15 bytes) with current control
    buildUCS7604Preamble(out, mode, current.r, current.g, current.b, current.w);
 
    // Add padding (0-2 zero bytes)
    for (size_t i = 0; i < padding; ++i) {
        *out++ = 0;
    }
 
    // Encode LED data based on mode and RGB/RGBW
    if (mode == UCS7604Mode::UCS7604_MODE_8BIT_800KHZ) {
        if (is_rgbw) {
            auto range = makeScaledPixelRangeRGBW(&pixel_iter);
            encodeUCS7604_8bit_RGBW(range.first, range.second, out);
        } else {
            auto range = makeScaledPixelRangeRGB(&pixel_iter);
            encodeUCS7604_8bit_RGB(range.first, range.second, out);
        }
    } else {
        // 16-bit modes -- fall back to gamma 2.8 if no gamma provided
        static fl::shared_ptr<const Gamma8> default_gamma;
        const Gamma8& g = gamma ? *gamma : *(default_gamma ? default_gamma : (default_gamma = Gamma8::getOrCreate(2.8f)));
        if (is_rgbw) {
            // RGBW stays on the gamma path: `ColorManagedPixelSource`
            // delegates its RGBW entry point to the legacy controller, so
            // there is no wide drive to consume here yet.
            auto range = makeScaledPixelRangeRGBW(&pixel_iter);
            encodeUCS7604_16bit_RGBW(range.first, range.second, out, g);
#if !FL_PLATFORM_HAS_TINY_MEMORY
        } else if (wide_source) {
            encodeUCS7604_16bit_RGB_wide(pixel_iter, out);
#endif
        } else {
            auto range = makeScaledPixelRangeRGB(&pixel_iter);
            encodeUCS7604_16bit_RGB(range.first, range.second, out, g);
        }
    }
}
 
} // namespace fl