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

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)

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_ ()
	Create decoder instance for the image's format.

Protected Member Functions inherited from esphome::image::Image
bool	get_binary_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	total_size_ {0}

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	is_big_endian_ {false}
	Whether the image is stored in big-endian format.

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_

size_t	bpp_ {}

size_t	stride_ {}

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 33 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 40 of file runtime_image.cpp.

◆ ~RuntimeImage()

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

Definition at line 49 of file runtime_image.cpp.

Member Function Documentation

◆ begin_decode()

bool esphome::runtime_image::RuntimeImage::begin_decode ( size_t expected_size = 0 )

Begin decoding an image.

Parameters

expected_size Optional hint about the expected data size.

Returns: true if decoder was successfully initialized.

Definition at line 174 of file runtime_image.cpp.

◆ create_decoder_()

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

protected

Create decoder instance for the image's format.

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

◆ draw_pixel()

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

Definition at line 74 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 214 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 200 of file runtime_image.cpp.

◆ get_buffer_height()

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

inline

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

◆ get_buffer_width()

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

inline

Definition at line 69 of file runtime_image.h.

◆ get_format()

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

inline

Get the image format.

Definition at line 120 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 348 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 234 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 102 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 115 of file runtime_image.h.

◆ map_chroma_key()

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

Definition at line 150 of file runtime_image.cpp.

◆ release()

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

Release the image buffer and free memory.

An external buffer is let go of rather than freed.

Definition at line 241 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 249 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 51 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 287 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 272 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 172 of file runtime_image.h.

Field Documentation

◆ buffer_

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

protected

Definition at line 202 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 224 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 216 of file runtime_image.h.

◆ decoded_bytes_

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

protected

Definition at line 228 of file runtime_image.h.

◆ decoder_

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

protected

Definition at line 205 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 246 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 233 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 231 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 207 of file runtime_image.h.

◆ is_big_endian_

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

protected

Whether the image is stored in big-endian format.

This is used to determine how to store 16 bit colors in the buffer.

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

◆ progressive_display_

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

protected

Definition at line 239 of file runtime_image.h.

◆ total_size_

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

protected

Definition at line 227 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_()

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

◆ is_big_endian_

◆ placeholder_

◆ progressive_display_

◆ total_size_