light_call.h

Go to the documentation of this file.

#pragma once
 
#include "light_color_values.h"
#include "esphome/core/string_ref.h"
 
namespace esphome {
 
// Forward declaration
struct LogString;
 
namespace light {
 
class LightState;
class LightTraits;
 
class LightCall {
 public:
  explicit LightCall(LightState *parent) : parent_(parent) {}
 
  LightCall &set_state(optional<bool> state);
  LightCall &set_state(bool state);
  LightCall &set_transition_length(optional<uint32_t> transition_length);
  LightCall &set_transition_length(uint32_t transition_length);
  LightCall &set_transition_length_if_supported(uint32_t transition_length);
  LightCall &set_flash_length(optional<uint32_t> flash_length);
  LightCall &set_flash_length(uint32_t flash_length);
  LightCall &set_brightness(optional<float> brightness);
  LightCall &set_brightness(float brightness);
  LightCall &set_brightness_if_supported(float brightness);
 
  LightCall &set_color_mode(optional<ColorMode> color_mode);
  LightCall &set_color_mode(ColorMode color_mode);
  LightCall &set_color_mode_if_supported(ColorMode color_mode);
 
  LightCall &set_color_brightness(optional<float> brightness);
  LightCall &set_color_brightness(float brightness);
  LightCall &set_color_brightness_if_supported(float brightness);
  LightCall &set_red(optional<float> red);
  LightCall &set_red(float red);
  LightCall &set_red_if_supported(float red);
  LightCall &set_green(optional<float> green);
  LightCall &set_green(float green);
  LightCall &set_green_if_supported(float green);
  LightCall &set_blue(optional<float> blue);
  LightCall &set_blue(float blue);
  LightCall &set_blue_if_supported(float blue);
  LightCall &set_white(optional<float> white);
  LightCall &set_white(float white);
  LightCall &set_white_if_supported(float white);
  LightCall &set_color_temperature(optional<float> color_temperature);
  LightCall &set_color_temperature(float color_temperature);
  LightCall &set_color_temperature_if_supported(float color_temperature);
  LightCall &set_cold_white(optional<float> cold_white);
  LightCall &set_cold_white(float cold_white);
  LightCall &set_cold_white_if_supported(float cold_white);
  LightCall &set_warm_white(optional<float> warm_white);
  LightCall &set_warm_white(float warm_white);
  LightCall &set_warm_white_if_supported(float warm_white);
  LightCall &set_effect(optional<std::string> effect);
  LightCall &set_effect(const std::string &effect) { return this->set_effect(effect.data(), effect.size()); }
  LightCall &set_effect(const char *effect) { return this->set_effect(effect, strlen(effect)); }
  LightCall &set_effect(StringRef effect) { return this->set_effect(effect.c_str(), effect.size()); }
  LightCall &set_effect(const char *effect, size_t len);
  LightCall &set_effect(uint32_t effect_number);
  LightCall &set_effect(optional<uint32_t> effect_number);
  LightCall &set_publish(bool publish);
  LightCall &set_save(bool save);
 
  // Getter methods to check if values are set
  bool has_state() const { return (flags_ & FLAG_HAS_STATE) != 0; }
  bool has_brightness() const { return (flags_ & FLAG_HAS_BRIGHTNESS) != 0; }
  bool has_color_brightness() const { return (flags_ & FLAG_HAS_COLOR_BRIGHTNESS) != 0; }
  bool has_red() const { return (flags_ & FLAG_HAS_RED) != 0; }
  bool has_green() const { return (flags_ & FLAG_HAS_GREEN) != 0; }
  bool has_blue() const { return (flags_ & FLAG_HAS_BLUE) != 0; }
  bool has_white() const { return (flags_ & FLAG_HAS_WHITE) != 0; }
  bool has_color_temperature() const { return (flags_ & FLAG_HAS_COLOR_TEMPERATURE) != 0; }
  bool has_cold_white() const { return (flags_ & FLAG_HAS_COLD_WHITE) != 0; }
  bool has_warm_white() const { return (flags_ & FLAG_HAS_WARM_WHITE) != 0; }
  bool has_color_mode() const { return (flags_ & FLAG_HAS_COLOR_MODE) != 0; }
 
  LightCall &set_rgb(float red, float green, float blue);
  LightCall &set_rgbw(float red, float green, float blue, float white);
  LightCall &from_light_color_values(const LightColorValues &values);
 
  void perform();
 
 protected:
  ColorMode get_active_color_mode_();
 
  LightColorValues validate_();
 
  ColorMode compute_color_mode_(const LightTraits &traits);
  color_mode_bitmask_t get_suitable_color_modes_mask_();
  void transform_parameters_(const LightTraits &traits);
 
  // Bits 0-7 index unit_fields_[] in validate_(); don't reorder (asserts in light_call.cpp).
  enum FieldFlags : uint16_t {
    FLAG_HAS_BRIGHTNESS = 1 << 0,
    FLAG_HAS_COLOR_BRIGHTNESS = 1 << 1,
    FLAG_HAS_RED = 1 << 2,
    FLAG_HAS_GREEN = 1 << 3,
    FLAG_HAS_BLUE = 1 << 4,
    FLAG_HAS_WHITE = 1 << 5,
    FLAG_HAS_COLD_WHITE = 1 << 6,
    FLAG_HAS_WARM_WHITE = 1 << 7,
    FLAG_HAS_COLOR_TEMPERATURE = 1 << 8,
    FLAG_HAS_STATE = 1 << 9,
    FLAG_HAS_TRANSITION = 1 << 10,
    FLAG_HAS_FLASH = 1 << 11,
    FLAG_HAS_EFFECT = 1 << 12,
    FLAG_HAS_COLOR_MODE = 1 << 13,
    FLAG_PUBLISH = 1 << 14,
    FLAG_SAVE = 1 << 15,
  };
  static constexpr uint16_t CLAMP_FLAGS_MASK = 0x00FFu;  // bits 0-7
  // Flags a plain turn-on may carry; any other flag means the caller asked for something specific
  static constexpr uint16_t STATE_ONLY_FLAGS_MASK = FLAG_HAS_STATE | FLAG_PUBLISH | FLAG_SAVE;
  static constexpr uint16_t VALUE_FLAGS_MASK = CLAMP_FLAGS_MASK | FLAG_HAS_COLOR_TEMPERATURE | FLAG_HAS_COLOR_MODE;
 
  inline bool has_transition_() { return (this->flags_ & FLAG_HAS_TRANSITION) != 0; }
  inline bool has_flash_() { return (this->flags_ & FLAG_HAS_FLASH) != 0; }
  inline bool has_effect_() { return (this->flags_ & FLAG_HAS_EFFECT) != 0; }
  inline bool get_publish_() { return (this->flags_ & FLAG_PUBLISH) != 0; }
  inline bool get_save_() { return (this->flags_ & FLAG_SAVE) != 0; }
 
  // Helper to set flag - defaults to true for common case
  void set_flag_(FieldFlags flag, bool value = true) ESPHOME_ALWAYS_INLINE {
    if (value) {
      this->flags_ |= flag;
    } else {
      this->flags_ &= ~flag;
    }
  }
 
  // Helper to clear flag - reduces code size for common case
  void clear_flag_(FieldFlags flag) ESPHOME_ALWAYS_INLINE { this->flags_ &= ~flag; }
 
  // Helper to log unsupported feature and clear flag - reduces code duplication
  void log_and_clear_unsupported_(FieldFlags flag, const LogString *feature, bool use_color_mode_log);
 
  LightState *parent_;
 
  // Light state values - use flags_ to check if a value has been set.
  uint32_t transition_length_;
  uint32_t flash_length_;
  uint32_t effect_;
  ESPHOME_LIGHT_UNIT_FIELDS_UNION();
  float color_temperature_;
 
  // Smaller members at the end for better packing
  uint16_t flags_{FLAG_PUBLISH | FLAG_SAVE};  // Tracks which values are set
  ColorMode color_mode_;
  bool state_;
};
 
}  // namespace light
}  // namespace esphome