ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esphome::runtime_image::ImageDecoder Class Referenceabstract

Class to abstract decoding different image formats. More...

#include <image_decoder.h>

Inheritance diagram for esphome::runtime_image::ImageDecoder:
esphome::runtime_image::BmpDecoder esphome::runtime_image::JpegDecoder esphome::runtime_image::PngDecoder esphome::runtime_image::QoiDecoder

Public Member Functions

 ImageDecoder (RuntimeImage *image, ImageFormat format)
 Construct a new Image Decoder object.
 
virtual ~ImageDecoder ()=default
 
ImageFormat get_format () const
 Get the image format handled by this decoder.
 
bool is_active () const
 Check if a decoding session is in progress (prepare() called, reset() not yet).
 
virtual void reset ()
 Reset the decoder state, ending any decoding session.
 
virtual int prepare (size_t expected_size)
 Initialize the decoder, starting a new decoding session.
 
virtual int decode (uint8_t *buffer, size_t size)=0
 Decode a part of the image.
 
virtual bool supports_source () const
 Whether this decoder can read a DecodeSource itself, a step at a time, instead of being fed data.
 
virtual int begin_source (DecodeSource *source)
 Start decoding from a source the decoder reads itself.
 
virtual int decode_step ()
 Decode a little more of an image started with begin_source(), keeping each call short.
 
bool set_size (int width, int height)
 Request the image to be resized once the actual dimensions are known.
 
void draw (int x, int y, int w, int h, const Color &color)
 Fill a rectangle on the display_buffer using the defined color.
 
size_t get_decoded_bytes () const
 Bytes of the image the decoder has used so far.
 
virtual bool is_finished () const
 Check if the decoder has finished processing.
 
virtual bool knows_end () const
 Whether is_finished() can tell a complete image from a cut-off one.
 
bool uses_direct_rgb565 () const
 The image is opaque RGB565, so draw() writes it straight into the buffer.
 

Protected Member Functions

bool resize_image_ (int width, int height)
 Resize the image for a width x height source, without preparing to draw. prepare_draw_() must follow.
 
void prepare_draw_ (int width, int height)
 Draw a source of width x height over the whole buffer from now on.
 
void draw_rgb565_ (int x, int y, int w, int h, uint16_t rgb565)
 Paint a block of source pixels in one color straight into the buffer. Only while uses_direct_rgb565().
 
uint8_t * image_buffer_ () const
 The image's pixel buffer, for decoders that write their output straight into it.
 
bool image_is_big_endian_ () const
 

Protected Attributes

int draw_width_ = 0
 
int draw_height_ = 0
 
FixedVector< uint16_t > x_boundaries_ {}
 
FixedVector< uint16_t > y_boundaries_ {}
 
RuntimeImage * image_
 
size_t expected_size_ = 0
 
size_t decoded_bytes_ = 0
 
const ImageFormat format_
 
bool active_ = false
 
bool size_valid_ = true
 
bool direct_rgb565_ = false
 

Detailed Description

Class to abstract decoding different image formats.

Definition at line 74 of file image_decoder.h.

Constructor & Destructor Documentation

◆ ImageDecoder()

esphome::runtime_image::ImageDecoder::ImageDecoder ( RuntimeImage * image,
ImageFormat format )
inline

Construct a new Image Decoder object.

Parameters
imageThe RuntimeImage to decode the stream into.
formatThe image format this decoder handles.

Definition at line 82 of file image_decoder.h.

◆ ~ImageDecoder()

virtual esphome::runtime_image::ImageDecoder::~ImageDecoder ( )
virtualdefault

Member Function Documentation

◆ begin_source()

virtual int esphome::runtime_image::ImageDecoder::begin_source ( DecodeSource * source)
inlinevirtual

Start decoding from a source the decoder reads itself.

Call after prepare(), in place of decode().

The image headers (everything before the image data) must be readable from the source when this is called; only decode_step() can wait for more to arrive. The source must hold expected_size bytes in the end, and stay valid until the session ends.

Returns
int 0 on success, or a {
See also
DecodeError} value.

Reimplemented in esphome::runtime_image::JpegDecoder.

Definition at line 143 of file image_decoder.h.

◆ decode()

virtual int esphome::runtime_image::ImageDecoder::decode ( uint8_t * buffer,
size_t size )
pure virtual

Decode a part of the image.

It will try reading from the buffer. There is no guarantee that the whole available buffer will be read/decoded; the method will return the amount of bytes actually decoded, so that the unread content can be moved to the beginning.

Parameters
bufferThe buffer to read from.
sizeThe maximum amount of bytes that can be read from the buffer.
Returns
int The amount of bytes read. It can be 0 if the buffer does not have enough content to meaningfully decode anything, or negative in case of a decoding error.

Implemented in esphome::runtime_image::BmpDecoder, esphome::runtime_image::JpegDecoder, esphome::runtime_image::PngDecoder, and esphome::runtime_image::QoiDecoder.

◆ decode_step()

virtual int esphome::runtime_image::ImageDecoder::decode_step ( )
inlinevirtual

Decode a little more of an image started with begin_source(), keeping each call short.

Returns
int DECODE_STEP_MORE while there is more to do, DECODE_STEP_NEED_DATA when the source has not delivered enough to go on, DECODE_STEP_DONE when the image is complete, or a {
See also
DecodeError} value.

Reimplemented in esphome::runtime_image::JpegDecoder.

Definition at line 152 of file image_decoder.h.

◆ draw()

void esphome::runtime_image::ImageDecoder::draw ( int x,
int y,
int w,
int h,
const Color & color )

Fill a rectangle on the display_buffer using the defined color.

Will check the given coordinates for out-of-bounds, and clip the rectangle accordingly. In case of binary displays, the color will be converted to binary as well. Called by the callback functions, to be able to access the parent Image class.

Parameters
xThe left-most coordinate of the rectangle.
yThe top-most coordinate of the rectangle.
wThe width of the rectangle.
hThe height of the rectangle.
colorThe fill color

Definition at line 78 of file image_decoder.cpp.

◆ draw_rgb565_()

void esphome::runtime_image::ImageDecoder::draw_rgb565_ ( int x,
int y,
int w,
int h,
uint16_t rgb565 )
protected

Paint a block of source pixels in one color straight into the buffer. Only while uses_direct_rgb565().

Definition at line 51 of file image_decoder.cpp.

◆ get_decoded_bytes()

size_t esphome::runtime_image::ImageDecoder::get_decoded_bytes ( ) const
inline

Bytes of the image the decoder has used so far.

Definition at line 179 of file image_decoder.h.

◆ get_format()

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

Get the image format handled by this decoder.

Definition at line 86 of file image_decoder.h.

◆ image_buffer_()

uint8_t * esphome::runtime_image::ImageDecoder::image_buffer_ ( ) const
protected

The image's pixel buffer, for decoders that write their output straight into it.

Definition at line 109 of file image_decoder.cpp.

◆ image_is_big_endian_()

bool esphome::runtime_image::ImageDecoder::image_is_big_endian_ ( ) const
protected

Definition at line 110 of file image_decoder.cpp.

◆ is_active()

bool esphome::runtime_image::ImageDecoder::is_active ( ) const
inline

Check if a decoding session is in progress (prepare() called, reset() not yet).

Definition at line 89 of file image_decoder.h.

◆ is_finished()

virtual bool esphome::runtime_image::ImageDecoder::is_finished ( ) const
inlinevirtual

Check if the decoder has finished processing.

This should be overridden by decoders that can detect completion based on format-specific markers rather than byte counts.

Reimplemented in esphome::runtime_image::BmpDecoder, and esphome::runtime_image::QoiDecoder.

Definition at line 187 of file image_decoder.h.

◆ knows_end()

virtual bool esphome::runtime_image::ImageDecoder::knows_end ( ) const
inlinevirtual

Whether is_finished() can tell a complete image from a cut-off one.

Reimplemented in esphome::runtime_image::BmpDecoder, and esphome::runtime_image::QoiDecoder.

Definition at line 196 of file image_decoder.h.

◆ prepare()

virtual int esphome::runtime_image::ImageDecoder::prepare ( size_t expected_size)
inlinevirtual

Initialize the decoder, starting a new decoding session.

Parameters
expected_sizeHint about the expected data size (0 if unknown).
Returns
int Returns 0 on success, a {
See also
DecodeError} value in case of an error.

Reimplemented in esphome::runtime_image::JpegDecoder, and esphome::runtime_image::PngDecoder.

Definition at line 112 of file image_decoder.h.

◆ prepare_draw_()

void esphome::runtime_image::ImageDecoder::prepare_draw_ ( int width,
int height )
protected

Draw a source of width x height over the whole buffer from now on.

For an opaque RGB565 image this builds the tables of where each source column and row lands; without the memory for them it draws pixel by pixel instead.

Definition at line 23 of file image_decoder.cpp.

◆ reset()

virtual void esphome::runtime_image::ImageDecoder::reset ( )
inlinevirtual

Reset the decoder state, ending any decoding session.

Subclasses should override this method to reset any format-specific state. Buffers the next decode can reuse should be kept allocated to avoid heap churn.

Reimplemented in esphome::runtime_image::BmpDecoder, esphome::runtime_image::JpegDecoder, esphome::runtime_image::PngDecoder, and esphome::runtime_image::QoiDecoder.

Definition at line 96 of file image_decoder.h.

◆ resize_image_()

bool esphome::runtime_image::ImageDecoder::resize_image_ ( int width,
int height )
protected

Resize the image for a width x height source, without preparing to draw. prepare_draw_() must follow.

Definition at line 18 of file image_decoder.cpp.

◆ set_size()

bool esphome::runtime_image::ImageDecoder::set_size ( int width,
int height )

Request the image to be resized once the actual dimensions are known.

Called by the callback functions, to be able to access the parent Image class.

Parameters
widthThe image's width.
heightThe image's height.
Returns
true if the image was resized, false otherwise.

Definition at line 11 of file image_decoder.cpp.

◆ supports_source()

virtual bool esphome::runtime_image::ImageDecoder::supports_source ( ) const
inlinevirtual

Whether this decoder can read a DecodeSource itself, a step at a time, instead of being fed data.

Reimplemented in esphome::runtime_image::JpegDecoder.

Definition at line 133 of file image_decoder.h.

◆ uses_direct_rgb565()

bool esphome::runtime_image::ImageDecoder::uses_direct_rgb565 ( ) const
inline

The image is opaque RGB565, so draw() writes it straight into the buffer.

Definition at line 199 of file image_decoder.h.

Field Documentation

◆ active_

bool esphome::runtime_image::ImageDecoder::active_ = false
protected

Definition at line 226 of file image_decoder.h.

◆ decoded_bytes_

size_t esphome::runtime_image::ImageDecoder::decoded_bytes_ = 0
protected

Definition at line 224 of file image_decoder.h.

◆ direct_rgb565_

bool esphome::runtime_image::ImageDecoder::direct_rgb565_ = false
protected

Definition at line 228 of file image_decoder.h.

◆ draw_height_

int esphome::runtime_image::ImageDecoder::draw_height_ = 0
protected

Definition at line 218 of file image_decoder.h.

◆ draw_width_

int esphome::runtime_image::ImageDecoder::draw_width_ = 0
protected

Definition at line 217 of file image_decoder.h.

◆ expected_size_

size_t esphome::runtime_image::ImageDecoder::expected_size_ = 0
protected

Definition at line 223 of file image_decoder.h.

◆ format_

const ImageFormat esphome::runtime_image::ImageDecoder::format_
protected

Definition at line 225 of file image_decoder.h.

◆ image_

RuntimeImage* esphome::runtime_image::ImageDecoder::image_
protected

Definition at line 222 of file image_decoder.h.

◆ size_valid_

bool esphome::runtime_image::ImageDecoder::size_valid_ = true
protected

Definition at line 227 of file image_decoder.h.

◆ x_boundaries_

FixedVector<uint16_t> esphome::runtime_image::ImageDecoder::x_boundaries_ {}
protected

Definition at line 220 of file image_decoder.h.

◆ y_boundaries_

FixedVector<uint16_t> esphome::runtime_image::ImageDecoder::y_boundaries_ {}
protected

Definition at line 221 of file image_decoder.h.


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