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.

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_img_dsc_t *	get_lv_img_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.

size_t	get_buffer_size_ (int width, int height) const
	Get the buffer size in bytes for given dimensions.

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
RAMAllocator< uint8_t >	allocator_ {}

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.

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

◆ ~RuntimeImage()

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

Definition at line 39 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 155 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 280 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 144 of file runtime_image.cpp.

◆ draw_pixel()

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

Definition at line 56 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 195 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 181 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

protected

Get the buffer size in bytes for given dimensions.

Definition at line 274 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 278 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 215 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 131 of file runtime_image.cpp.

◆ release()

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

Release the image buffer and free memory.

Definition at line 222 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 230 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 41 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 243 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 133 of file runtime_image.h.

Field Documentation

◆ allocator_

RAMAllocator<uint8_t> esphome::runtime_image::RuntimeImage::allocator_ {}

protected

Definition at line 168 of file runtime_image.h.

◆ buffer_

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

protected

Definition at line 169 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 191 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 183 of file runtime_image.h.

◆ decoded_bytes_

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

protected

Definition at line 195 of file runtime_image.h.

◆ decoder_

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

protected

Definition at line 172 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 200 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 198 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 174 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 211 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 203 of file runtime_image.h.

◆ progressive_display_

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

protected

Definition at line 206 of file runtime_image.h.

◆ total_size_

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

protected

Definition at line 194 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_progressive_display()

Field Documentation

◆ allocator_

◆ buffer_

◆ buffer_height_

◆ buffer_width_

◆ decoded_bytes_

◆ decoder_

◆ fixed_height_

◆ fixed_width_

◆ format_

◆ is_big_endian_

◆ placeholder_

◆ progressive_display_

◆ total_size_