ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
runtime_image.h
Go to the documentation of this file.
1#pragma once
2
5
6#include <vector>
7
8#include "image_decoder.h"
9#include "image_format.h"
10
11namespace esphome::runtime_image {
12
21class RuntimeImage : public image::Image {
22 public:
35 image::Image *placeholder = nullptr, bool is_big_endian = false, int fixed_width = 0,
36 int fixed_height = 0);
37
39
40 // Decoder interface methods
54 int resize(int width, int height);
55 void draw_pixel(int x, int y, const Color &color);
56 void map_chroma_key(Color &color);
57 int get_buffer_width() const { return this->buffer_width_; }
58 int get_buffer_height() const { return this->buffer_height_; }
59#ifdef USE_LVGL
61 lv_image_dsc_t *get_lv_image_dsc() override;
62#endif
63#ifdef USE_LVGL_IMAGE
64 void add_lvgl_widget(lv_obj_t *obj) override;
65#endif
66
67 // Image drawing interface
68 void draw(int x, int y, display::Display *display, Color color_on, Color color_off) override;
69
77 bool begin_decode(size_t expected_size = 0, ImageFormat format = AUTO);
78
86 int feed_data(uint8_t *data, size_t len);
87
89 bool decoder_supports_source() const { return this->is_decoding() && this->decoder_->supports_source(); }
90
99 int begin_source(DecodeSource *source);
100
102 int decode_step();
103
109 bool end_decode();
110
114 bool is_decoding() const { return this->decoder_ != nullptr && this->decoder_->is_active(); }
115
122 bool is_decode_finished() const;
123
125 bool decoder_knows_end() const;
126
130 bool is_loaded() const {
131 return this->is_double_buffered_() ? this->front_buffer_ != nullptr : this->buffer_ != nullptr;
132 }
133
138 ImageFormat get_format() const { return this->format_; }
139
146 void release();
147
154 void abort_decode();
155
186 bool set_external_buffer(uint8_t *buffer, int width, int height);
187
193 size_t get_buffer_size(int width, int height) const;
194
201 void set_progressive_display(bool progressive) { this->progressive_display_ = progressive; }
202
208 void set_double_buffer(bool double_buffer) { this->double_buffer_ = double_buffer; }
209
210 protected:
218 size_t resize_buffer_(int width, int height);
219
225 void release_buffer_();
226
227 bool is_double_buffered_() const { return this->double_buffer_ && !this->progressive_display_; }
228
230 void refresh_lvgl_();
231
235 int get_position_(int x, int y) const;
236
242 std::unique_ptr<ImageDecoder> create_decoder_(ImageFormat format);
243
244 // Memory management
245 uint8_t *buffer_{nullptr};
247 uint8_t *front_buffer_{nullptr};
248
249 // Decoder management
250 std::unique_ptr<ImageDecoder> decoder_{nullptr};
253
270
271 // Decoding state
272 size_t decoded_bytes_{0};
273
275 const int fixed_width_{0};
277 const int fixed_height_{0};
278
281
282 // Configuration
284 bool double_buffer_{false};
286 bool external_buffer_{false};
287#ifdef USE_LVGL_IMAGE
288 static void lvgl_widget_deleted(lv_event_t *event);
290 std::vector<lv_obj_t *> lvgl_widgets_;
291#endif
292
293 friend class ImageDecoder;
294};
295
296} // namespace esphome::runtime_image
Input that a decoder reads itself as it goes, so the whole image never has to be in memory at once.
Class to abstract decoding different image formats.
A dynamic image that can be loaded and decoded at runtime.
int decode_step()
Decode a little more from the source; see ImageDecoder::decode_step().
bool is_loaded() const
Check if an image is currently loaded.
static void lvgl_widget_deleted(lv_event_t *event)
void set_double_buffer(bool double_buffer)
Set whether to decode into a second buffer, keeping the image on show until the new one is complete.
bool begin_decode(size_t expected_size=0, ImageFormat format=AUTO)
Begin decoding an image.
bool is_decoding() const
Check if decoding is currently in progress.
void draw(int x, int y, display::Display *display, Color color_on, Color color_off) override
size_t get_buffer_size(int width, int height) const
Get the buffer size in bytes needed for a picture of the given dimensions.
int buffer_width_
Actual width of the current image.
int begin_source(DecodeSource *source)
Decode from a source the decoder reads itself, in place of feed_data().
bool end_decode()
Complete the decoding process.
void set_progressive_display(bool progressive)
Set whether to allow progressive display during decode.
int get_position_(int x, int y) const
Get the position in the buffer for a pixel.
const int fixed_height_
Fixed height requested on configuration, or 0 if not specified.
void release_buffer_()
Release only the image buffer without resetting the decoder.
void abort_decode()
End a decode that will not be finished.
int resize(int width, int height)
Resize the image buffer to the requested dimensions.
int feed_data(uint8_t *data, size_t len)
Feed data to the decoder.
const int fixed_width_
Fixed width requested on configuration, or 0 if not specified.
bool is_decode_finished() const
Check if the decoder has finished processing all data.
void release()
Release the image buffer and free its memory, ending any decode session.
image::Image * placeholder_
Placeholder image to show when the runtime image is not available.
RuntimeImage(ImageFormat format, image::ImageType type, image::Transparency transparency, image::Image *placeholder=nullptr, bool is_big_endian=false, int fixed_width=0, int fixed_height=0)
Construct a new RuntimeImage object.
bool decoder_knows_end() const
True while decoding and the decoder can tell a complete image from a cut-off one.
ImageFormat get_format() const
Get the image format.
const ImageFormat format_
The image format this RuntimeImage is configured to decode.
size_t resize_buffer_(int width, int height)
Resize the image buffer to the requested dimensions.
std::unique_ptr< ImageDecoder > decoder_
lv_image_dsc_t * get_lv_image_dsc() override
Until an image is loaded, the placeholder's descriptor if there is one.
std::vector< lv_obj_t * > lvgl_widgets_
Widgets given this image. One moved to another image is dropped at the next refresh.
void draw_pixel(int x, int y, const Color &color)
std::unique_ptr< ImageDecoder > create_decoder_(ImageFormat format)
Create decoder instance for the requested format.
int buffer_height_
Actual height of the current image.
uint8_t * front_buffer_
With double buffering, the buffer on show, width_ by height_. buffer_ is then the one decoded into.
bool decoder_supports_source() const
Whether the active decoder can read a DecodeSource itself (see begin_source()).
bool set_external_buffer(uint8_t *buffer, int width, int height)
Decode into a buffer the caller owns, instead of one allocated here.
void refresh_lvgl_()
Bring the LVGL descriptor up to date after the image shown changed, and give it again to the widgets ...
void add_lvgl_widget(lv_obj_t *obj) override
bool external_buffer_
Whether buffer_ belongs to the caller, so it must not be freed or resized here.
uint8_t type
uint32_t buffer
Definition gif.cpp:50
const char * format
ImageFormat
Image format types that can be decoded dynamically.
@ AUTO
Format is supplied per decode, e.g.
const void size_t len
Definition hal.h:68
uint16_t x
Definition tt21100.cpp:5
uint16_t y
Definition tt21100.cpp:6