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

#include <runtime_image.h>

Inheritance diagram for esphome::runtime_image::RuntimeImage:

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

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	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.

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.

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

lv_image_dsc_t *	get_lv_image_dsc ()

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.

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

Protected Attributes
uint8_t *	buffer_ {nullptr}

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	external_buffer_ {false}
	Whether buffer_ belongs to the caller, so it must not be freed or resized here.

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 19 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

format	The image format to decode.
type	The pixel format for the image.
transparency	The transparency type for the image.
placeholder	Optional placeholder image to show while loading.
is_big_endian	Whether the image is stored in big-endian format.
fixed_width	Fixed width for the image (0 for auto-resize).
fixed_height	Fixed height for the image (0 for auto-resize).

Definition at line 42 of file runtime_image.cpp.

◆ ~RuntimeImage()

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

Definition at line 50 of file runtime_image.cpp.

Member Function Documentation

◆ begin_decode()

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

Begin decoding an image.

Parameters

expected_size	Optional hint about the expected data size.
format	The image format to decode (defaults to AUTO, which uses the value set at construction).

Returns: true if decoder was successfully initialized.

Definition at line 191 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

format The image format to decode.

Returns: Unique pointer to the created decoder, or nullptr on failure.

Definition at line 377 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 265 of file runtime_image.cpp.

◆ 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 180 of file runtime_image.cpp.

◆ draw_pixel()

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

Definition at line 75 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 242 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

data	Pointer to the data buffer.
len	Length of data to process.

Returns: Number of bytes consumed by the decoder.

Definition at line 228 of file runtime_image.cpp.

◆ get_buffer_height()

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

inline

Definition at line 56 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 363 of file runtime_image.cpp.

◆ get_buffer_width()

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

inline

Definition at line 55 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 111 of file runtime_image.h.

◆ 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 375 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 263 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 89 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 105 of file runtime_image.h.

◆ map_chroma_key()

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

Definition at line 167 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 267 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 276 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

width	Requested width (ignored if fixed_width_ is set)
height	Requested height (ignored if fixed_height_ is set)

Returns: Size of the allocated buffer in bytes, or 0 if allocation failed.

Definition at line 52 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

width	New width in pixels.
height	New height in pixels.

Returns: Size of the allocated buffer, or 0 on failure.

Definition at line 314 of file runtime_image.cpp.

◆ 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.

Parameters

buffer	Memory for a picture of the given size, at least get_buffer_size() bytes.
width	Width of the buffer in pixels.
height	Height of the buffer in pixels.

Returns: true if the image took the buffer, false if it was refused.

Definition at line 299 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 164 of file runtime_image.h.

Field Documentation

◆ buffer_

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

protected

Definition at line 196 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 218 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 210 of file runtime_image.h.

◆ decoded_bytes_

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

protected

Definition at line 221 of file runtime_image.h.

◆ decoder_

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

protected

Definition at line 199 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 234 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 226 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 224 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 201 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 229 of file runtime_image.h.

◆ progressive_display_

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

protected

Definition at line 232 of file runtime_image.h.

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

esphome/components/runtime_image/runtime_image.h
esphome/components/runtime_image/runtime_image.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RuntimeImage()

◆ ~RuntimeImage()

Member Function Documentation

◆ begin_decode()

◆ create_decoder_()

◆ decoder_knows_end()

◆ draw()

◆ draw_pixel()

◆ end_decode()

◆ feed_data()

◆ get_buffer_height()

◆ get_buffer_size()

◆ get_buffer_width()

◆ get_format()

◆ get_position_()

◆ is_decode_finished()

◆ is_decoding()

◆ is_loaded()

◆ map_chroma_key()

◆ release()

◆ release_buffer_()

◆ resize()

◆ resize_buffer_()

◆ set_external_buffer()

◆ set_progressive_display()

Field Documentation

◆ buffer_

◆ buffer_height_

◆ buffer_width_

◆ decoded_bytes_

◆ decoder_

◆ external_buffer_

◆ fixed_height_

◆ fixed_width_

◆ format_

◆ placeholder_

◆ progressive_display_