esphome 2024.12.3__py3-none-any.whl → 2025.2.0__py3-none-any.whl

esphome/components/online_image/image_decoder.h

@@ -1,10 +1,15 @@
 #pragma once
-#include "esphome/core/defines.h"
 #include "esphome/core/color.h"
 
 namespace esphome {
 namespace online_image {
 
+enum DecodeError : int {
+  DECODE_ERROR_INVALID_TYPE = -1,
+  DECODE_ERROR_UNSUPPORTED_FORMAT = -2,
+  DECODE_ERROR_OUT_OF_MEMORY = -3,
+};
+
 class OnlineImage;
 
 /**
@@ -23,9 +28,13 @@ class ImageDecoder {
   /**
    * @brief Initialize the decoder.
    *
-   * @param download_size The total number of bytes that need to be download for the image.
+   * @param download_size The total number of bytes that need to be downloaded for the image.
+   * @return int          Returns 0 on success, a {@see DecodeError} value in case of an error.
    */
-  virtual void prepare(uint32_t download_size) { this->download_size_ = download_size; }
+  virtual int prepare(size_t download_size) {
+    this->download_size_ = download_size;
+    return 0;
+  }
 
   /**
    * @brief Decode a part of the image. It will try reading from the buffer.
@@ -38,7 +47,7 @@ class ImageDecoder {
    * @return 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.
    */
-  virtual int decode(uint8_t *buffer, size_t size);
+  virtual int decode(uint8_t *buffer, size_t size) = 0;
 
   /**
    * @brief Request the image to be resized once the actual dimensions are known.
@@ -46,11 +55,12 @@ class ImageDecoder {
    *
    * @param width The image's width.
    * @param height The image's height.
+   * @return true if the image was resized, false otherwise.
    */
-  void set_size(int width, int height);
+  bool set_size(int width, int height);
 
   /**
-   * @brief Draw a rectangle on the display_buffer using the defined color.
+   * @brief 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.
@@ -59,7 +69,7 @@ class ImageDecoder {
    * @param y The top-most coordinate of the rectangle.
    * @param w The width of the rectangle.
    * @param h The height of the rectangle.
-   * @param color The color to draw the rectangle with.
+   * @param color The fill color
    */
   void draw(int x, int y, int w, int h, const Color &color);
 
@@ -67,20 +77,17 @@ class ImageDecoder {
 
  protected:
   OnlineImage *image_;
-  // Initializing to 1, to ensure it is different than initial "decoded_bytes_".
+  // Initializing to 1, to ensure it is distinguishable from initial "decoded_bytes_".
   // Will be overwritten anyway once the download size is known.
-  uint32_t download_size_ = 1;
-  uint32_t decoded_bytes_ = 0;
+  size_t download_size_ = 1;
+  size_t decoded_bytes_ = 0;
   double x_scale_ = 1.0;
   double y_scale_ = 1.0;
 };
 
 class DownloadBuffer {
  public:
-  DownloadBuffer(size_t size) : size_(size) {
-    this->buffer_ = this->allocator_.allocate(size);
-    this->reset();
-  }
+  DownloadBuffer(size_t size);
 
   virtual ~DownloadBuffer() { this->allocator_.deallocate(this->buffer_, this->size_); }
 
@@ -100,8 +107,10 @@ class DownloadBuffer {
 
   void reset() { this->unread_ = 0; }
 
+  size_t resize(size_t size);
+
  protected:
-  ExternalRAMAllocator<uint8_t> allocator_;
+  RAMAllocator<uint8_t> allocator_{};
   uint8_t *buffer_;
   size_t size_;
   /** Total number of downloaded bytes not yet read. */

esphome/components/online_image/jpeg_image.cpp

@@ -0,0 +1,92 @@
+#include "jpeg_image.h"
+#ifdef USE_ONLINE_IMAGE_JPEG_SUPPORT
+
+#include "esphome/components/display/display_buffer.h"
+#include "esphome/core/application.h"
+#include "esphome/core/helpers.h"
+#include "esphome/core/log.h"
+
+#include "online_image.h"
+static const char *const TAG = "online_image.jpeg";
+
+namespace esphome {
+namespace online_image {
+
+/**
+ * @brief Callback method that will be called by the JPEGDEC engine when a chunk
+ * of the image is decoded.
+ *
+ * @param jpeg  The JPEGDRAW object, including the context data.
+ */
+static int draw_callback(JPEGDRAW *jpeg) {
+  ImageDecoder *decoder = (ImageDecoder *) jpeg->pUser;
+
+  // Some very big images take too long to decode, so feed the watchdog on each callback
+  // to avoid crashing.
+  App.feed_wdt();
+  size_t position = 0;
+  for (size_t y = 0; y < jpeg->iHeight; y++) {
+    for (size_t x = 0; x < jpeg->iWidth; x++) {
+      auto rg = decode_value(jpeg->pPixels[position++]);
+      auto ba = decode_value(jpeg->pPixels[position++]);
+      Color color(rg[1], rg[0], ba[1], ba[0]);
+
+      if (!decoder) {
+        ESP_LOGE(TAG, "Decoder pointer is null!");
+        return 0;
+      }
+      decoder->draw(jpeg->x + x, jpeg->y + y, 1, 1, color);
+    }
+  }
+  return 1;
+}
+
+int JpegDecoder::prepare(size_t download_size) {
+  ImageDecoder::prepare(download_size);
+  auto size = this->image_->resize_download_buffer(download_size);
+  if (size < download_size) {
+    ESP_LOGE(TAG, "Download buffer resize failed!");
+    return DECODE_ERROR_OUT_OF_MEMORY;
+  }
+  return 0;
+}
+
+int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
+  if (size < this->download_size_) {
+    ESP_LOGV(TAG, "Download not complete. Size: %d/%d", size, this->download_size_);
+    return 0;
+  }
+
+  if (!this->jpeg_.openRAM(buffer, size, draw_callback)) {
+    ESP_LOGE(TAG, "Could not open image for decoding: %d", this->jpeg_.getLastError());
+    return DECODE_ERROR_INVALID_TYPE;
+  }
+  auto jpeg_type = this->jpeg_.getJPEGType();
+  if (jpeg_type == JPEG_MODE_INVALID) {
+    ESP_LOGE(TAG, "Unsupported JPEG image");
+    return DECODE_ERROR_INVALID_TYPE;
+  } else if (jpeg_type == JPEG_MODE_PROGRESSIVE) {
+    ESP_LOGE(TAG, "Progressive JPEG images not supported");
+    return DECODE_ERROR_INVALID_TYPE;
+  }
+  ESP_LOGD(TAG, "Image size: %d x %d, bpp: %d", this->jpeg_.getWidth(), this->jpeg_.getHeight(), this->jpeg_.getBpp());
+
+  this->jpeg_.setUserPointer(this);
+  this->jpeg_.setPixelType(RGB8888);
+  if (!this->set_size(this->jpeg_.getWidth(), this->jpeg_.getHeight())) {
+    return DECODE_ERROR_OUT_OF_MEMORY;
+  }
+  if (!this->jpeg_.decode(0, 0, 0)) {
+    ESP_LOGE(TAG, "Error while decoding.");
+    this->jpeg_.close();
+    return DECODE_ERROR_UNSUPPORTED_FORMAT;
+  }
+  this->decoded_bytes_ = size;
+  this->jpeg_.close();
+  return size;
+}
+
+}  // namespace online_image
+}  // namespace esphome
+
+#endif  // USE_ONLINE_IMAGE_JPEG_SUPPORT

esphome/components/online_image/jpeg_image.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include "image_decoder.h"
+#include "esphome/core/defines.h"
+#ifdef USE_ONLINE_IMAGE_JPEG_SUPPORT
+#include <JPEGDEC.h>
+
+namespace esphome {
+namespace online_image {
+
+/**
+ * @brief Image decoder specialization for JPEG images.
+ */
+class JpegDecoder : public ImageDecoder {
+ public:
+  /**
+   * @brief Construct a new JPEG Decoder object.
+   *
+   * @param display The image to decode the stream into.
+   */
+  JpegDecoder(OnlineImage *image) : ImageDecoder(image) {}
+  ~JpegDecoder() override {}
+
+  int prepare(size_t download_size) override;
+  int HOT decode(uint8_t *buffer, size_t size) override;
+
+ protected:
+  JPEGDEC jpeg_{};
+};
+
+}  // namespace online_image
+}  // namespace esphome
+
+#endif  // USE_ONLINE_IMAGE_JPEG_SUPPORT

esphome/components/online_image/online_image.cpp

@@ -6,6 +6,12 @@ static const char *const TAG = "online_image";
 
 #include "image_decoder.h"
 
+#ifdef USE_ONLINE_IMAGE_BMP_SUPPORT
+#include "bmp_image.h"
+#endif
+#ifdef USE_ONLINE_IMAGE_JPEG_SUPPORT
+#include "jpeg_image.h"
+#endif
 #ifdef USE_ONLINE_IMAGE_PNG_SUPPORT
 #include "png_image.h"
 #endif
@@ -25,10 +31,11 @@ inline bool is_color_on(const Color &color) {
 }
 
 OnlineImage::OnlineImage(const std::string &url, int width, int height, ImageFormat format, ImageType type,
-                         uint32_t download_buffer_size)
-    : Image(nullptr, 0, 0, type),
+                         image::Transparency transparency, uint32_t download_buffer_size)
+    : Image(nullptr, 0, 0, type, transparency),
       buffer_(nullptr),
       download_buffer_(download_buffer_size),
+      download_buffer_initial_size_(download_buffer_size),
       format_(format),
       fixed_width_(width),
       fixed_height_(height) {
@@ -45,7 +52,7 @@ void OnlineImage::draw(int x, int y, display::Display *display, Color color_on,
 
 void OnlineImage::release() {
   if (this->buffer_) {
-    ESP_LOGD(TAG, "Deallocating old buffer...");
+    ESP_LOGV(TAG, "Deallocating old buffer...");
     this->allocator_.deallocate(this->buffer_, this->get_buffer_size_());
     this->data_start_ = nullptr;
     this->buffer_ = nullptr;
@@ -57,53 +64,72 @@ void OnlineImage::release() {
   }
 }
 
-bool OnlineImage::resize_(int width_in, int height_in) {
+size_t OnlineImage::resize_(int width_in, int height_in) {
   int width = this->fixed_width_;
   int height = this->fixed_height_;
-  if (this->auto_resize_()) {
+  if (this->is_auto_resize_()) {
     width = width_in;
     height = height_in;
     if (this->width_ != width && this->height_ != height) {
       this->release();
     }
   }
+  size_t new_size = this->get_buffer_size_(width, height);
   if (this->buffer_) {
-    return false;
+    // Buffer already allocated => no need to resize
+    return new_size;
   }
-  auto new_size = this->get_buffer_size_(width, height);
-  ESP_LOGD(TAG, "Allocating new buffer of %d Bytes...", new_size);
-  delay_microseconds_safe(2000);
+  ESP_LOGD(TAG, "Allocating new buffer of %zu bytes", new_size);
   this->buffer_ = this->allocator_.allocate(new_size);
-  if (this->buffer_) {
-    this->buffer_width_ = width;
-    this->buffer_height_ = height;
-    this->width_ = width;
-    ESP_LOGD(TAG, "New size: (%d, %d)", width, height);
-  } else {
-#if defined(USE_ESP8266)
-    // NOLINTNEXTLINE(readability-static-accessed-through-instance)
-    int max_block = ESP.getMaxFreeBlockSize();
-#elif defined(USE_ESP32)
-    int max_block = heap_caps_get_largest_free_block(MALLOC_CAP_INTERNAL);
-#else
-    int max_block = -1;
-#endif
-    ESP_LOGE(TAG, "allocation failed. Biggest block in heap: %d Bytes", max_block);
+  if (this->buffer_ == nullptr) {
+    ESP_LOGE(TAG, "allocation of %zu bytes failed. Biggest block in heap: %zu Bytes", new_size,
+             this->allocator_.get_max_free_block_size());
     this->end_connection_();
-    return false;
+    return 0;
   }
-  return true;
+  this->buffer_width_ = width;
+  this->buffer_height_ = height;
+  this->width_ = width;
+  ESP_LOGV(TAG, "New size: (%d, %d)", width, height);
+  return new_size;
 }
 
 void OnlineImage::update() {
   if (this->decoder_) {
     ESP_LOGW(TAG, "Image already being updated.");
     return;
-  } else {
-    ESP_LOGI(TAG, "Updating image");
   }
+  ESP_LOGI(TAG, "Updating image %s", this->url_.c_str());
+
+  std::list<http_request::Header> headers = {};
+
+  http_request::Header accept_header;
+  accept_header.name = "Accept";
+  std::string accept_mime_type;
+  switch (this->format_) {
+#ifdef USE_ONLINE_IMAGE_BMP_SUPPORT
+    case ImageFormat::BMP:
+      accept_mime_type = "image/bmp";
+      break;
+#endif  // ONLINE_IMAGE_BMP_SUPPORT
+#ifdef USE_ONLINE_IMAGE_JPEG_SUPPORT
+    case ImageFormat::JPEG:
+      accept_mime_type = "image/jpeg";
+      break;
+#endif  // USE_ONLINE_IMAGE_JPEG_SUPPORT
+#ifdef USE_ONLINE_IMAGE_PNG_SUPPORT
+    case ImageFormat::PNG:
+      accept_mime_type = "image/png";
+      break;
+#endif  // ONLINE_IMAGE_PNG_SUPPORT
+    default:
+      accept_mime_type = "image/*";
+  }
+  accept_header.value = accept_mime_type + ",*/*;q=0.8";
+
+  headers.push_back(accept_header);
 
-  this->downloader_ = this->parent_->get(this->url_);
+  this->downloader_ = this->parent_->get(this->url_, headers);
 
   if (this->downloader_ == nullptr) {
     ESP_LOGE(TAG, "Download failed.");
@@ -128,20 +154,39 @@ void OnlineImage::update() {
   ESP_LOGD(TAG, "Starting download");
   size_t total_size = this->downloader_->content_length;
 
+#ifdef USE_ONLINE_IMAGE_BMP_SUPPORT
+  if (this->format_ == ImageFormat::BMP) {
+    ESP_LOGD(TAG, "Allocating BMP decoder");
+    this->decoder_ = make_unique<BmpDecoder>(this);
+  }
+#endif  // ONLINE_IMAGE_BMP_SUPPORT
+#ifdef USE_ONLINE_IMAGE_JPEG_SUPPORT
+  if (this->format_ == ImageFormat::JPEG) {
+    ESP_LOGD(TAG, "Allocating JPEG decoder");
+    this->decoder_ = esphome::make_unique<JpegDecoder>(this);
+  }
+#endif  // USE_ONLINE_IMAGE_JPEG_SUPPORT
 #ifdef USE_ONLINE_IMAGE_PNG_SUPPORT
   if (this->format_ == ImageFormat::PNG) {
-    this->decoder_ = esphome::make_unique<PngDecoder>(this);
+    ESP_LOGD(TAG, "Allocating PNG decoder");
+    this->decoder_ = make_unique<PngDecoder>(this);
   }
 #endif  // ONLINE_IMAGE_PNG_SUPPORT
 
   if (!this->decoder_) {
-    ESP_LOGE(TAG, "Could not instantiate decoder. Image format unsupported.");
+    ESP_LOGE(TAG, "Could not instantiate decoder. Image format unsupported: %d", this->format_);
     this->end_connection_();
     this->download_error_callback_.call();
     return;
   }
-  this->decoder_->prepare(total_size);
-  ESP_LOGI(TAG, "Downloading image");
+  auto prepare_result = this->decoder_->prepare(total_size);
+  if (prepare_result < 0) {
+    this->end_connection_();
+    this->download_error_callback_.call();
+    return;
+  }
+  ESP_LOGI(TAG, "Downloading image (Size: %d)", total_size);
+  this->start_time_ = ::time(nullptr);
 }
 
 void OnlineImage::loop() {
@@ -150,10 +195,12 @@ void OnlineImage::loop() {
     return;
   }
   if (!this->downloader_ || this->decoder_->is_finished()) {
-    ESP_LOGD(TAG, "Image fully downloaded");
     this->data_start_ = buffer_;
     this->width_ = buffer_width_;
     this->height_ = buffer_height_;
+    ESP_LOGD(TAG, "Image fully downloaded, read %zu bytes, width/height = %d/%d", this->downloader_->get_bytes_read(),
+             this->width_, this->height_);
+    ESP_LOGD(TAG, "Total time: %lds", ::time(nullptr) - this->start_time_);
     this->end_connection_();
     this->download_finished_callback_.call();
     return;
@@ -164,6 +211,10 @@ void OnlineImage::loop() {
   }
   size_t available = this->download_buffer_.free_capacity();
   if (available) {
+    // Some decoders need to fully download the image before downloading.
+    // In case of huge images, don't wait blocking until the whole image has been downloaded,
+    // use smaller chunks
+    available = std::min(available, this->download_buffer_initial_size_);
     auto len = this->downloader_->read(this->download_buffer_.append(), available);
     if (len > 0) {
       this->download_buffer_.write(len);
@@ -179,6 +230,19 @@ void OnlineImage::loop() {
   }
 }
 
+void OnlineImage::map_chroma_key(Color &color) {
+  if (this->transparency_ == image::TRANSPARENCY_CHROMA_KEY) {
+    if (color.g == 1 && color.r == 0 && color.b == 0) {
+      color.g = 0;
+    }
+    if (color.w < 0x80) {
+      color.r = 0;
+      color.g = this->type_ == ImageType::IMAGE_TYPE_RGB565 ? 4 : 1;
+      color.b = 0;
+    }
+  }
+}
+
 void OnlineImage::draw_pixel_(int x, int y, Color color) {
   if (!this->buffer_) {
     ESP_LOGE(TAG, "Buffer not allocated!");
@@ -192,57 +256,53 @@ void OnlineImage::draw_pixel_(int x, int y, Color color) {
   switch (this->type_) {
     case ImageType::IMAGE_TYPE_BINARY: {
       const uint32_t width_8 = ((this->width_ + 7u) / 8u) * 8u;
-      const uint32_t pos = x + y * width_8;
-      if ((this->has_transparency() && color.w > 127) || is_color_on(color)) {
-        this->buffer_[pos / 8u] |= (0x80 >> (pos % 8u));
+      pos = x + y * width_8;
+      auto bitno = 0x80 >> (pos % 8u);
+      pos /= 8u;
+      auto on = is_color_on(color);
+      if (this->has_transparency() && color.w < 0x80)
+        on = false;
+      if (on) {
+        this->buffer_[pos] |= bitno;
       } else {
-        this->buffer_[pos / 8u] &= ~(0x80 >> (pos % 8u));
+        this->buffer_[pos] &= ~bitno;
       }
       break;
     }
     case ImageType::IMAGE_TYPE_GRAYSCALE: {
       uint8_t gray = static_cast<uint8_t>(0.2125 * color.r + 0.7154 * color.g + 0.0721 * color.b);
-      if (this->has_transparency()) {
+      if (this->transparency_ == image::TRANSPARENCY_CHROMA_KEY) {
         if (gray == 1) {
           gray = 0;
         }
         if (color.w < 0x80) {
           gray = 1;
         }
+      } else if (this->transparency_ == image::TRANSPARENCY_ALPHA_CHANNEL) {
+        if (color.w != 0xFF)
+          gray = color.w;
       }
       this->buffer_[pos] = gray;
       break;
     }
     case ImageType::IMAGE_TYPE_RGB565: {
+      this->map_chroma_key(color);
       uint16_t col565 = display::ColorUtil::color_to_565(color);
       this->buffer_[pos + 0] = static_cast<uint8_t>((col565 >> 8) & 0xFF);
       this->buffer_[pos + 1] = static_cast<uint8_t>(col565 & 0xFF);
-      if (this->has_transparency())
+      if (this->transparency_ == image::TRANSPARENCY_ALPHA_CHANNEL) {
         this->buffer_[pos + 2] = color.w;
+      }
       break;
     }
-    case ImageType::IMAGE_TYPE_RGBA: {
+    case ImageType::IMAGE_TYPE_RGB: {
+      this->map_chroma_key(color);
       this->buffer_[pos + 0] = color.r;
       this->buffer_[pos + 1] = color.g;
       this->buffer_[pos + 2] = color.b;
-      this->buffer_[pos + 3] = color.w;
-      break;
-    }
-    case ImageType::IMAGE_TYPE_RGB24:
-    default: {
-      if (this->has_transparency()) {
-        if (color.b == 1 && color.r == 0 && color.g == 0) {
-          color.b = 0;
-        }
-        if (color.w < 0x80) {
-          color.r = 0;
-          color.g = 0;
-          color.b = 1;
-        }
+      if (this->transparency_ == image::TRANSPARENCY_ALPHA_CHANNEL) {
+        this->buffer_[pos + 3] = color.w;
       }
-      this->buffer_[pos + 0] = color.r;
-      this->buffer_[pos + 1] = color.g;
-      this->buffer_[pos + 2] = color.b;
       break;
     }
   }

esphome/components/online_image/online_image.h

@@ -1,10 +1,10 @@
 #pragma once
 
+#include "esphome/components/http_request/http_request.h"
+#include "esphome/components/image/image.h"
 #include "esphome/core/component.h"
 #include "esphome/core/defines.h"
 #include "esphome/core/helpers.h"
-#include "esphome/components/http_request/http_request.h"
-#include "esphome/components/image/image.h"
 
 #include "image_decoder.h"
 
@@ -23,10 +23,12 @@ using t_http_codes = enum {
 enum ImageFormat {
   /** Automatically detect from MIME type. Not supported yet. */
   AUTO,
-  /** JPEG format. Not supported yet. */
+  /** JPEG format. */
   JPEG,
   /** PNG format. */
   PNG,
+  /** BMP format. */
+  BMP,
 };
 
 /**
@@ -48,12 +50,13 @@ class OnlineImage : public PollingComponent,
    * @param buffer_size Size of the buffer used to download the image.
    */
   OnlineImage(const std::string &url, int width, int height, ImageFormat format, image::ImageType type,
-              uint32_t buffer_size);
+              image::Transparency transparency, uint32_t buffer_size);
 
   void draw(int x, int y, display::Display *display, Color color_on, Color color_off) override;
 
   void update() override;
   void loop() override;
+  void map_chroma_key(Color &color);
 
   /** Set the URL to download the image from. */
   void set_url(const std::string &url) {
@@ -76,23 +79,42 @@ class OnlineImage : public PollingComponent,
    */
   void release();
 
+  /**
+   * Resize the download buffer
+   *
+   * @param size The new size for the download buffer.
+   */
+  size_t resize_download_buffer(size_t size) { return this->download_buffer_.resize(size); }
+
   void add_on_finished_callback(std::function<void()> &&callback);
   void add_on_error_callback(std::function<void()> &&callback);
 
  protected:
   bool validate_url_(const std::string &url);
 
-  using Allocator = ExternalRAMAllocator<uint8_t>;
-  Allocator allocator_{Allocator::Flags::ALLOW_FAILURE};
+  RAMAllocator<uint8_t> allocator_{};
 
   uint32_t get_buffer_size_() const { return get_buffer_size_(this->buffer_width_, this->buffer_height_); }
   int get_buffer_size_(int width, int height) const { return (this->get_bpp() * width + 7u) / 8u * height; }
 
   int get_position_(int x, int y) const { return (x + y * this->buffer_width_) * this->get_bpp() / 8; }
 
-  ESPHOME_ALWAYS_INLINE bool auto_resize_() const { return this->fixed_width_ == 0 || this->fixed_height_ == 0; }
+  ESPHOME_ALWAYS_INLINE bool is_auto_resize_() const { return this->fixed_width_ == 0 || this->fixed_height_ == 0; }
 
-  bool resize_(int width, int height);
+  /**
+   * @brief Resize the image buffer to the requested dimensions.
+   *
+   * The buffer will be allocated if not existing.
+   * If the dimensions have been fixed in the yaml config, 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
+   * allocated
+   *
+   * @param width
+   * @param height
+   * @return 0 if no memory could be allocated, the size of the new buffer otherwise.
+   */
+  size_t resize_(int width, int height);
 
   /**
    * @brief Draw a pixel into the buffer.
@@ -117,6 +139,12 @@ class OnlineImage : public PollingComponent,
 
   uint8_t *buffer_;
   DownloadBuffer download_buffer_;
+  /**
+   * This is the *initial* size of the download buffer, not the current size.
+   * The download buffer can be resized at runtime; the download_buffer_initial_size_
+   * will *not* change even if the download buffer has been resized.
+   */
+  size_t download_buffer_initial_size_;
 
   const ImageFormat format_;
   image::Image *placeholder_{nullptr};
@@ -146,7 +174,9 @@ class OnlineImage : public PollingComponent,
    */
   int buffer_height_;
 
-  friend void ImageDecoder::set_size(int width, int height);
+  time_t start_time_;
+
+  friend bool ImageDecoder::set_size(int width, int height);
   friend void ImageDecoder::draw(int x, int y, int w, int h, const Color &color);
 };
 

esphome/components/online_image/png_image.cpp

@@ -2,7 +2,6 @@
 #ifdef USE_ONLINE_IMAGE_PNG_SUPPORT
 
 #include "esphome/components/display/display_buffer.h"
-#include "esphome/core/application.h"
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
@@ -41,17 +40,22 @@ static void draw_callback(pngle_t *pngle, uint32_t x, uint32_t y, uint32_t w, ui
   decoder->draw(x, y, w, h, color);
 }
 
-void PngDecoder::prepare(uint32_t download_size) {
+int PngDecoder::prepare(size_t download_size) {
   ImageDecoder::prepare(download_size);
+  if (!this->pngle_) {
+    ESP_LOGE(TAG, "PNG decoder engine not initialized!");
+    return DECODE_ERROR_OUT_OF_MEMORY;
+  }
   pngle_set_user_data(this->pngle_, this);
   pngle_set_init_callback(this->pngle_, init_callback);
   pngle_set_draw_callback(this->pngle_, draw_callback);
+  return 0;
 }
 
 int HOT PngDecoder::decode(uint8_t *buffer, size_t size) {
   if (!this->pngle_) {
     ESP_LOGE(TAG, "PNG decoder engine not initialized!");
-    return -1;
+    return DECODE_ERROR_OUT_OF_MEMORY;
   }
   if (size < 256 && size < this->download_size_ - this->decoded_bytes_) {
     ESP_LOGD(TAG, "Waiting for data");

esphome/components/online_image/png_image.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "image_decoder.h"
+#include "esphome/core/defines.h"
 #ifdef USE_ONLINE_IMAGE_PNG_SUPPORT
 #include <pngle.h>
 
@@ -20,7 +21,7 @@ class PngDecoder : public ImageDecoder {
   PngDecoder(OnlineImage *image) : ImageDecoder(image), pngle_(pngle_new()) {}
   ~PngDecoder() override { pngle_destroy(this->pngle_); }
 
-  void prepare(uint32_t download_size) override;
+  int prepare(size_t download_size) override;
   int HOT decode(uint8_t *buffer, size_t size) override;
 
  protected: