ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
image.cpp
Go to the documentation of this file.
1#include "image.h"
2
3#include <algorithm>
4#include <cstring>
5
6#include "esphome/core/hal.h"
8
9ESPHOME_LOG_TAG(TAG, "image");
10
11namespace esphome::image {
12
13// Walks the clipped range with rows (ROWS_OUTER) or columns outer and hands the
14// body its coordinates and row major index. The body must be ESPHOME_ALWAYS_INLINE,
15// at -Os GCC otherwise calls it once per pixel.
16template<bool ROWS_OUTER, typename F>
17static void for_each_pixel(int x_start, int x_end, int y_start, int y_end, int width, F &&f) {
18 const int outer_start = ROWS_OUTER ? y_start : x_start;
19 const int outer_end = ROWS_OUTER ? y_end : x_end;
20 const int inner_start = ROWS_OUTER ? x_start : y_start;
21 const int inner_end = ROWS_OUTER ? x_end : y_end;
22 for (int outer = outer_start; outer < outer_end; outer++) {
23 const int outer_pos = ROWS_OUTER ? outer * width : outer;
24 for (int inner = inner_start; inner < inner_end; inner++) {
25 f(ROWS_OUTER ? inner : outer, ROWS_OUTER ? outer : inner,
26 ROWS_OUTER ? outer_pos + inner : outer_pos + inner * width);
27 }
28 }
29}
30
31void Image::draw(int x, int y, display::Display *display, Color color_on, Color color_off) {
32 int x_start = 0;
33 int y_start = 0;
34 int x_end = width_;
35 int y_end = height_;
36
37 auto clipping = display->get_clipping();
38 if (clipping.is_set()) {
39 if (clipping.x > x)
40 x_start += clipping.x - x;
41 if (clipping.y > y)
42 y_start += clipping.y - y;
43 if (x_end > clipping.x2() - x)
44 x_end = clipping.x2() - x;
45 if (y_end > clipping.y2() - y)
46 y_end = clipping.y2() - y;
47 }
48
49#ifndef USE_ESP8266
50 // Opaque RGB565 and RGB are already laid out for draw_pixels_at(), so the display
51 // gets the whole window. Not on the ESP8266, whose image bytes need progmem_read_byte().
53 (this->type_ == IMAGE_TYPE_RGB565 || this->type_ == IMAGE_TYPE_RGB)) {
54 // Keep the block on screen
55 x_start = std::max(x_start, -x);
56 y_start = std::max(y_start, -y);
57 x_end = std::min(x_end, display->get_width() - x);
58 y_end = std::min(y_end, display->get_height() - y);
59 if (x_end <= x_start || y_end <= y_start)
60 return;
61 const bool rgb565 = this->type_ == IMAGE_TYPE_RGB565;
62 display->draw_pixels_at(x + x_start, y + y_start, x_end - x_start, y_end - y_start, this->data_start_,
64 x_start, y_start, this->width_ - x_end);
65 return;
66 }
67#endif
68
69 // Rows keep the read and the write sequential; when the display swaps the axes
70 // columns keep the write sequential instead, and a strided write costs more.
71#ifdef USE_PSRAM
72 if (display->pixel_axes_swapped()) {
73 this->draw_<false>(x, y, display, color_on, color_off, x_start, x_end, y_start, y_end);
74 return;
75 }
76#endif
77 // Without PSRAM a strided write is free, so one copy of the loops is enough
78 this->draw_<true>(x, y, display, color_on, color_off, x_start, x_end, y_start, y_end);
79}
80
81template<bool ROWS_OUTER>
82void Image::draw_(int x, int y, display::Display *display, Color color_on, Color color_off, int x_start, int x_end,
83 int y_start, int y_end) {
84 // Local copies, or the virtual draw_pixel_at() forces a reload every pixel
85 const Transparency transparency = this->transparency_;
86 const int width = this->width_;
87 switch (this->type_) {
89 for_each_pixel<ROWS_OUTER>(x_start, x_end, y_start, y_end, width,
90 [&](int img_x, int img_y, int pos) ESPHOME_ALWAYS_INLINE {
91 if (this->get_binary_pixel_(img_x, img_y)) {
92 display->draw_pixel_at(x + img_x, y + img_y, color_on);
93 } else if (transparency == TRANSPARENCY_OPAQUE) {
94 display->draw_pixel_at(x + img_x, y + img_y, color_off);
95 }
96 });
97 break;
99 for_each_pixel<ROWS_OUTER>(x_start, x_end, y_start, y_end, width,
100 [&](int img_x, int img_y, int pos) ESPHOME_ALWAYS_INLINE {
101 auto color = this->get_rgb111_pixel_(img_x, img_y);
102 if (color.w >= 0x80) {
103 display->draw_pixel_at(x + img_x, y + img_y, color);
104 }
105 });
106 break;
108 const uint8_t *const data = this->data_start_;
109 for_each_pixel<ROWS_OUTER>(x_start, x_end, y_start, y_end, width,
110 [&](int img_x, int img_y, int pos) ESPHOME_ALWAYS_INLINE {
111 const uint8_t gray = progmem_read_byte(data + pos);
112 Color color = Color(gray, gray, gray, 0xFF);
113 if (transparency == TRANSPARENCY_CHROMA_KEY) {
114 if (gray == 1) {
115 return; // transparent pixel, skip drawing
116 }
117 } else if (transparency == TRANSPARENCY_ALPHA_CHANNEL) {
118 // gray is the alpha: blend from color_off to color_on, drawn opaque
119 color = Color(Color::blend_channel(color_off.r, color_on.r, gray),
120 Color::blend_channel(color_off.g, color_on.g, gray),
121 Color::blend_channel(color_off.b, color_on.b, gray), 0xFF);
122 }
123 display->draw_pixel_at(x + img_x, y + img_y, color);
124 });
125 break;
126 }
128 for_each_pixel<ROWS_OUTER>(x_start, x_end, y_start, y_end, width,
129 [&](int img_x, int img_y, int pos) ESPHOME_ALWAYS_INLINE {
130 auto color = this->get_rgb565_pixel_(img_x, img_y);
131 if (color.w >= 0x80) {
132 display->draw_pixel_at(x + img_x, y + img_y, color);
133 }
134 });
135 break;
136 case IMAGE_TYPE_RGB:
137 for_each_pixel<ROWS_OUTER>(x_start, x_end, y_start, y_end, width,
138 [&](int img_x, int img_y, int pos) ESPHOME_ALWAYS_INLINE {
139 auto color = this->get_rgb_pixel_(img_x, img_y);
140 if (color.w >= 0x80) {
141 display->draw_pixel_at(x + img_x, y + img_y, color);
142 }
143 });
144 break;
145 }
146}
147Color Image::get_pixel(int x, int y, const Color color_on, const Color color_off) const {
148 if (x < 0 || x >= this->width_ || y < 0 || y >= this->height_)
149 return color_off;
150 switch (this->type_) {
152 if (this->get_binary_pixel_(x, y))
153 return color_on;
154 return color_off;
156 return this->get_rgb111_pixel_(x, y);
158 return this->get_grayscale_pixel_(x, y);
160 return this->get_rgb565_pixel_(x, y);
161 case IMAGE_TYPE_RGB:
162 return this->get_rgb_pixel_(x, y);
163 default:
164 return color_off;
165 }
166}
167#ifdef USE_LVGL
168lv_image_dsc_t *Image::get_lv_image_dsc() {
169 // No pixels yet. A widget keeps this descriptor and reads it on every draw, and LVGL warns on every draw of an image
170 // without data, so give it a transparent pixel instead
171 static constexpr uint8_t TRANSPARENT_PIXEL = 0;
172 if (this->data_start_ == nullptr) {
173 if (this->dsc_.data != &TRANSPARENT_PIXEL) {
174 memset(&this->dsc_, 0, sizeof(this->dsc_));
175 this->dsc_.header.cf = LV_COLOR_FORMAT_A8;
176 this->dsc_.header.w = 1;
177 this->dsc_.header.h = 1;
178 this->dsc_.header.stride = 1;
179 this->dsc_.data_size = 1;
180 this->dsc_.data = &TRANSPARENT_PIXEL;
181 }
182 return &this->dsc_;
183 }
184 // lazily construct lvgl image_dsc.
185 if (this->dsc_.data != this->data_start_) {
186 this->dsc_.data = this->data_start_;
187 this->dsc_.header.reserved_2 = 0;
188 this->dsc_.header.stride = this->get_width_stride();
189 this->dsc_.header.w = this->width_;
190 this->dsc_.header.h = this->height_;
191 this->dsc_.data_size = this->get_width_stride() * this->get_height();
192 switch (this->get_type()) {
194 this->dsc_.header.cf = LV_COLOR_FORMAT_A1;
195 break;
196
198 this->dsc_.header.cf = LV_COLOR_FORMAT_A8;
199 break;
200
202 // Rejected by the lvgl config validation
203 ESP_LOGE(TAG, "RGB111 images are not supported in LVGL.");
204 break;
205 case IMAGE_TYPE_RGB:
206 switch (this->transparency_) {
208 this->dsc_.header.cf = LV_COLOR_FORMAT_ARGB8888;
209 break;
211 default:
212 this->dsc_.header.cf = LV_COLOR_FORMAT_RGB888;
213 break;
214 }
215 break;
216
218 switch (this->transparency_) {
220 this->dsc_.header.cf = LV_COLOR_FORMAT_RGB565A8;
221 break;
222 default:
223 this->dsc_.header.cf = LV_COLOR_FORMAT_RGB565;
224 }
225 break;
226 }
227 }
228 return &this->dsc_;
229}
230#endif // USE_LVGL
231
232bool Image::get_binary_pixel_(int x, int y) const {
233 const uint32_t width_8 = ((this->width_ + 7u) / 8u) * 8u;
234 const uint32_t pos = x + y * width_8;
235 return progmem_read_byte(this->data_start_ + (pos / 8u)) & (0x80 >> (pos % 8u));
236}
238 const uint32_t bitpos = y * this->get_width_stride() * 8 + x * this->bpp_;
239 const uint8_t *byte = this->data_start_ + bitpos / 8;
240 const uint8_t shift = bitpos % 8;
241 // A pixel can straddle two bytes; read the second one only when it does.
242 uint16_t window = progmem_read_byte(byte) << 8;
243 if (shift + this->bpp_ > 8)
244 window |= progmem_read_byte(byte + 1);
245 const uint8_t bits = (window >> (16 - this->bpp_ - shift)) & ((1u << this->bpp_) - 1);
246 const uint8_t rgb = this->bpp_ == 4 ? bits >> 1 : bits;
247 const bool opaque = this->bpp_ == 3 || (bits & 1);
248 return Color(rgb & 4 ? 0xFF : 0x00, rgb & 2 ? 0xFF : 0x00, rgb & 1 ? 0xFF : 0x00, opaque ? 0xFF : 0x00);
249}
251 const uint32_t pos = (x + y * this->width_) * static_cast<size_t>(this->bpp_) / 8;
252 Color color = Color(progmem_read_byte(this->data_start_ + pos + 2), progmem_read_byte(this->data_start_ + pos + 1),
253 progmem_read_byte(this->data_start_ + pos + 0), 0xFF);
254
255 switch (this->transparency_) {
257 if (color.g == 1 && color.r == 0 && color.b == 0) {
258 // (0, 1, 0) has been defined as transparent color for non-alpha images.
259 color.w = 0;
260 }
261 break;
263 color.w = progmem_read_byte(this->data_start_ + (pos + 3));
264 break;
265 default:
266 break;
267 }
268 return color;
269}
271 const uint8_t *pos = this->data_start_ + (x + y * this->width_) * static_cast<size_t>(this->bpp_) / 8;
272 // High byte first when big endian
273 const uint8_t high = this->big_endian_ ? 0 : 1;
274 const uint16_t rgb565 = encode_uint16(progmem_read_byte(pos + high), progmem_read_byte(pos + 1 - high));
275 auto r = (rgb565 & 0xF800) >> 11;
276 auto g = (rgb565 & 0x07E0) >> 5;
277 auto b = rgb565 & 0x001F;
278 auto a = 0xFF;
279 switch (this->transparency_) {
281 a = progmem_read_byte(this->data_start_ + this->width_ * this->height_ * 2 + (x + y * this->width_));
282 break;
284 if (rgb565 == 0x0020)
285 a = 0;
286 break;
287 default:
288 break;
289 }
290 return Color((r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2), a);
291}
292
294 const uint32_t pos = (x + y * this->width_);
295 const uint8_t gray = progmem_read_byte(this->data_start_ + pos);
296 switch (this->transparency_) {
298 if (gray == 1)
299 return Color(0, 0, 0, 0);
300 return Color(gray, gray, gray, 0xFF);
302 return Color(0, 0, 0, gray);
303 default:
304 return Color(gray, gray, gray, 0xFF);
305 }
306}
307int Image::get_width() const { return this->width_; }
308int Image::get_height() const { return this->height_; }
309ImageType Image::get_type() const { return this->type_; }
310Image::Image(const uint8_t *data_start, int width, int height, ImageType type, Transparency transparency,
311 bool big_endian)
312 : width_(width),
313 height_(height),
314 type_(type),
315 data_start_(data_start),
316 transparency_(transparency),
317 big_endian_(big_endian) {
318 switch (this->type_) {
320 this->bpp_ = 1;
321 break;
323 this->bpp_ = this->transparency_ == TRANSPARENCY_ALPHA_CHANNEL ? 4 : 3;
324 break;
326 this->bpp_ = 8;
327 break;
329 this->bpp_ = 16;
330 break;
331 case IMAGE_TYPE_RGB:
332 this->bpp_ = this->transparency_ == TRANSPARENCY_ALPHA_CHANNEL ? 32 : 24;
333 break;
334 }
335}
336
337} // namespace esphome::image
virtual bool pixel_axes_swapped() const
True when draw_pixel_at() swaps x and y before writing, so pixels that are neighbours along x land a ...
Definition display.h:757
virtual int get_height()
Get the calculated height of the display in pixels with rotation applied.
Definition display.h:338
virtual int get_width()
Get the calculated width of the display in pixels with rotation applied.
Definition display.h:336
void draw_pixel_at(int x, int y)
Set a single pixel at the specified coordinates to default color.
Definition display.h:346
void draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, ColorBitness bitness, bool big_endian, int x_offset, int y_offset, int x_pad)
Given an array of pixels encoded in the nominated format, draw these into the display's buffer.
Definition display.h:370
Rect get_clipping() const
Get the current the clipping rectangle.
Definition display.cpp:826
Color get_rgb565_pixel_(int x, int y) const
Definition image.cpp:270
const uint8_t * data_start_
Definition image.h:67
Color get_rgb_pixel_(int x, int y) const
Definition image.cpp:250
size_t get_width_stride() const
Return the stride of the image in bytes, that is, the distance in bytes between two consecutive rows ...
Definition image.h:40
Color get_pixel(int x, int y, Color color_on=display::COLOR_ON, Color color_off=display::COLOR_OFF) const
Definition image.cpp:147
ImageType type_
Definition image.h:66
int get_height() const override
Definition image.cpp:308
ImageType get_type() const
Definition image.cpp:309
bool get_binary_pixel_(int x, int y) const
Definition image.cpp:232
Image(const uint8_t *data_start, int width, int height, ImageType type, Transparency transparency, bool big_endian=false)
big_endian is the RGB565 byte order; codegen writes little endian unless configured otherwise.
Definition image.cpp:310
void draw_(int x, int y, display::Display *display, Color color_on, Color color_off, int x_start, int x_end, int y_start, int y_end)
Per-pixel draw of the clipped range, rows (true) or columns (false) outer.
Definition image.cpp:82
Transparency transparency_
Definition image.h:68
lv_img_dsc_t dsc_
Definition image.h:72
Color get_rgb111_pixel_(int x, int y) const
Definition image.cpp:237
virtual lv_image_dsc_t * get_lv_image_dsc()
Definition image.cpp:168
void draw(int x, int y, display::Display *display, Color color_on, Color color_off) override
Definition image.cpp:31
int get_width() const override
Definition image.cpp:307
Color get_grayscale_pixel_(int x, int y) const
Definition image.cpp:293
uint8_t type
ESPHOME_LOG_TAG(TAG, "image")
@ TRANSPARENCY_ALPHA_CHANNEL
Definition image.h:22
@ TRANSPARENCY_CHROMA_KEY
Definition image.h:21
@ TRANSPARENCY_OPAQUE
Definition image.h:20
@ IMAGE_TYPE_GRAYSCALE
Definition image.h:13
@ IMAGE_TYPE_BINARY
Definition image.h:12
@ IMAGE_TYPE_RGB565
Definition image.h:15
@ IMAGE_TYPE_RGB111
Definition image.h:16
@ IMAGE_TYPE_RGB
Definition image.h:14
size_t size_t pos
Definition helpers.h:1333
constexpr uint16_t encode_uint16(uint8_t msb, uint8_t lsb)
Encode a 16-bit value given the most and least significant byte.
Definition helpers.h:1043
uint8_t progmem_read_byte(const uint8_t *addr)
Definition hal.h:51
static void uint32_t
uint8_t w
Definition color.h:48
static uint8_t blend_channel(uint8_t from, uint8_t to, uint8_t amnt) ESPHOME_ALWAYS_INLINE
One channel of gradient(): from at amnt 0 to to at amnt 255.
Definition color.h:187
uint8_t g
Definition color.h:40
uint8_t b
Definition color.h:44
uint8_t r
Definition color.h:36
uint16_t x
Definition tt21100.cpp:5
uint16_t y
Definition tt21100.cpp:6