rgbww.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/stdint.h"
#include "fl/stl/compiler_control.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
 
// Forward decl — full definition in fl/gfx/rgbw_colorimetric.h. Avoiding the
// transitive include keeps Rgbww's compile cost minimal in callers that don't
// need the colorimetric solver.
namespace colorimetric_detail {
struct RgbcctProfile;
}

enum class EOrderWW : fl::u8 {
    WwWcEnd   = 0x34,   
    WcWwEnd   = 0x43,   
    WwWcStart = 0x01,   
    WcWwStart = 0x10,   
    WWDefault = WwWcEnd,
};

enum class RGBWW_MODE : fl::u8 {
    kRGBWWInvalid,
    kRGBWWColorimetric,
    kRGBWWColorimetricBoosted,
    // IMPORTANT: kRGBWWUserFunction MUST remain the last enumerator. New
    // modes are added immediately above this line so the user-function
    // ordinal stays as the dispatch max value.
    kRGBWWUserFunction,
};

enum {
    kRGBWWDefaultWarmCct = 2700,
    kRGBWWDefaultCoolCct = 6500,
};

struct Rgbww;
 
namespace detail {
struct RgbwwNoEncoder {};
void enable_rgbww_conversion() FL_NO_EXCEPT;
using RgbwwConvertFn = void (*)(const Rgbww& rgbww, const fl::u8 (&raw)[3],
                                const fl::u8 (&premix)[3], const fl::u8 (&order)[3],
                                fl::u8* b0, fl::u8* b1, fl::u8* b2,
                                fl::u8* b3, fl::u8* b4);
RgbwwConvertFn rgbww_conversion() FL_NO_EXCEPT;
}  // namespace detail
 
struct Rgbww {
    explicit Rgbww(fl::u16 warm = kRGBWWDefaultWarmCct,
                   fl::u16 cool = kRGBWWDefaultCoolCct,
                   RGBWW_MODE mode = RGBWW_MODE::kRGBWWColorimetric,
                   EOrderWW placement = EOrderWW::WWDefault) FL_NO_EXCEPT
        : warm_cct(warm), cool_cct(cool),
          rgbww_mode(mode), w_placement(placement),
          profile(nullptr) {
        detail::enable_rgbww_conversion();
    }

    explicit Rgbww(detail::RgbwwNoEncoder) FL_NO_EXCEPT
        : warm_cct(kRGBWWDefaultWarmCct), cool_cct(kRGBWWDefaultCoolCct),
          rgbww_mode(RGBWW_MODE::kRGBWWInvalid), w_placement(EOrderWW::WWDefault),
          profile(nullptr) {}
 
    fl::u16 warm_cct;
    fl::u16 cool_cct;
    RGBWW_MODE rgbww_mode;
    EOrderWW w_placement;
    const colorimetric_detail::RgbcctProfile* profile;
 
    FASTLED_FORCE_INLINE bool active() const FL_NO_EXCEPT {
        return rgbww_mode != RGBWW_MODE::kRGBWWInvalid;
    }
};

struct RgbwwInvalid : public Rgbww {
    RgbwwInvalid() FL_NO_EXCEPT : Rgbww(detail::RgbwwNoEncoder()) {
        rgbww_mode = RGBWW_MODE::kRGBWWInvalid;
    }
    static Rgbww value() FL_NO_EXCEPT { return RgbwwInvalid(); }
};

struct RgbwwDefault : public Rgbww {
    RgbwwDefault() FL_NO_EXCEPT : Rgbww() {}
    static Rgbww value() FL_NO_EXCEPT { return RgbwwDefault(); }
};
 
// ===== rgb_2_rgbww dispatch surface (#2558) =================================
//
// Mirror of the rgb_2_rgbw dispatch family. Real-path implementations run
// when FASTLED_RGBW_COLORIMETRIC=1 is set at library build time; without it,
// the library ships stubs that emit FL_WARN_ONCE and output zeros.
//
// Signature note: unlike rgb_2_rgbw_function (scalar fields), the RGBWW
// signature takes the Rgbww config struct by-ref to carry the two CCTs and
// the optional profile pointer in one parameter.
 
typedef void (*rgb_2_rgbww_function)(const Rgbww& cfg,
                                     fl::u8 r, fl::u8 g, fl::u8 b,
                                     fl::u8 r_scale, fl::u8 g_scale, fl::u8 b_scale,
                                     fl::u8 *out_r, fl::u8 *out_g, fl::u8 *out_b,
                                     fl::u8 *out_ww, fl::u8 *out_wc);

void rgb_2_rgbww_colorimetric(const Rgbww& cfg,
                              fl::u8 r, fl::u8 g, fl::u8 b,
                              fl::u8 r_scale, fl::u8 g_scale, fl::u8 b_scale,
                              fl::u8 *out_r, fl::u8 *out_g, fl::u8 *out_b,
                              fl::u8 *out_ww, fl::u8 *out_wc) FL_NO_EXCEPT;

void rgb_2_rgbww_colorimetric_boosted(const Rgbww& cfg,
                                      fl::u8 r, fl::u8 g, fl::u8 b,
                                      fl::u8 r_scale, fl::u8 g_scale, fl::u8 b_scale,
                                      fl::u8 *out_r, fl::u8 *out_g, fl::u8 *out_b,
                                      fl::u8 *out_ww, fl::u8 *out_wc) FL_NO_EXCEPT;

void rgb_2_rgbww_user_function(const Rgbww& cfg,
                               fl::u8 r, fl::u8 g, fl::u8 b,
                               fl::u8 r_scale, fl::u8 g_scale, fl::u8 b_scale,
                               fl::u8 *out_r, fl::u8 *out_g, fl::u8 *out_b,
                               fl::u8 *out_ww, fl::u8 *out_wc) FL_NO_EXCEPT;
 
void set_rgb_2_rgbww_function(rgb_2_rgbww_function func) FL_NO_EXCEPT;
 
// ===== Default RGBCCT profile + active-profile API (Phase D of #2558) =======
//
// Ships the default warm-W (2700K) + cool-W (6500K) profile used when an
// Rgbww config carries `profile = nullptr`. Users with a colorimeter or
// custom RGBWW chipset install their own via set_rgbww_colorimetric_profile().
// Pointer is borrowed — caller keeps the profile alive for the lifetime of
// any controller referencing it. Pass nullptr to revert to the default.
 
extern const colorimetric_detail::RgbcctProfile kRgbwwDefaultProfile;
 
void set_rgbww_colorimetric_profile(const colorimetric_detail::RgbcctProfile* profile) FL_NO_EXCEPT;
const colorimetric_detail::RgbcctProfile* get_rgbww_colorimetric_profile() FL_NO_EXCEPT;

void rgbww_partial_reorder(EOrderWW ww_placement,
                           fl::u8 b0, fl::u8 b1, fl::u8 b2,
                           fl::u8 ww, fl::u8 wc,
                           fl::u8 *out_b0, fl::u8 *out_b1, fl::u8 *out_b2,
                           fl::u8 *out_b3, fl::u8 *out_b4) FL_NO_EXCEPT;
 
FASTLED_FORCE_INLINE void
rgb_2_rgbww(const Rgbww& cfg,
            fl::u8 r, fl::u8 g, fl::u8 b,
            fl::u8 r_scale, fl::u8 g_scale, fl::u8 b_scale,
            fl::u8 *out_r, fl::u8 *out_g, fl::u8 *out_b,
            fl::u8 *out_ww, fl::u8 *out_wc) FL_NO_EXCEPT {
    switch (cfg.rgbww_mode) {
    case RGBWW_MODE::kRGBWWInvalid:
        // Inactive: emit zeros across all five channels.
        *out_r = *out_g = *out_b = *out_ww = *out_wc = 0;
        return;
    case RGBWW_MODE::kRGBWWColorimetric:
        rgb_2_rgbww_colorimetric(cfg, r, g, b, r_scale, g_scale, b_scale,
                                 out_r, out_g, out_b, out_ww, out_wc);
        return;
    case RGBWW_MODE::kRGBWWColorimetricBoosted:
        rgb_2_rgbww_colorimetric_boosted(cfg, r, g, b, r_scale, g_scale, b_scale,
                                         out_r, out_g, out_b, out_ww, out_wc);
        return;
    case RGBWW_MODE::kRGBWWUserFunction:
        rgb_2_rgbww_user_function(cfg, r, g, b, r_scale, g_scale, b_scale,
                                  out_r, out_g, out_b, out_ww, out_wc);
        return;
    }
    *out_r = *out_g = *out_b = *out_ww = *out_wc = 0;
}
 
} // namespace fl