light_color_values.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/helpers.h"
#include "color_mode.h"
#include <cmath>
#include <cstdint>
#include <limits>
 
namespace esphome::light {
 
inline static uint8_t to_uint8_scale(float x) { return static_cast<uint8_t>(roundf(x * 255.0f)); }
 
// IEEE 754 bit patterns. Values in [0.0f, 1.0f] have bits <= ONE_F_BITS;
// negatives have the sign bit set (→ huge unsigned). A single unsigned compare
// replaces two soft-float __ltsf2/__gtsf2 calls on ESP8266.
static constexpr uint32_t ONE_F_BITS = 0x3F800000u;       // 1.0f
static constexpr uint32_t NEG_ZERO_F_BITS = 0x80000000u;  // -0.0f / sign-bit mask
static_assert(sizeof(float) == sizeof(uint32_t), "float must be 32-bit");
static_assert(std::numeric_limits<float>::is_iec559, "IEEE 754 float required");
 
// Union pun — memcpy/bit_cast don't fold on xtensa-gcc (see api/proto.h).
// -0.0f is numerically zero so it's reported in range (no warning, no clamp).
inline bool float_out_of_unit_range(float x) {
  union {
    float f;
    uint32_t u;
  } pun;
  pun.f = x;
  return pun.u > ONE_F_BITS && pun.u != NEG_ZERO_F_BITS;
}
 
// Clamps to [0.0f, 1.0f] without float compares. Out of range: sign bit set
// (negatives, -NaN, -Inf) → 0.0f; sign bit clear (>1, +NaN, +Inf) → 1.0f.
inline float clamp_unit_float(float x) {
  union {
    float f;
    uint32_t u;
  } pun;
  pun.f = x;
  if (pun.u <= ONE_F_BITS)
    return x;
  return (pun.u & NEG_ZERO_F_BITS) ? 0.0f : 1.0f;  // sign bit → negative → clamp to 0
}
 
// Shared anonymous union: eight unit-range floats alias unit_fields_[8] so
// LightCall::validate_() can iterate them as a real array. GCC/Clang ext.
#define ESPHOME_LIGHT_UNIT_FIELDS_UNION() \
  union { \
    struct { \
      float brightness_; \
      float color_brightness_; \
      float red_; \
      float green_; \
      float blue_; \
      float white_; \
      float cold_white_; \
      float warm_white_; \
    }; \
    float unit_fields_[8]; \
  }
 
class LightColorValues {
 public:
  LightColorValues()
      : state_(0.0f),
        brightness_(1.0f),
        color_brightness_(1.0f),
        red_(1.0f),
        green_(1.0f),
        blue_(1.0f),
        white_(1.0f),
        cold_white_{1.0f},
        warm_white_{1.0f},
        color_temperature_{0.0f},
        color_mode_(ColorMode::UNKNOWN) {}
 
  LightColorValues(ColorMode color_mode, float state, float brightness, float color_brightness, float red, float green,
                   float blue, float white, float color_temperature, float cold_white, float warm_white) {
    this->set_color_mode(color_mode);
    this->set_state(state);
    this->set_brightness(brightness);
    this->set_color_brightness(color_brightness);
    this->set_red(red);
    this->set_green(green);
    this->set_blue(blue);
    this->set_white(white);
    this->set_color_temperature(color_temperature);
    this->set_cold_white(cold_white);
    this->set_warm_white(warm_white);
  }
 
  static LightColorValues lerp(const LightColorValues &start, const LightColorValues &end, float completion);
 
  void normalize_color() {
    if (this->color_mode_ & ColorCapability::RGB) {
      float max_value = fmaxf(this->red_, fmaxf(this->green_, this->blue_));
      // Assign directly to avoid redundant clamp in set_red/green/blue.
      // Values are guaranteed in [0,1]: inputs are already clamped to [0,1],
      // and dividing by max_value (the largest) keeps results in [0,1].
      if (max_value == 0.0f) {
        this->red_ = 1.0f;
        this->green_ = 1.0f;
        this->blue_ = 1.0f;
      } else {
        float inv = 1.0f / max_value;
        this->red_ *= inv;
        this->green_ *= inv;
        this->blue_ *= inv;
      }
    }
  }
 
  void as_binary(bool *binary) const { *binary = this->state_ == 1.0f; }
 
  void as_brightness(float *brightness) const { *brightness = this->state_ * this->brightness_; }
 
  void as_rgb(float *red, float *green, float *blue) const {
    if (this->color_mode_ & ColorCapability::RGB) {
      float brightness = this->state_ * this->brightness_ * this->color_brightness_;
      *red = brightness * this->red_;
      *green = brightness * this->green_;
      *blue = brightness * this->blue_;
    } else {
      *red = *green = *blue = 0;
    }
  }
 
  void as_rgbw(float *red, float *green, float *blue, float *white) const {
    this->as_rgb(red, green, blue);
    if (this->color_mode_ & ColorCapability::WHITE) {
      *white = this->state_ * this->brightness_ * this->white_;
    } else {
      *white = 0;
    }
  }
 
  void as_rgbww(float *red, float *green, float *blue, float *cold_white, float *warm_white,
                bool constant_brightness = false) const {
    this->as_rgb(red, green, blue);
    this->as_cwww(cold_white, warm_white, constant_brightness);
  }
 
  void as_rgbct(float color_temperature_cw, float color_temperature_ww, float *red, float *green, float *blue,
                float *color_temperature, float *white_brightness) const {
    this->as_rgb(red, green, blue);
    this->as_ct(color_temperature_cw, color_temperature_ww, color_temperature, white_brightness);
  }
 
  void as_cwww(float *cold_white, float *warm_white, bool constant_brightness = false) const {
    if (this->color_mode_ & ColorCapability::COLD_WARM_WHITE) {
      const float cw_level = this->cold_white_;
      const float ww_level = this->warm_white_;
      const float white_level = this->state_ * this->brightness_;
      if (!constant_brightness) {
        *cold_white = white_level * cw_level;
        *warm_white = white_level * ww_level;
      } else {
        // Just multiplying by cw_level / (cw_level + ww_level) would divide out the brightness information from the
        // cold_white and warm_white settings (i.e. cw=0.8, ww=0.4 would be identical to cw=0.4, ww=0.2), which breaks
        // transitions. Use the highest value as the brightness for the white channels (the alternative, using cw+ww/2,
        // reduces to cw/2 and ww/2, which would still limit brightness to 100% of a single channel, but isn't very
        // useful in all other aspects -- that behaviour can also be achieved by limiting the output power).
        const float sum = cw_level > 0 || ww_level > 0 ? cw_level + ww_level : 1;  // Don't divide by zero.
        *cold_white = white_level * std::max(cw_level, ww_level) * cw_level / sum;
        *warm_white = white_level * std::max(cw_level, ww_level) * ww_level / sum;
      }
    } else {
      *cold_white = *warm_white = 0;
    }
  }
 
  void as_ct(float color_temperature_cw, float color_temperature_ww, float *color_temperature,
             float *white_brightness) const {
    const float white_level = this->color_mode_ & ColorCapability::RGB ? this->white_ : 1;
    if (this->color_mode_ & ColorCapability::COLOR_TEMPERATURE) {
      *color_temperature =
          (this->color_temperature_ - color_temperature_cw) / (color_temperature_ww - color_temperature_cw);
      *white_brightness = this->state_ * this->brightness_ * white_level;
    } else {  // Probably won't get here but put this here anyway.
      *white_brightness = 0;
    }
  }
 
  bool operator==(const LightColorValues &rhs) const {
    return color_mode_ == rhs.color_mode_ && state_ == rhs.state_ && brightness_ == rhs.brightness_ &&
           color_brightness_ == rhs.color_brightness_ && red_ == rhs.red_ && green_ == rhs.green_ &&
           blue_ == rhs.blue_ && white_ == rhs.white_ && color_temperature_ == rhs.color_temperature_ &&
           cold_white_ == rhs.cold_white_ && warm_white_ == rhs.warm_white_;
  }
  bool operator!=(const LightColorValues &rhs) const { return !(rhs == *this); }
 
  ColorMode get_color_mode() const { return this->color_mode_; }
  void set_color_mode(ColorMode color_mode) { this->color_mode_ = color_mode; }
 
  float get_state() const { return this->state_; }
  bool is_on() const { return this->get_state() != 0.0f; }
  void set_state(float state) { this->state_ = clamp_unit_float(state); }
  void set_state(bool state) { this->state_ = state ? 1.0f : 0.0f; }
 
  float get_brightness() const { return this->brightness_; }
  void set_brightness(float brightness) { this->brightness_ = clamp_unit_float(brightness); }
 
  float get_color_brightness() const { return this->color_brightness_; }
  void set_color_brightness(float brightness) { this->color_brightness_ = clamp_unit_float(brightness); }
 
  float get_red() const { return this->red_; }
  void set_red(float red) { this->red_ = clamp_unit_float(red); }
 
  float get_green() const { return this->green_; }
  void set_green(float green) { this->green_ = clamp_unit_float(green); }
 
  float get_blue() const { return this->blue_; }
  void set_blue(float blue) { this->blue_ = clamp_unit_float(blue); }
 
  float get_white() const { return white_; }
  void set_white(float white) { this->white_ = clamp_unit_float(white); }
 
  float get_color_temperature() const { return this->color_temperature_; }
  void set_color_temperature(float color_temperature) { this->color_temperature_ = color_temperature; }
 
  float get_color_temperature_kelvin() const {
    if (this->color_temperature_ <= 0) {
      return this->color_temperature_;
    }
    return 1000000.0 / this->color_temperature_;
  }
  void set_color_temperature_kelvin(float color_temperature) {
    if (color_temperature <= 0) {
      return;
    }
    this->color_temperature_ = 1000000.0 / color_temperature;
  }
 
  float get_cold_white() const { return this->cold_white_; }
  void set_cold_white(float cold_white) { this->cold_white_ = clamp_unit_float(cold_white); }
 
  float get_warm_white() const { return this->warm_white_; }
  void set_warm_white(float warm_white) { this->warm_white_ = clamp_unit_float(warm_white); }
 
  friend class LightCall;
 
 protected:
  float state_;  
  ESPHOME_LIGHT_UNIT_FIELDS_UNION();
  float color_temperature_;  
  ColorMode color_mode_;
};
 
}  // namespace esphome::light