ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
image_decoder.h
Go to the documentation of this file.
1#pragma once
2#include <cstdint>
3
6#include "image_format.h"
7
9
12inline int scale_boundary(int n, int source, int target) {
13 if (source <= 0)
14 return 0;
15 return static_cast<int>((static_cast<uint32_t>(n) * static_cast<uint32_t>(target) + source - 1) /
16 static_cast<uint32_t>(source));
17}
18
26
28enum DecodeStep : int {
31 DECODE_STEP_NEED_DATA = 2, // The source has nothing more yet; call again once more has arrived
32};
33
34constexpr const char *decode_error_to_string(int error) {
35 switch (error) {
37 return "Invalid type";
39 return "Unsupported format";
41 return "Out of memory";
43 return "Internal decoder error";
45 return "Read error";
46 default:
47 return "Unknown error";
48 }
49}
50
51// The longest one decode() call works before it returns, leaving the rest of the data for the next call
52static constexpr uint32_t DECODE_TIME_LIMIT_MS = 15;
53// Pixel loops read the clock once per this many steps
54static constexpr uint32_t DECODE_TIME_CHECK_STEPS = 64;
55
56class RuntimeImage;
57
60 public:
61 virtual ~DecodeSource() = default;
66 virtual int32_t read(uint8_t *buf, uint32_t len) = 0;
68 virtual bool seek(uint32_t position) = 0;
69};
70
75 public:
83 virtual ~ImageDecoder() = default;
84
86 ImageFormat get_format() const { return this->format_; }
87
89 bool is_active() const { return this->active_; }
90
96 virtual void reset() {
97 this->active_ = false;
98 this->expected_size_ = 0;
99 this->decoded_bytes_ = 0;
100 this->size_valid_ = true;
101 this->draw_width_ = 0;
102 this->draw_height_ = 0;
103 this->direct_rgb565_ = false;
104 }
105
112 virtual int prepare(size_t expected_size) {
113 this->reset();
114 this->expected_size_ = expected_size;
115 this->active_ = true;
116 return 0;
117 }
118
130 virtual int decode(uint8_t *buffer, size_t size) = 0;
131
133 virtual bool supports_source() const { return false; }
134
144
153
162 bool set_size(int width, int height);
163
176 void draw(int x, int y, int w, int h, const Color &color);
177
179 size_t get_decoded_bytes() const { return this->decoded_bytes_; }
180
187 virtual bool is_finished() const {
188 if (this->expected_size_ > 0) {
189 return this->decoded_bytes_ >= this->expected_size_;
190 }
191 // If size is unknown, derived classes should override this
192 return false;
193 }
194
196 virtual bool knows_end() const { return this->expected_size_ > 0; }
197
199 bool uses_direct_rgb565() const { return this->direct_rgb565_; }
200
201 protected:
203 bool resize_image_(int width, int height);
208 void prepare_draw_(int width, int height);
210 void draw_rgb565_(int x, int y, int w, int h, uint16_t rgb565);
211
213 uint8_t *image_buffer_() const;
214 bool image_is_big_endian_() const;
215
216 // Size of the image as the decoder draws it, which draw() spreads over the buffer
217 int draw_width_ = 0;
219 // Boundary n is the first buffer column, or row, that source column, or row, n paints
223 size_t expected_size_ = 0; // Expected data size (0 if unknown)
224 size_t decoded_bytes_ = 0; // Bytes processed so far
226 bool active_ = false; // A decoding session is in progress
227 bool size_valid_ = true; // Last set_size() result; draw() no-ops while false
228 bool direct_rgb565_ = false;
229};
230
231} // namespace esphome::runtime_image
uint8_t h
Definition bl0906.h:2
Fixed-capacity vector - sized once through init() or try_init(); push_back never reallocates This avo...
Definition helpers.h:669
Input that a decoder reads itself as it goes, so the whole image never has to be in memory at once.
virtual int32_t read(uint8_t *buf, uint32_t len)=0
Read up to len bytes at the current position.
virtual bool seek(uint32_t position)=0
Move to a position counted from the start. Returns false on error.
Class to abstract decoding different image formats.
FixedVector< uint16_t > x_boundaries_
void prepare_draw_(int width, int height)
Draw a source of width x height over the whole buffer from now on.
virtual bool knows_end() const
Whether is_finished() can tell a complete image from a cut-off one.
virtual void reset()
Reset the decoder state, ending any decoding session.
size_t get_decoded_bytes() const
Bytes of the image the decoder has used so far.
ImageDecoder(RuntimeImage *image, ImageFormat format)
Construct a new Image Decoder object.
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()...
bool resize_image_(int width, int height)
Resize the image for a width x height source, without preparing to draw. prepare_draw_() must follow.
uint8_t * image_buffer_() const
The image's pixel buffer, for decoders that write their output straight into it.
bool is_active() const
Check if a decoding session is in progress (prepare() called, reset() not yet).
virtual bool is_finished() const
Check if the decoder has finished processing.
virtual int decode(uint8_t *buffer, size_t size)=0
Decode a part of the image.
virtual int begin_source(DecodeSource *source)
Start decoding from a source the decoder reads itself.
void draw(int x, int y, int w, int h, const Color &color)
Fill a rectangle on the display_buffer using the defined color.
ImageFormat get_format() const
Get the image format handled by this decoder.
FixedVector< uint16_t > y_boundaries_
bool uses_direct_rgb565() const
The image is opaque RGB565, so draw() writes it straight into the buffer.
bool set_size(int width, int height)
Request the image to be resized once the actual dimensions are known.
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 prepare(size_t expected_size)
Initialize the decoder, starting a new decoding session.
virtual int decode_step()
Decode a little more of an image started with begin_source(), keeping each call short.
A dynamic image that can be loaded and decoded at runtime.
float position
Definition cover.h:0
uint32_t buffer
Definition gif.cpp:50
const char * format
ImageFormat
Image format types that can be decoded dynamically.
DecodeStep
Results of ImageDecoder::decode_step() other than a DecodeError.
int scale_boundary(int n, int source, int target)
The first of target pixels that pixel n of source paints, rounded up: ceil(n * target / source).
constexpr const char * decode_error_to_string(int error)
const void size_t len
Definition hal.h:68
uint16_t size
Definition helpers.cpp:34
static void uint32_t
uint16_t x
Definition tt21100.cpp:5
uint16_t y
Definition tt21100.cpp:6