ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
jpeg_decoder.cpp
Go to the documentation of this file.
1#include "jpeg_decoder.h"
2#ifdef USE_RUNTIME_IMAGE_JPEG
3
9#include "esphome/core/log.h"
10
11#ifdef USE_ESP_IDF
12#include "esp_task_wdt.h"
13#endif
14
15ESPHOME_LOG_TAG(TAG, "image_decoder.jpeg");
16
17namespace esphome::runtime_image {
18
19void JpegDecoder::draw_rgb565(int x, int y, int w, int h, const uint8_t *pixels) {
20 if (pixels == nullptr) {
21 return;
22 }
23 uint8_t *const buffer = this->image_buffer_();
24 const uint32_t buffer_width = this->image_->get_buffer_width();
25 // JPEGDEC gives little-endian words; a big-endian image stores the high byte first
26 const uint8_t first = this->image_is_big_endian_() ? 1 : 0;
27 for (int source_y = 0; source_y < h; source_y++) {
28 const int absolute_y = y + source_y;
29 if (absolute_y < 0 || absolute_y >= this->draw_height_) {
30 continue;
31 }
32 const uint16_t y1 = this->y_boundaries_[absolute_y];
33 const uint16_t y2 = this->y_boundaries_[absolute_y + 1];
34 for (int source_x = 0; source_x < w; source_x++) {
35 const int absolute_x = x + source_x;
36 if (absolute_x < 0 || absolute_x >= this->draw_width_) {
37 continue;
38 }
39 const uint16_t x1 = this->x_boundaries_[absolute_x];
40 const uint16_t x2 = this->x_boundaries_[absolute_x + 1];
41 const uint8_t *pixel = pixels + (source_y * w + source_x) * 2;
42 for (uint16_t destination_y = y1; destination_y < y2; destination_y++) {
43 uint8_t *destination = buffer + (destination_y * buffer_width + x1) * 2;
44 for (uint16_t destination_x = x1; destination_x < x2; destination_x++) {
45 destination[0] = pixel[first];
46 destination[1] = pixel[1 - first];
47 destination += 2;
48 }
49 }
50 }
51 }
52}
53
54// Some very big images take too long to decode, so feed the watchdog as the decode goes
55// to avoid crashing if the executing task has a watchdog enabled.
56static void feed_watchdog() {
57#ifdef USE_ESP_IDF
58 if (esp_task_wdt_status(nullptr) == ESP_OK) {
59#endif
60 App.feed_wdt();
61#ifdef USE_ESP_IDF
62 }
63#endif
64}
65
72static int draw_callback(JPEGDRAW *jpeg) {
73 JpegDecoder *decoder = (JpegDecoder *) jpeg->pUser;
74
75 if (decoder == nullptr) {
76 ESP_LOGE(TAG, "Decoder pointer is null!");
77 return 0;
78 }
79
80 feed_watchdog();
81 if (decoder->uses_direct_rgb565()) {
82 decoder->draw_rgb565(jpeg->x, jpeg->y, jpeg->iWidth, jpeg->iHeight,
83 reinterpret_cast<const uint8_t *>(jpeg->pPixels));
84 return 1;
85 }
86 size_t position = 0;
87 size_t height = static_cast<size_t>(jpeg->iHeight);
88 size_t width = static_cast<size_t>(jpeg->iWidth);
89 for (size_t y = 0; y < height; y++) {
90 for (size_t x = 0; x < width; x++) {
91 auto rg = decode_value(jpeg->pPixels[position++]);
92 auto ba = decode_value(jpeg->pPixels[position++]);
93 Color color(rg[1], rg[0], ba[1], ba[0]);
94
95 decoder->draw(jpeg->x + x, jpeg->y + y, 1, 1, color);
96 }
97 }
98 return 1;
99}
100
102 : ImageDecoder(image, JPEG), jpeg_(RAMAllocator<JPEGDEC>().make_unique()) {
103 if (this->jpeg_ == nullptr) {
104 ESP_LOGE(TAG, "Failed to allocate memory for the JPEG decoder");
105 }
106}
107
108int JpegDecoder::prepare(size_t expected_size) {
109 // Check before the base prepare() so a failure never leaves an active session
110 if (this->jpeg_ == nullptr) {
111 ESP_LOGE(TAG, "JPEG decoder engine not initialized!");
113 }
114 return ImageDecoder::prepare(expected_size);
115}
116
117int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
118 if (this->jpeg_ == nullptr) {
119 ESP_LOGE(TAG, "JPEG decoder engine not initialized!");
121 }
122 // JPEG decoder requires complete data
123 // If we know the expected size, wait for it
125 ESP_LOGV(TAG, "Download not complete. Size: %zu/%zu", size, this->expected_size_);
126 return 0;
127 }
128
129 // If size unknown, try to decode what has arrived. JPEGDEC usually fails on an incomplete baseline image, but draws
130 // the scans that arrived of an incomplete progressive image and reports success, so any data after that cannot open.
131
132 if (!this->jpeg_->openRAM(buffer, size, draw_callback)) {
133 ESP_LOGE(TAG, "Could not open image for decoding: %d", this->jpeg_->getLastError());
135 }
136 const int err = this->start_();
137 if (err != 0)
138 return err;
139 // Row by row rather than with decode(): a progressive image decodes all its scans before the first draw callback
140 if (!this->jpeg_->decodeBegin(0, 0, this->scale_option_()))
141 return this->fail_();
142 int result;
143 while ((result = this->jpeg_->decodeRows(1)) == JPEG_DECODE_MORE)
144 feed_watchdog();
145 if (result != 1)
146 return this->fail_();
147 this->decoded_bytes_ = size;
148 this->jpeg_->close();
149 return size;
150}
151
153 auto jpeg_type = this->jpeg_->getJPEGType();
154 if (jpeg_type == JPEG_MODE_INVALID) {
155 ESP_LOGE(TAG, "Unsupported JPEG image");
157 }
158 ESP_LOGD(TAG, "Image size: %d x %d, bpp: %d", this->jpeg_->getWidth(), this->jpeg_->getHeight(),
159 this->jpeg_->getBpp());
160
161 this->jpeg_->setUserPointer(this);
162 const int width = this->jpeg_->getWidth();
163 const int height = this->jpeg_->getHeight();
164 // The tables for drawing are only built once the decoded size is known, below
165 if (!this->resize_image_(width, height)) {
167 }
168 // JPEGDEC can decode at 1/2, 1/4 or 1/8 size for much less work. Use the smallest size that still has at least as
169 // many pixels as the buffer, so a large image shown small is not decoded in full only to be thrown away.
170 const int buffer_width = this->image_->get_buffer_width();
171 const int buffer_height = this->image_->get_buffer_height();
172 this->scale_ = 1;
173 while (this->scale_ < JPEG_SCALE_EIGHTH && width / (this->scale_ * 2) >= buffer_width &&
174 height / (this->scale_ * 2) >= buffer_height) {
175 this->scale_ *= 2;
176 }
177 const int decoded_width = (width + this->scale_ - 1) / this->scale_;
178 const int decoded_height = (height + this->scale_ - 1) / this->scale_;
179 if (this->scale_ != 1) {
180 ESP_LOGD(TAG, "Decoding at 1/%d size, %d x %d", this->scale_, decoded_width, decoded_height);
181 }
182 this->prepare_draw_(decoded_width, decoded_height);
183 if (this->direct_rgb565_) {
184 // JPEGDEC's RGB565_BIG_ENDIAN output is not byte swapped on every build (the x86 host build
185 // returns little-endian words for it), so the byte order is applied in draw_rgb565 instead
186 this->jpeg_->setPixelType(RGB565_LITTLE_ENDIAN);
187 } else {
188 this->jpeg_->setPixelType(RGB8888);
189 }
190 return 0;
191}
192
194 const bool read_failed = this->source_ != nullptr && this->source_failed_;
195 const int error = this->jpeg_->getLastError();
196 this->jpeg_->close();
197 this->source_ = nullptr;
198 if (read_failed) {
199 ESP_LOGE(TAG, "Reading the image failed");
200 return DECODE_ERROR_READ;
201 }
202 ESP_LOGE(TAG, "Error while decoding: %d", error);
203 switch (error) {
204 case JPEG_ERROR_MEMORY:
206 case JPEG_UNSUPPORTED_FEATURE:
208 case JPEG_INVALID_FILE:
209 case JPEG_INVALID_PARAMETER:
211 case JPEG_DECODE_ERROR:
212 default:
214 }
215}
216
218 // A decode from a source that was given up part way still has the image open
219 if (this->source_ != nullptr) {
220 this->jpeg_->close();
221 this->source_ = nullptr;
222 }
224}
225
226int32_t JpegDecoder::source_read(JPEGFILE *file, uint8_t *buf, int32_t len) {
227 auto *decoder = static_cast<JpegDecoder *>(file->fHandle);
228 const int32_t n = decoder->source_->read(buf, len);
229 if (n < 0) {
230 // JPEGDEC has no way to report a failed read, so remember it and give it no data
231 decoder->source_failed_ = true;
232 return 0;
233 }
234 file->iPos += n;
235 return n;
236}
237
238int32_t JpegDecoder::source_seek(JPEGFILE *file, int32_t position) {
239 auto *decoder = static_cast<JpegDecoder *>(file->fHandle);
241 decoder->source_failed_ = true;
242 return file->iPos;
243 }
244 file->iPos = position;
245 return position;
246}
247
249 if (this->jpeg_ == nullptr) {
250 ESP_LOGE(TAG, "JPEG decoder engine not initialized!");
252 }
253 if (this->expected_size_ == 0 || this->expected_size_ > INT32_MAX) {
254 ESP_LOGE(TAG, "Image size %zu cannot be read from a source", this->expected_size_);
256 }
257 if (!source->seek(0)) {
258 ESP_LOGE(TAG, "Could not read the image");
259 return DECODE_ERROR_READ;
260 }
261 this->source_ = source;
262 this->source_failed_ = false;
263 if (!this->jpeg_->open(this, this->expected_size_, source_close, source_read, source_seek, draw_callback)) {
264 // The caller may recover, for example by reading the whole image first, so it reports the failure
265 ESP_LOGD(TAG, "Could not open image for decoding: %d", this->jpeg_->getLastError());
266 this->source_ = nullptr;
268 }
269 const int err = this->start_();
270 if (err != 0) {
271 this->jpeg_->close();
272 this->source_ = nullptr;
273 return err;
274 }
275 if (!this->jpeg_->decodeBegin(0, 0, this->scale_option_()))
276 return this->fail_();
277 return 0;
278}
279
281 if (this->source_ == nullptr)
283 const int result = this->jpeg_->decodeRows(1);
284 // JPEGDEC may decode on with the missing data, so check the read before its result
285 if (this->source_failed_)
286 return this->fail_();
287 if (result == JPEG_DECODE_MORE)
288 return DECODE_STEP_MORE;
289 if (result == JPEG_DECODE_NEED_DATA)
291 if (result == 0)
292 return this->fail_();
293 this->decoded_bytes_ = this->expected_size_;
294 this->jpeg_->close();
295 this->source_ = nullptr;
296 return DECODE_STEP_DONE;
297}
298
299} // namespace esphome::runtime_image
300
301#endif // USE_RUNTIME_IMAGE_JPEG
uint8_t h
Definition bl0906.h:2
void feed_wdt()
Feed the task watchdog.
An STL allocator that uses SPI or internal RAM.
Definition helpers.h:2396
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 void reset()
Reset the decoder state, ending any decoding session.
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.
FixedVector< uint16_t > y_boundaries_
virtual int prepare(size_t expected_size)
Initialize the decoder, starting a new decoding session.
Image decoder specialization for JPEG images.
RAMUniquePtr< JPEGDEC > jpeg_
About 18 KB of decoder state: PSRAM first, nullptr if out of memory.
int prepare(size_t expected_size) override
int begin_source(DecodeSource *source) override
void draw_rgb565(int x, int y, int w, int h, const uint8_t *pixels)
int start_()
Set up an opened image for decoding. Returns 0, or a DecodeError.
static int32_t source_read(JPEGFILE *file, uint8_t *buf, int32_t len)
JpegDecoder(RuntimeImage *image)
Construct a new JPEG Decoder object.
int fail_()
The DecodeError for a failed read of the source or JPEGDEC's last error, closing the image.
int HOT decode(uint8_t *buffer, size_t size) override
int HOT decode_step() override
Decodes one row of MCUs (8 or 16 pixel rows), or waits part way through one for more of the source.
static int32_t source_seek(JPEGFILE *file, int32_t position)
static void source_close(void *handle)
A dynamic image that can be loaded and decoded at runtime.
float position
Definition cover.h:0
uint32_t buffer
Definition gif.cpp:50
ESPHOME_LOG_TAG(TAG, "image_decoder.jpeg")
const void size_t len
Definition hal.h:68
uint16_t size
Definition helpers.cpp:34
constexpr std::array< uint8_t, sizeof(T)> decode_value(T val)
Decode a value into its constituent bytes (from most to least significant).
Definition helpers.h:1101
Application App
Global storage of Application pointer - only one Application can exist.
static void uint32_t
uint16_t x
Definition tt21100.cpp:5
uint16_t y
Definition tt21100.cpp:6