ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esphome::runtime_image::RuntimeImage Class Reference

A dynamic image that can be loaded and decoded at runtime. More...

#include <runtime_image.h>

Inheritance diagram for esphome::runtime_image::RuntimeImage:
esphome::image::Image esphome::display::BaseImage esphome::online_image::OnlineImage esphome::sendspin_::ArtworkDecodeSink

Public Member Functions

 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.
 
 ~RuntimeImage ()
 
int resize (int width, int height)
 Resize the image buffer to the requested dimensions.
 
void draw_pixel (int x, int y, const Color &color)
 
void map_chroma_key (Color &color)
 
int get_buffer_width () const
 
int get_buffer_height () const
 
lv_image_dsc_t * get_lv_image_dsc () override
 Until an image is loaded, the placeholder's descriptor if there is one.
 
void add_lvgl_widget (lv_obj_t *obj) override
 
void draw (int x, int y, display::Display *display, Color color_on, Color color_off) override
 
bool begin_decode (size_t expected_size=0, ImageFormat format=AUTO)
 Begin decoding an image.
 
int feed_data (uint8_t *data, size_t len)
 Feed data to the decoder.
 
bool decoder_supports_source () const
 Whether the active decoder can read a DecodeSource itself (see begin_source()).
 
int begin_source (DecodeSource *source)
 Decode from a source the decoder reads itself, in place of feed_data().
 
int decode_step ()
 Decode a little more from the source; see ImageDecoder::decode_step().
 
bool end_decode ()
 Complete the decoding process.
 
bool is_decoding () const
 Check if decoding is currently in progress.
 
bool is_decode_finished () const
 Check if the decoder has finished processing all data.
 
bool decoder_knows_end () const
 True while decoding and the decoder can tell a complete image from a cut-off one.
 
bool is_loaded () const
 Check if an image is currently loaded.
 
ImageFormat get_format () const
 Get the image format.
 
void release ()
 Release the image buffer and free its memory, ending any decode session.
 
void abort_decode ()
 End a decode that will not be finished.
 
bool set_external_buffer (uint8_t *buffer, int width, int height)
 Decode into a buffer the caller owns, instead of one allocated here.
 
size_t get_buffer_size (int width, int height) const
 Get the buffer size in bytes needed for a picture of the given dimensions.
 
void set_progressive_display (bool progressive)
 Set whether to allow progressive display during decode.
 
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.
 
- Public Member Functions inherited from esphome::image::Image
 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.
 
Color get_pixel (int x, int y, Color color_on=display::COLOR_ON, Color color_off=display::COLOR_OFF) const
 
int get_width () const override
 
int get_height () const override
 
const uint8_t * get_data_start () const
 
ImageType get_type () const
 
int get_bpp () const
 
size_t get_width_stride () const
 Return the stride of the image in bytes, that is, the distance in bytes between two consecutive rows of pixels.
 
bool has_transparency () const
 
- Public Member Functions inherited from esphome::display::BaseImage

Protected Member Functions

size_t resize_buffer_ (int width, int height)
 Resize the image buffer to the requested dimensions.
 
void release_buffer_ ()
 Release only the image buffer without resetting the decoder.
 
bool is_double_buffered_ () const
 
void refresh_lvgl_ ()
 Bring the LVGL descriptor up to date after the image shown changed, and give it again to the widgets showing it.
 
int get_position_ (int x, int y) const
 Get the position in the buffer for a pixel.
 
std::unique_ptr< ImageDecoder > create_decoder_ (ImageFormat format)
 Create decoder instance for the requested format.
 
- Protected Member Functions inherited from esphome::image::Image
template<bool ROWS_OUTER>
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.
 
bool get_binary_pixel_ (int x, int y) const
 
Color get_rgb111_pixel_ (int x, int y) const
 
Color get_rgb_pixel_ (int x, int y) const
 
Color get_rgb565_pixel_ (int x, int y) const
 
Color get_grayscale_pixel_ (int x, int y) const
 

Static Protected Member Functions

static void lvgl_widget_deleted (lv_event_t *event)
 

Protected Attributes

uint8_t * buffer_ {nullptr}
 
uint8_t * front_buffer_ {nullptr}
 With double buffering, the buffer on show, width_ by height_. buffer_ is then the one decoded into.
 
std::unique_ptr< ImageDecoder > decoder_ {nullptr}
 
const ImageFormat format_
 The image format this RuntimeImage is configured to decode.
 
int buffer_width_ {0}
 Actual width of the current image.
 
int buffer_height_ {0}
 Actual height of the current image.
 
size_t decoded_bytes_ {0}
 
const int fixed_width_ {0}
 Fixed width requested on configuration, or 0 if not specified.
 
const int fixed_height_ {0}
 Fixed height requested on configuration, or 0 if not specified.
 
image::Image * placeholder_ {nullptr}
 Placeholder image to show when the runtime image is not available.
 
bool progressive_display_ {false}
 
bool double_buffer_ {false}
 
bool external_buffer_ {false}
 Whether buffer_ belongs to the caller, so it must not be freed or resized here.
 
std::vector< lv_obj_t * > lvgl_widgets_
 Widgets given this image. One moved to another image is dropped at the next refresh.
 
- Protected Attributes inherited from esphome::image::Image
int width_
 
int height_
 
ImageType type_
 
const uint8_t * data_start_
 
Transparency transparency_
 
bool big_endian_
 
uint8_t bpp_ {}
 
lv_img_dsc_t dsc_ {}
 

Detailed Description

A dynamic image that can be loaded and decoded at runtime.

This class provides dynamic buffer allocation and management for images that are decoded at runtime, as opposed to static images compiled into the firmware. It serves as a base class for components that need to load images dynamically from various sources.

Definition at line 21 of file runtime_image.h.

Constructor & Destructor Documentation

◆ RuntimeImage()

esphome::runtime_image::RuntimeImage::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.

Parameters
formatThe image format to decode.
typeThe pixel format for the image.
transparencyThe transparency type for the image.
placeholderOptional placeholder image to show while loading.
is_big_endianWhether the image is stored in big-endian format.
fixed_widthFixed width for the image (0 for auto-resize).
fixed_heightFixed height for the image (0 for auto-resize).

Definition at line 44 of file runtime_image.cpp.

◆ ~RuntimeImage()

esphome::runtime_image::RuntimeImage::~RuntimeImage ( )

Definition at line 52 of file runtime_image.cpp.

Member Function Documentation

◆ abort_decode()

void esphome::runtime_image::RuntimeImage::abort_decode ( )

End a decode that will not be finished.

With double buffering the image on show stays and the buffer decoded into is kept for the next decode. Otherwise the same as release(), since the image on show was being decoded over.

Definition at line 368 of file runtime_image.cpp.

◆ add_lvgl_widget()

void esphome::runtime_image::RuntimeImage::add_lvgl_widget ( lv_obj_t * obj)
overridevirtual

Reimplemented from esphome::image::Image.

Definition at line 199 of file runtime_image.cpp.

◆ begin_decode()

bool esphome::runtime_image::RuntimeImage::begin_decode ( size_t expected_size = 0,
ImageFormat format = AUTO )

Begin decoding an image.

Parameters
expected_sizeOptional hint about the expected data size.
formatThe image format to decode (defaults to AUTO, which uses the value set at construction).
Returns
true if decoder was successfully initialized.

Definition at line 245 of file runtime_image.cpp.

◆ begin_source()

int esphome::runtime_image::RuntimeImage::begin_source ( DecodeSource * source)

Decode from a source the decoder reads itself, in place of feed_data().

Call after begin_decode() when decoder_supports_source() is true, once the image headers can be read from the source, then call decode_step() until it returns DECODE_STEP_DONE, and finish with end_decode().

Returns
0 on success, or a DecodeError value.

Definition at line 296 of file runtime_image.cpp.

◆ create_decoder_()

std::unique_ptr< ImageDecoder > esphome::runtime_image::RuntimeImage::create_decoder_ ( ImageFormat format)
protected

Create decoder instance for the requested format.

Parameters
formatThe image format to decode.
Returns
Unique pointer to the created decoder, or nullptr on failure.

Definition at line 485 of file runtime_image.cpp.

◆ decode_step()

int esphome::runtime_image::RuntimeImage::decode_step ( )

Decode a little more from the source; see ImageDecoder::decode_step().

Definition at line 304 of file runtime_image.cpp.

◆ decoder_knows_end()

bool esphome::runtime_image::RuntimeImage::decoder_knows_end ( ) const

True while decoding and the decoder can tell a complete image from a cut-off one.

Definition at line 348 of file runtime_image.cpp.

◆ decoder_supports_source()

bool esphome::runtime_image::RuntimeImage::decoder_supports_source ( ) const
inline

Whether the active decoder can read a DecodeSource itself (see begin_source()).

Definition at line 89 of file runtime_image.h.

◆ draw()

void esphome::runtime_image::RuntimeImage::draw ( int x,
int y,
display::Display * display,
Color color_on,
Color color_off )
overridevirtual

Reimplemented from esphome::image::Image.

Definition at line 234 of file runtime_image.cpp.

◆ draw_pixel()

void esphome::runtime_image::RuntimeImage::draw_pixel ( int x,
int y,
const Color & color )

Definition at line 85 of file runtime_image.cpp.

◆ end_decode()

bool esphome::runtime_image::RuntimeImage::end_decode ( )

Complete the decoding process.

Returns
true if decoding completed successfully.

Definition at line 315 of file runtime_image.cpp.

◆ feed_data()

int esphome::runtime_image::RuntimeImage::feed_data ( uint8_t * data,
size_t len )

Feed data to the decoder.

Parameters
dataPointer to the data buffer.
lenLength of data to process.
Returns
Number of bytes consumed by the decoder.

Definition at line 282 of file runtime_image.cpp.

◆ get_buffer_height()

int esphome::runtime_image::RuntimeImage::get_buffer_height ( ) const
inline

Definition at line 58 of file runtime_image.h.

◆ get_buffer_size()

size_t esphome::runtime_image::RuntimeImage::get_buffer_size ( int width,
int height ) const

Get the buffer size in bytes needed for a picture of the given dimensions.

Returns 0 for dimensions the image cannot decode at.

Definition at line 471 of file runtime_image.cpp.

◆ get_buffer_width()

int esphome::runtime_image::RuntimeImage::get_buffer_width ( ) const
inline

Definition at line 57 of file runtime_image.h.

◆ get_format()

ImageFormat esphome::runtime_image::RuntimeImage::get_format ( ) const
inline

Get the image format.

Configured format; a format resolved per decode lives on the active decoder

Definition at line 138 of file runtime_image.h.

◆ get_lv_image_dsc()

lv_image_dsc_t * esphome::runtime_image::RuntimeImage::get_lv_image_dsc ( )
overridevirtual

Until an image is loaded, the placeholder's descriptor if there is one.

Reimplemented from esphome::image::Image.

Definition at line 189 of file runtime_image.cpp.

◆ get_position_()

int esphome::runtime_image::RuntimeImage::get_position_ ( int x,
int y ) const
protected

Get the position in the buffer for a pixel.

Definition at line 483 of file runtime_image.cpp.

◆ is_decode_finished()

bool esphome::runtime_image::RuntimeImage::is_decode_finished ( ) const

Check if the decoder has finished processing all data.

This delegates to the decoder's format-specific completion check, which handles both known-size and chunked transfer cases.

Definition at line 346 of file runtime_image.cpp.

◆ is_decoding()

bool esphome::runtime_image::RuntimeImage::is_decoding ( ) const
inline

Check if decoding is currently in progress.

Definition at line 114 of file runtime_image.h.

◆ is_double_buffered_()

bool esphome::runtime_image::RuntimeImage::is_double_buffered_ ( ) const
inlineprotected

Definition at line 227 of file runtime_image.h.

◆ is_loaded()

bool esphome::runtime_image::RuntimeImage::is_loaded ( ) const
inline

Check if an image is currently loaded.

Definition at line 130 of file runtime_image.h.

◆ lvgl_widget_deleted()

void esphome::runtime_image::RuntimeImage::lvgl_widget_deleted ( lv_event_t * event)
staticprotected

Definition at line 206 of file runtime_image.cpp.

◆ map_chroma_key()

void esphome::runtime_image::RuntimeImage::map_chroma_key ( Color & color)

Definition at line 175 of file runtime_image.cpp.

◆ refresh_lvgl_()

void esphome::runtime_image::RuntimeImage::refresh_lvgl_ ( )
protected

Bring the LVGL descriptor up to date after the image shown changed, and give it again to the widgets showing it.

Definition at line 213 of file runtime_image.cpp.

◆ release()

void esphome::runtime_image::RuntimeImage::release ( )

Release the image buffer and free its memory, ending any decode session.

An external buffer is let go of rather than freed. The decoder object is kept warm so the next decode can reuse it without churning the heap.

Definition at line 350 of file runtime_image.cpp.

◆ release_buffer_()

void esphome::runtime_image::RuntimeImage::release_buffer_ ( )
protected

Release only the image buffer without resetting the decoder.

This is safe to call from within the decoder (e.g., during resize).

Definition at line 378 of file runtime_image.cpp.

◆ resize()

int esphome::runtime_image::RuntimeImage::resize ( int width,
int height )

Resize the image buffer to the requested dimensions.

The buffer will be allocated if not existing. If fixed dimensions have been specified in the constructor, the buffer will be created with those dimensions and not resized, even on request. Otherwise, the old buffer will be deallocated and a new buffer with the requested dimensions allocated.

Parameters
widthRequested width (ignored if fixed_width_ is set)
heightRequested height (ignored if fixed_height_ is set)
Returns
Size of the allocated buffer in bytes, or 0 if allocation failed.

Definition at line 61 of file runtime_image.cpp.

◆ resize_buffer_()

size_t esphome::runtime_image::RuntimeImage::resize_buffer_ ( int width,
int height )
protected

Resize the image buffer to the requested dimensions.

Parameters
widthNew width in pixels.
heightNew height in pixels.
Returns
Size of the allocated buffer, or 0 on failure.

Definition at line 422 of file runtime_image.cpp.

◆ set_double_buffer()

void esphome::runtime_image::RuntimeImage::set_double_buffer ( bool double_buffer)
inline

Set whether to decode into a second buffer, keeping the image on show until the new one is complete.

Both buffers are kept, so a new image of the same size allocates nothing. Ignored with progressive display.

Definition at line 208 of file runtime_image.h.

◆ set_external_buffer()

bool esphome::runtime_image::RuntimeImage::set_external_buffer ( uint8_t * buffer,
int width,
int height )

Decode into a buffer the caller owns, instead of one allocated here.

The image never frees an external buffer and never resizes it: a decode that needs other dimensions fails as if the allocation had failed, and the buffer is let go of so a decoder that ignores that failure cannot publish a picture it did not paint. The caller keeps the buffer alive for as long as anything can draw the image, and calls release() (or hands over another buffer) before reusing it.

Hand a buffer over before every decode. The image lets go of one whenever a decode fails and whenever release() is called, and it does not remember that it ever had one: a decode that starts without a buffer allocates its own, which is the runtime allocation this method exists to avoid.

The buffer is decoded into as it is handed over, so the caller owns its initial contents. Zero it first if anything can draw the image before a decode has painted every pixel.

Do not hand a buffer over while is_decoding() is true. A running decoder keeps scaling values for the buffer it started with.

A null buffer or dimensions the image cannot decode at are refused, leaving the image with no buffer at all.

Refused when double buffering is on.

Parameters
bufferMemory for a picture of the given size, at least get_buffer_size() bytes.
widthWidth of the buffer in pixels.
heightHeight of the buffer in pixels.
Returns
true if the image took the buffer, false if it was refused.

Definition at line 403 of file runtime_image.cpp.

◆ set_progressive_display()

void esphome::runtime_image::RuntimeImage::set_progressive_display ( bool progressive)
inline

Set whether to allow progressive display during decode.

When enabled, the image can be displayed even while still decoding. When disabled, the image is only displayed after decoding completes.

Definition at line 201 of file runtime_image.h.

Field Documentation

◆ buffer_

uint8_t* esphome::runtime_image::RuntimeImage::buffer_ {nullptr}
protected

Definition at line 245 of file runtime_image.h.

◆ buffer_height_

int esphome::runtime_image::RuntimeImage::buffer_height_ {0}
protected

Actual height of the current image.

This needs to be separate from "Image::get_height()" because the latter must return 0 until the image has been decoded (to avoid showing partially decoded images). When progressive_display_ is enabled, Image dimensions are updated during decoding to allow rendering in progress.

Definition at line 269 of file runtime_image.h.

◆ buffer_width_

int esphome::runtime_image::RuntimeImage::buffer_width_ {0}
protected

Actual width of the current image.

This needs to be separate from "Image::get_width()" because the latter must return 0 until the image has been decoded (to avoid showing partially decoded images). When progressive_display_ is enabled, Image dimensions are updated during decoding to allow rendering in progress.

Definition at line 261 of file runtime_image.h.

◆ decoded_bytes_

size_t esphome::runtime_image::RuntimeImage::decoded_bytes_ {0}
protected

Definition at line 272 of file runtime_image.h.

◆ decoder_

std::unique_ptr<ImageDecoder> esphome::runtime_image::RuntimeImage::decoder_ {nullptr}
protected

Definition at line 250 of file runtime_image.h.

◆ double_buffer_

bool esphome::runtime_image::RuntimeImage::double_buffer_ {false}
protected

Definition at line 284 of file runtime_image.h.

◆ external_buffer_

bool esphome::runtime_image::RuntimeImage::external_buffer_ {false}
protected

Whether buffer_ belongs to the caller, so it must not be freed or resized here.

Definition at line 286 of file runtime_image.h.

◆ fixed_height_

const int esphome::runtime_image::RuntimeImage::fixed_height_ {0}
protected

Fixed height requested on configuration, or 0 if not specified.

Definition at line 277 of file runtime_image.h.

◆ fixed_width_

const int esphome::runtime_image::RuntimeImage::fixed_width_ {0}
protected

Fixed width requested on configuration, or 0 if not specified.

Definition at line 275 of file runtime_image.h.

◆ format_

const ImageFormat esphome::runtime_image::RuntimeImage::format_
protected

The image format this RuntimeImage is configured to decode.

Definition at line 252 of file runtime_image.h.

◆ front_buffer_

uint8_t* esphome::runtime_image::RuntimeImage::front_buffer_ {nullptr}
protected

With double buffering, the buffer on show, width_ by height_. buffer_ is then the one decoded into.

Definition at line 247 of file runtime_image.h.

◆ lvgl_widgets_

std::vector<lv_obj_t *> esphome::runtime_image::RuntimeImage::lvgl_widgets_
protected

Widgets given this image. One moved to another image is dropped at the next refresh.

Definition at line 290 of file runtime_image.h.

◆ placeholder_

image::Image* esphome::runtime_image::RuntimeImage::placeholder_ {nullptr}
protected

Placeholder image to show when the runtime image is not available.

Definition at line 280 of file runtime_image.h.

◆ progressive_display_

bool esphome::runtime_image::RuntimeImage::progressive_display_ {false}
protected

Definition at line 283 of file runtime_image.h.


The documentation for this class was generated from the following files: