ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esp_color_view.h
Go to the documentation of this file.
1#pragma once
2
3#include <cstring>
4#include <utility>
5
8#include "esp_hsv_color.h"
10#include "channel_colors.h"
11
12namespace esphome::light {
13
23 public:
24 virtual Color get(int32_t index) const = 0;
25 virtual Color get_raw(int32_t index) const = 0;
26 virtual uint8_t get_channel(int32_t index, uint8_t channel) const = 0;
27 virtual uint8_t get_channel_raw(int32_t index, uint8_t channel) const = 0;
28 virtual uint8_t get_effect_data(int32_t index) const = 0;
29
30 virtual void set(int32_t index, Color color) = 0;
31 virtual void set_raw(int32_t index, Color raw_color) = 0;
32 virtual void set_channel(int32_t index, uint8_t channel, uint8_t value) = 0;
33 virtual void set_channel_raw(int32_t index, uint8_t channel, uint8_t raw_value) = 0;
34 virtual void set_effect_data(int32_t index, uint8_t value) = 0;
35
36#if defined(USE_LIGHT_PARTITION) && defined(USE_LIGHT_POWER_ESTIMATION)
37 virtual const ESPColorCorrection *get_color_correction_internal(int32_t index) const { return nullptr; }
38#endif
39};
40
42class NullColorAccessor final : public ESPColorAccessor {
43 public:
46
47 Color get(int32_t index) const override { return {}; }
48 Color get_raw(int32_t index) const override { return {}; }
49 uint8_t get_channel(int32_t index, uint8_t channel) const override { return 0; }
50 uint8_t get_channel_raw(int32_t index, uint8_t channel) const override { return 0; }
51 uint8_t get_effect_data(int32_t index) const override { return 0; }
52
53 void set(int32_t index, Color color) override {}
54 void set_raw(int32_t index, Color raw_color) override {}
55 void set_channel(int32_t index, uint8_t channel, uint8_t value) override {}
56 void set_channel_raw(int32_t index, uint8_t channel, uint8_t raw_value) override {}
57 void set_effect_data(int32_t index, uint8_t value) override {}
58};
59
62 public:
66
67 Color get_raw(int32_t index) const override { return this->channel_colors.get(this->color_data, index); }
68 uint8_t get_channel_raw(int32_t index, uint8_t channel) const override {
69 return this->channel_colors.get_channel(this->color_data, index, channel);
70 }
71 uint8_t get_effect_data(int32_t index) const override { return this->effect_data[index]; }
72
73 void set_raw(int32_t index, Color raw_color) override {
74 this->channel_colors.set(this->color_data, index, raw_color);
75 }
76 void set_channel_raw(int32_t index, uint8_t channel, uint8_t raw_value) override {
77 this->channel_colors.set_channel(this->color_data, index, channel, raw_value);
78 }
79 void set_effect_data(int32_t index, uint8_t value) override { this->effect_data[index] = value; }
80
83 bool allocate(RAMAllocator<uint8_t> &allocator, size_t num_leds, size_t extra_bytes = 0) {
84 const size_t color_bytes = num_leds * this->channel_colors.bytes_per_led();
85 const size_t total_bytes = color_bytes + num_leds + extra_bytes;
86 uint8_t *buf = allocator.allocate(total_bytes);
87 if (buf == nullptr)
88 return false;
89 memset(buf, 0, total_bytes);
90 this->color_data = buf;
91 this->effect_data = buf + color_bytes;
92 return true;
93 }
94
96 void clear_effect_data(size_t num_leds) {
97 if (this->effect_data != nullptr)
98 memset(this->effect_data, 0, num_leds);
99 }
100
101 // These fields must all be initialized to valid (non-null) values prior to using the accessor.
102 uint8_t *color_data{nullptr};
103 uint8_t *effect_data{nullptr};
105};
106
109 public:
113
114 Color get(int32_t index) const override { return this->get_raw(index); }
115 uint8_t get_channel(int32_t index, uint8_t channel) const override { return this->get_channel_raw(index, channel); }
116
117 void set(int32_t index, Color color) override { this->set_raw(index, color); }
118 void set_channel(int32_t index, uint8_t channel, uint8_t raw_value) override {
119 this->set_channel_raw(index, channel, raw_value);
120 }
121};
122
125 public:
130
131 Color get(int32_t index) const override {
132 const Color raw_color = this->channel_colors.get(this->color_data, index);
133 const ESPColorCorrection *correction = this->color_correction;
134 // Skip white when the strip has none; uncorrecting its zero is wasted work on every read
135 return Color(correction->color_uncorrect_red(raw_color.red), correction->color_uncorrect_green(raw_color.green),
136 correction->color_uncorrect_blue(raw_color.blue),
137 this->channel_colors.has_white() ? correction->color_uncorrect_white(raw_color.white) : 0);
138 }
139 uint8_t get_channel(int32_t index, uint8_t channel) const override {
140 return this->color_correction->color_uncorrect_channel(channel, this->get_channel_raw(index, channel));
141 }
142
143 void set(int32_t index, Color color) override { this->set_raw(index, this->color_correction->color_correct(color)); }
144 void set_channel(int32_t index, uint8_t channel, uint8_t value) override {
145 this->set_channel_raw(index, channel, this->color_correction->color_correct_channel(channel, value));
146 }
147
148#if defined(USE_LIGHT_PARTITION) && defined(USE_LIGHT_POWER_ESTIMATION)
149 const ESPColorCorrection *get_color_correction_internal(int32_t index) const override {
150 return this->color_correction;
151 }
152#endif
153
154 // Must be initialized to a valid non-null value prior to using the accessor.
156};
157
161 public:
162 virtual void set(Color color) = 0;
163 virtual void set_channel(uint8_t channel, uint8_t value) = 0;
164 virtual void set_effect_data(uint8_t value) = 0;
165
166 virtual void fade_to_white(uint8_t amnt) = 0;
167 virtual void fade_to_black(uint8_t amnt) = 0;
168 virtual void lighten(uint8_t delta) = 0;
169 virtual void darken(uint8_t delta) = 0;
170
171 inline void set_red(uint8_t red) ESPHOME_ALWAYS_INLINE { this->set_channel(COLOR_CHANNEL_R, red); }
172 inline void set_green(uint8_t green) ESPHOME_ALWAYS_INLINE { this->set_channel(COLOR_CHANNEL_G, green); }
173 inline void set_blue(uint8_t blue) ESPHOME_ALWAYS_INLINE { this->set_channel(COLOR_CHANNEL_B, blue); }
174 inline void set_white(uint8_t white) ESPHOME_ALWAYS_INLINE { this->set_channel(COLOR_CHANNEL_W, white); }
175
176 void set_rgb(uint8_t red, uint8_t green, uint8_t blue) {
177 // This method should perhaps be deprecated because it's slower than `set(Color)`
178 // in the common case where the intent is to set all color channels of the pixel at once
179 // and there just happens to not be any white.
180 this->set_red(red);
181 this->set_green(green);
182 this->set_blue(blue);
183 }
184 void set_rgbw(uint8_t red, uint8_t green, uint8_t blue, uint8_t white) { this->set(Color(red, green, blue, white)); }
185
186 ESPDEPRECATED("Use set_hsv(hsv_color) instead. Removed in 2027.5.0.", "2026.11.0")
187 void set(ESPHSVColor hsv_color) { this->set(hsv_color.to_rgb()); }
188 void set_hsv(ESPHSVColor hsv_color) { this->set(hsv_color.to_rgb()); }
189};
190
195class ESPColorView final : public ESPColorSettable {
196 public:
197 ESPColorView(ESPColorAccessor *accessor, int32_t index) : accessor_(accessor), index_(index) {}
198 ESPColorView(const ESPColorView &) = default;
199
200 inline ESPColorView &operator=(Color color) {
201 this->set(color);
202 return *this;
203 }
204 inline ESPColorView &operator=(ESPHSVColor hsv_color) {
205 this->set_hsv(hsv_color);
206 return *this;
207 }
208 ESPColorView &operator=(const ESPColorView &other) { // NOLINT
209 const Color color = other.get();
210 this->set(color);
211 return *this;
212 }
213
214 void set(Color color) override { this->accessor_->set(this->index_, color); }
215 void set_channel(uint8_t channel, uint8_t value) override {
216 this->accessor_->set_channel(this->index_, channel, value);
217 }
218
219 void set_raw(Color raw_color) { this->accessor_->set_raw(this->index_, raw_color); }
220 void set_channel_raw(uint8_t channel, uint8_t raw_value) {
221 this->accessor_->set_channel_raw(this->index_, channel, raw_value);
222 }
223
224 inline void set_red_raw(uint8_t raw_red) ESPHOME_ALWAYS_INLINE { this->set_channel_raw(COLOR_CHANNEL_R, raw_red); }
225 inline void set_green_raw(uint8_t raw_green) ESPHOME_ALWAYS_INLINE {
226 this->set_channel_raw(COLOR_CHANNEL_G, raw_green);
227 }
228 inline void set_blue_raw(uint8_t raw_blue) ESPHOME_ALWAYS_INLINE { this->set_channel_raw(COLOR_CHANNEL_B, raw_blue); }
229 inline void set_white_raw(uint8_t raw_white) ESPHOME_ALWAYS_INLINE {
230 this->set_channel_raw(COLOR_CHANNEL_W, raw_white);
231 }
232
233 void set_effect_data(uint8_t value) override { this->accessor_->set_effect_data(this->index_, value); }
234
235 void fade_to_white(uint8_t amnt) override { this->set(this->get().fade_to_white(amnt)); }
236 void fade_to_black(uint8_t amnt) override { this->set(this->get().fade_to_black(amnt)); }
237 void lighten(uint8_t delta) override { this->set(this->get().lighten(delta)); }
238 void darken(uint8_t delta) override { this->set(this->get().darken(delta)); }
239
240 Color get() const { return this->accessor_->get(this->index_); }
241 uint8_t get_channel(uint8_t channel) const { return this->accessor_->get_channel(this->index_, channel); }
242
243 inline uint8_t get_red() const ESPHOME_ALWAYS_INLINE { return this->get_channel(COLOR_CHANNEL_R); }
244 inline uint8_t get_green() const ESPHOME_ALWAYS_INLINE { return this->get_channel(COLOR_CHANNEL_G); }
245 inline uint8_t get_blue() const ESPHOME_ALWAYS_INLINE { return this->get_channel(COLOR_CHANNEL_B); }
246 inline uint8_t get_white() const ESPHOME_ALWAYS_INLINE { return this->get_channel(COLOR_CHANNEL_W); }
247
248 Color get_raw() const { return this->accessor_->get_raw(this->index_); }
249 uint8_t get_channel_raw(uint8_t channel) const { return this->accessor_->get_channel_raw(this->index_, channel); }
250
251 inline uint8_t get_red_raw() const ESPHOME_ALWAYS_INLINE { return this->get_channel_raw(COLOR_CHANNEL_R); }
252 inline uint8_t get_green_raw() const ESPHOME_ALWAYS_INLINE { return this->get_channel_raw(COLOR_CHANNEL_G); }
253 inline uint8_t get_blue_raw() const ESPHOME_ALWAYS_INLINE { return this->get_channel_raw(COLOR_CHANNEL_B); }
254 inline uint8_t get_white_raw() const ESPHOME_ALWAYS_INLINE { return this->get_channel_raw(COLOR_CHANNEL_W); }
255
256 uint8_t get_effect_data() const { return this->accessor_->get_effect_data(this->index_); }
257
258#if defined(USE_LIGHT_PARTITION) && defined(USE_LIGHT_POWER_ESTIMATION)
259 // This method is for internal use only.
260 // Get the color correction applied by the underlying accessor or nullptr if there is none.
264#endif
265
266 protected:
268 const int32_t index_;
269};
270
271} // namespace esphome::light
An STL allocator that uses SPI or internal RAM.
Definition helpers.h:2396
T * allocate(size_t n)
Definition helpers.h:2423
Base class for color accessors backed by a buffer whose layout is described by ChannelColors.
uint8_t get_effect_data(int32_t index) const override
void set_raw(int32_t index, Color raw_color) override
void clear_effect_data(size_t num_leds)
Zero the effect data of the first num_leds LEDs; does nothing before the effect data is allocated.
void set_channel_raw(int32_t index, uint8_t channel, uint8_t raw_value) override
Color get_raw(int32_t index) const override
uint8_t get_channel_raw(int32_t index, uint8_t channel) const override
void set_effect_data(int32_t index, uint8_t value) override
bool allocate(RAMAllocator< uint8_t > &allocator, size_t num_leds, size_t extra_bytes=0)
Allocate the color and effect data for num_leds LEDs as one zeroed block, followed by extra_bytes mor...
BufferColorAccessor(uint8_t *color_data, uint8_t *effect_data, ChannelColors channel_colors)
Color accessor backed by a buffer whose contents have color correction applied.
void set_channel(int32_t index, uint8_t channel, uint8_t value) override
Color get(int32_t index) const override
const ESPColorCorrection * get_color_correction_internal(int32_t index) const override
uint8_t get_channel(int32_t index, uint8_t channel) const override
void set(int32_t index, Color color) override
CorrectedBufferColorAccessor(uint8_t *color_data, uint8_t *effect_data, ChannelColors channel_colors, const ESPColorCorrection *color_correction)
Abstract interface for accessing color and effect data for an addressable light by index.
virtual Color get_raw(int32_t index) const =0
virtual void set_raw(int32_t index, Color raw_color)=0
virtual uint8_t get_effect_data(int32_t index) const =0
virtual uint8_t get_channel_raw(int32_t index, uint8_t channel) const =0
virtual void set(int32_t index, Color color)=0
virtual const ESPColorCorrection * get_color_correction_internal(int32_t index) const
virtual void set_channel(int32_t index, uint8_t channel, uint8_t value)=0
virtual void set_effect_data(int32_t index, uint8_t value)=0
virtual uint8_t get_channel(int32_t index, uint8_t channel) const =0
virtual Color get(int32_t index) const =0
virtual void set_channel_raw(int32_t index, uint8_t channel, uint8_t raw_value)=0
uint8_t color_correct_channel(uint8_t channel, uint8_t value) const ESPHOME_ALWAYS_INLINE
uint8_t color_uncorrect_blue(uint8_t raw_blue) const ESPHOME_ALWAYS_INLINE
Color color_correct(Color color) const ESPHOME_ALWAYS_INLINE
uint8_t color_uncorrect_white(uint8_t raw_white) const ESPHOME_ALWAYS_INLINE
uint8_t color_uncorrect_channel(uint8_t channel, uint8_t raw_value) const
uint8_t color_uncorrect_red(uint8_t raw_red) const ESPHOME_ALWAYS_INLINE
uint8_t color_uncorrect_green(uint8_t raw_green) const ESPHOME_ALWAYS_INLINE
Abstract interface that supports setting colors and effect data.
void set_red(uint8_t red) ESPHOME_ALWAYS_INLINE
virtual void set_channel(uint8_t channel, uint8_t value)=0
void set_hsv(ESPHSVColor hsv_color)
void set_rgb(uint8_t red, uint8_t green, uint8_t blue)
void set_rgbw(uint8_t red, uint8_t green, uint8_t blue, uint8_t white)
virtual void darken(uint8_t delta)=0
virtual void lighten(uint8_t delta)=0
virtual void fade_to_white(uint8_t amnt)=0
virtual void set(Color color)=0
void set_green(uint8_t green) ESPHOME_ALWAYS_INLINE
void set_blue(uint8_t blue) ESPHOME_ALWAYS_INLINE
virtual void set_effect_data(uint8_t value)=0
ESPDEPRECATED("Use set_hsv(hsv_color) instead. Removed in 2027.5.0.", "2026.11.0") void set(ESPHSVColor hsv_color)
void set_white(uint8_t white) ESPHOME_ALWAYS_INLINE
virtual void fade_to_black(uint8_t amnt)=0
Gets or sets the color or effect data at a specific index within an color accessor.
void set_effect_data(uint8_t value) override
void set_channel(uint8_t channel, uint8_t value) override
uint8_t get_channel(uint8_t channel) const
uint8_t get_red() const ESPHOME_ALWAYS_INLINE
void set_red_raw(uint8_t raw_red) ESPHOME_ALWAYS_INLINE
uint8_t get_blue() const ESPHOME_ALWAYS_INLINE
void fade_to_black(uint8_t amnt) override
ESPColorAccessor *const accessor_
void fade_to_white(uint8_t amnt) override
const ESPColorCorrection * get_color_correction_internal() const
void darken(uint8_t delta) override
uint8_t get_blue_raw() const ESPHOME_ALWAYS_INLINE
void set_white_raw(uint8_t raw_white) ESPHOME_ALWAYS_INLINE
void set_channel_raw(uint8_t channel, uint8_t raw_value)
uint8_t get_white() const ESPHOME_ALWAYS_INLINE
ESPColorView(ESPColorAccessor *accessor, int32_t index)
void set(Color color) override
ESPColorView & operator=(ESPHSVColor hsv_color)
uint8_t get_white_raw() const ESPHOME_ALWAYS_INLINE
void set_blue_raw(uint8_t raw_blue) ESPHOME_ALWAYS_INLINE
uint8_t get_red_raw() const ESPHOME_ALWAYS_INLINE
ESPColorView & operator=(const ESPColorView &other)
uint8_t get_green() const ESPHOME_ALWAYS_INLINE
uint8_t get_channel_raw(uint8_t channel) const
ESPColorView(const ESPColorView &)=default
uint8_t get_green_raw() const ESPHOME_ALWAYS_INLINE
void lighten(uint8_t delta) override
ESPColorView & operator=(Color color)
void set_raw(Color raw_color)
void set_green_raw(uint8_t raw_green) ESPHOME_ALWAYS_INLINE
Color accessor that is completely at peace with the void of nothingness.
void set_raw(int32_t index, Color raw_color) override
Color get_raw(int32_t index) const override
uint8_t get_channel_raw(int32_t index, uint8_t channel) const override
uint8_t get_channel(int32_t index, uint8_t channel) const override
void set_channel(int32_t index, uint8_t channel, uint8_t value) override
Color get(int32_t index) const override
void set(int32_t index, Color color) override
uint8_t get_effect_data(int32_t index) const override
static NullColorAccessor instance
Singleton instance of this accessor.
void set_channel_raw(int32_t index, uint8_t channel, uint8_t raw_value) override
void set_effect_data(int32_t index, uint8_t value) override
Color accessor backed by a buffer whose contents have no color correction applied.
Color get(int32_t index) const override
void set_channel(int32_t index, uint8_t channel, uint8_t raw_value) override
RawBufferColorAccessor(uint8_t *color_data, uint8_t *effect_data, ChannelColors channel_colors)
void set(int32_t index, Color color) override
uint8_t get_channel(int32_t index, uint8_t channel) const override
uint32_t value
Definition hal.cpp:41
uint8_t red
Definition color.h:37
uint8_t white
Definition color.h:49
uint8_t green
Definition color.h:41
uint8_t blue
Definition color.h:45
Which byte of an addressable LED's data carries each colour.
void set_channel(uint8_t *color_data, int32_t index, uint8_t channel, uint8_t value) const
Color get(const uint8_t *color_data, int32_t index) const ESPHOME_ALWAYS_INLINE
void set(uint8_t *color_data, int32_t index, Color color) const
uint8_t get_channel(const uint8_t *color_data, int32_t index, uint8_t channel) const