[runtime_image] keep decoder allocated (#18488)

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: J. Nick Koston <nick@home-assistant.io>
Co-authored-by: J. Nick Koston <nick@koston.org>

esphome/components/online_image/online_image.cpp

@@ -216,7 +216,7 @@ void OnlineImage::loop() {
 }
 
 void OnlineImage::end_connection_() {
-  // Abort any in-progress decode to free decoder resources.
+  // Abort any in-progress decode; the decoder object is kept warm for the next decode.
   // Use RuntimeImage::release() directly to avoid recursion with OnlineImage::release().
   if (this->is_decoding()) {
     RuntimeImage::release();

esphome/components/runtime_image/__init__.py

@@ -77,6 +77,11 @@ class JPEGFormat(Format):
     def actions(self) -> None:
         cg.add_define("USE_RUNTIME_IMAGE_JPEG")
         cg.add_library("JPEGDEC", "1.8.4", "https://github.com/bitbank2/JPEGDEC#1.8.4")
+        if CORE.is_host:
+            # JPEGDEC's host detection checks __MACH__/__LINUX__, but gcc only
+            # predefines the lowercase __linux__; without this a Linux host
+            # build tries to include Arduino.h.
+            cg.add_build_flag("-D__LINUX__")
         if CORE.is_esp32:
             from esphome.components.esp32 import add_idf_component
 

esphome/components/runtime_image/bmp_decoder.cpp

@@ -12,6 +12,22 @@ namespace esphome::runtime_image {
 
 static const char *const TAG = "image_decoder.bmp";
 
+void BmpDecoder::reset() {
+  ImageDecoder::reset();
+  this->bits_per_pixel_ = 0;
+  this->compression_method_ = 0;
+  this->image_data_size_ = 0;
+  this->width_ = 0;
+  this->height_ = 0;
+  this->current_index_ = 0;
+  this->paint_index_ = 0;
+  // color_table_ is deliberately kept allocated so the next decode can reuse it
+  this->color_table_entries_ = 0;
+  this->data_offset_ = 0;
+  this->padding_bytes_ = 0;
+  this->width_bytes_ = 0;
+}
+
 int HOT BmpDecoder::decode(uint8_t *buffer, size_t size) {
   size_t index = 0;
   if (this->current_index_ == 0) {
@@ -85,7 +101,10 @@ int HOT BmpDecoder::decode(uint8_t *buffer, size_t size) {
         size_t header_size = encode_uint32(buffer[17], buffer[16], buffer[15], buffer[14]);
         size_t offset = 14 + header_size;
 
-        this->color_table_ = std::make_unique<uint32_t[]>(this->color_table_entries_);
+        if (this->color_table_entries_ > this->color_table_capacity_) {
+          this->color_table_ = std::make_unique<uint32_t[]>(this->color_table_entries_);
+          this->color_table_capacity_ = this->color_table_entries_;
+        }
 
         for (size_t i = 0; i < this->color_table_entries_; i++) {
           this->color_table_[i] = encode_uint32(buffer[offset + i * 4 + 3], buffer[offset + i * 4 + 2],

esphome/components/runtime_image/bmp_decoder.h

@@ -21,8 +21,9 @@ class BmpDecoder : public ImageDecoder {
    *
    * @param image The RuntimeImage to decode the stream into.
    */
-  BmpDecoder(RuntimeImage *image) : ImageDecoder(image) {}
+  BmpDecoder(RuntimeImage *image) : ImageDecoder(image, BMP) {}
 
+  void reset() override;
   int HOT decode(uint8_t *buffer, size_t size) override;
 
   bool is_finished() const override {
@@ -35,17 +36,18 @@ class BmpDecoder : public ImageDecoder {
   }
 
  protected:
+  std::unique_ptr<uint32_t[]> color_table_;
   size_t current_index_{0};
   size_t paint_index_{0};
   ssize_t width_{0};
   ssize_t height_{0};
-  uint16_t bits_per_pixel_{0};
+  size_t width_bytes_{0};
+  size_t data_offset_{0};
   uint32_t compression_method_{0};
   uint32_t image_data_size_{0};
   uint32_t color_table_entries_{0};
-  std::unique_ptr<uint32_t[]> color_table_;
-  size_t width_bytes_{0};
-  size_t data_offset_{0};
+  uint32_t color_table_capacity_{0};  // Allocated entries in color_table_, kept across decodes
+  uint16_t bits_per_pixel_{0};
   uint8_t padding_bytes_{0};
 };
 

esphome/components/runtime_image/image_decoder.h

@@ -1,5 +1,6 @@
 #pragma once
 #include "esphome/core/color.h"
+#include "image_format.h"
 
 namespace esphome::runtime_image {
 
@@ -36,18 +37,41 @@ class ImageDecoder {
    * @brief Construct a new Image Decoder object
    *
    * @param image The RuntimeImage to decode the stream into.
+   * @param format The image format this decoder handles.
    */
-  ImageDecoder(RuntimeImage *image) : image_(image) {}
+  ImageDecoder(RuntimeImage *image, ImageFormat format) : image_(image), format_(format) {}
   virtual ~ImageDecoder() = default;
 
+  /// @brief Get the image format handled by this decoder.
+  ImageFormat get_format() const { return this->format_; }
+
+  /// @brief Check if a decoding session is in progress (prepare() called, reset() not yet).
+  bool is_active() const { return this->active_; }
+
   /**
-   * @brief Initialize the decoder.
+   * @brief 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.
+   */
+  virtual void reset() {
+    this->active_ = false;
+    this->expected_size_ = 0;
+    this->decoded_bytes_ = 0;
+    this->size_valid_ = true;
+    this->x_scale_ = 1.0;
+    this->y_scale_ = 1.0;
+  }
+
+  /**
+   * @brief Initialize the decoder, starting a new decoding session.
    *
    * @param expected_size Hint about the expected data size (0 if unknown).
    * @return int          Returns 0 on success, a {@see DecodeError} value in case of an error.
    */
   virtual int prepare(size_t expected_size) {
+    this->reset();
     this->expected_size_ = expected_size;
+    this->active_ = true;
     return 0;
   }
 
@@ -103,11 +127,13 @@ class ImageDecoder {
   }
 
  protected:
+  double x_scale_ = 1.0;
+  double y_scale_ = 1.0;
   RuntimeImage *image_;
   size_t expected_size_ = 0;  // Expected data size (0 if unknown)
   size_t decoded_bytes_ = 0;  // Bytes processed so far
-  double x_scale_ = 1.0;
-  double y_scale_ = 1.0;
+  const ImageFormat format_;
+  bool active_ = false;     // A decoding session is in progress
   bool size_valid_ = true;  // Last set_size() result; draw() no-ops while false
 };
 

esphome/components/runtime_image/image_format.h

@@ -0,0 +1,19 @@
+#pragma once
+
+namespace esphome::runtime_image {
+
+/**
+ * @brief Image format types that can be decoded dynamically.
+ */
+enum ImageFormat {
+  /** Automatically detect from data. Not implemented yet. */
+  AUTO,
+  /** JPEG format. */
+  JPEG,
+  /** PNG format. */
+  PNG,
+  /** BMP format. */
+  BMP,
+};
+
+}  // namespace esphome::runtime_image

esphome/components/runtime_image/jpeg_decoder.cpp

@@ -52,12 +52,6 @@ static int draw_callback(JPEGDRAW *jpeg) {
   return 1;
 }
 
-int JpegDecoder::prepare(size_t expected_size) {
-  ImageDecoder::prepare(expected_size);
-  // JPEG decoder needs complete data before decoding
-  return 0;
-}
-
 int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
   // JPEG decoder requires complete data
   // If we know the expected size, wait for it

esphome/components/runtime_image/jpeg_decoder.h

@@ -18,10 +18,9 @@ class JpegDecoder : public ImageDecoder {
    *
    * @param image The RuntimeImage to decode the stream into.
    */
-  JpegDecoder(RuntimeImage *image) : ImageDecoder(image) {}
+  JpegDecoder(RuntimeImage *image) : ImageDecoder(image, JPEG) {}
   ~JpegDecoder() override {}
 
-  int prepare(size_t expected_size) override;
   int HOT decode(uint8_t *buffer, size_t size) override;
 
  protected:

esphome/components/runtime_image/png_decoder.cpp

@@ -48,7 +48,7 @@ static void draw_callback(pngle_t *pngle, uint32_t x, uint32_t y, uint32_t w, ui
   }
 }
 
-PngDecoder::PngDecoder(RuntimeImage *image) : ImageDecoder(image) {
+PngDecoder::PngDecoder(RuntimeImage *image) : ImageDecoder(image, PNG) {
   {
     RAMAllocator<pngle_t> allocator;
     pngle_t *pngle = allocator.allocate(1, PNGLE_T_SIZE);
@@ -57,8 +57,8 @@ PngDecoder::PngDecoder(RuntimeImage *image) : ImageDecoder(image) {
       return;
     }
     memset(pngle, 0, PNGLE_T_SIZE);
-    pngle_reset(pngle);
     this->pngle_ = pngle;
+    pngle_reset(this->pngle_);
   }
 }
 
@@ -71,11 +71,12 @@ PngDecoder::~PngDecoder() {
 }
 
 int PngDecoder::prepare(size_t expected_size) {
-  ImageDecoder::prepare(expected_size);
+  // Check before the base prepare() so a failure never leaves an active session
   if (!this->pngle_) {
     ESP_LOGE(TAG, "PNG decoder engine not initialized!");
     return DECODE_ERROR_OUT_OF_MEMORY;
   }
+  ImageDecoder::prepare(expected_size);
   pngle_set_user_data(this->pngle_, this);
   pngle_set_init_callback(this->pngle_, init_callback);
   pngle_set_draw_callback(this->pngle_, draw_callback);

esphome/components/runtime_image/png_decoder.h

@@ -22,6 +22,14 @@ class PngDecoder : public ImageDecoder {
   PngDecoder(RuntimeImage *image);
   ~PngDecoder() override;
 
+  void reset() override {
+    ImageDecoder::reset();
+    if (this->pngle_) {
+      pngle_reset(this->pngle_);
+    }
+    this->pixels_decoded_ = 0;
+  }
+
   int prepare(size_t expected_size) override;
   int HOT decode(uint8_t *buffer, size_t size) override;
 

esphome/components/runtime_image/runtime_image.cpp

@@ -172,33 +172,38 @@ void RuntimeImage::draw(int x, int y, display::Display *display, Color color_on,
 }
 
 bool RuntimeImage::begin_decode(size_t expected_size) {
-  if (this->decoder_) {
+  if (this->is_decoding()) {
     ESP_LOGW(TAG, "Decoding already in progress");
     return false;
   }
 
-  this->decoder_ = this->create_decoder_();
-  if (!this->decoder_) {
-    ESP_LOGE(TAG, "Failed to create decoder for format %d", this->format_);
-    return false;
+  // An idle decoder for a different format cannot be reused
+  if (this->decoder_ != nullptr && this->decoder_->get_format() != this->format_) {
+    ESP_LOGD(TAG, "Decoder format mismatch: current: %d, new: %d", this->decoder_->get_format(), this->format_);
+    this->decoder_ = nullptr;
+  }
+
+  if (!this->decoder_) {
+    this->decoder_ = this->create_decoder_(this->format_);
+    if (!this->decoder_) {
+      ESP_LOGE(TAG, "Failed to create decoder for format %d", this->format_);
+      return false;
+    }
   }
 
-  this->total_size_ = expected_size;
   this->decoded_bytes_ = 0;
 
-  // Initialize decoder
   int result = this->decoder_->prepare(expected_size);
   if (result < 0) {
     ESP_LOGE(TAG, "Failed to prepare decoder: %d", result);
-    this->decoder_ = nullptr;
+    this->decoder_ = nullptr;  // If prepare fails, a full reset is needed
     return false;
   }
-
   return true;
 }
 
 int RuntimeImage::feed_data(uint8_t *data, size_t len) {
-  if (!this->decoder_) {
+  if (!this->is_decoding()) {
     ESP_LOGE(TAG, "No decoder initialized");
     return -1;
   }
@@ -212,7 +217,7 @@ int RuntimeImage::feed_data(uint8_t *data, size_t len) {
 }
 
 bool RuntimeImage::end_decode() {
-  if (!this->decoder_) {
+  if (!this->is_decoding()) {
     return false;
   }
 
@@ -224,26 +229,23 @@ bool RuntimeImage::end_decode() {
     this->data_start_ = this->buffer_;
   }
 
-  // Clean up decoder
-  this->decoder_ = nullptr;
+  // End the session; the decoder object stays warm so the next decode can
+  // reuse it (and its buffers) without churning the heap.
+  this->decoder_->reset();
 
   ESP_LOGD(TAG, "Decoding complete: %dx%d, %zu bytes", this->width_, this->height_, this->decoded_bytes_);
   return true;
 }
 
-bool RuntimeImage::is_decode_finished() const {
-  if (!this->decoder_) {
-    return false;
-  }
-  return this->decoder_->is_finished();
-}
+bool RuntimeImage::is_decode_finished() const { return this->is_decoding() && this->decoder_->is_finished(); }
 
 void RuntimeImage::release() {
   this->release_buffer_();
-  // Reset decoder separately — release() can be called from within the decoder
-  // (via set_size -> resize -> resize_buffer_), so we must not destroy the decoder here.
-  // The decoder lifecycle is managed by begin_decode()/end_decode().
-  this->decoder_ = nullptr;
+  // End any active decode session; decoders free the format-specific working buffers
+  // they can (PNG), while the decoder object itself is kept warm for the next decode.
+  if (this->decoder_) {
+    this->decoder_->reset();
+  }
 }
 
 void RuntimeImage::release_buffer_() {
@@ -347,8 +349,9 @@ size_t RuntimeImage::get_buffer_size(int width, int height) const {
 
 int RuntimeImage::get_position_(int x, int y) const { return (x + y * this->buffer_width_) * this->get_bpp() / 8; }
 
-std::unique_ptr<ImageDecoder> RuntimeImage::create_decoder_() {
-  switch (this->format_) {
+std::unique_ptr<ImageDecoder> RuntimeImage::create_decoder_(ImageFormat format) {
+  ESP_LOGV(TAG, "Creating decoder for format %d", format);
+  switch (format) {
 #ifdef USE_RUNTIME_IMAGE_BMP
     case BMP:
       return make_unique<BmpDecoder>(this);
@@ -362,7 +365,7 @@ std::unique_ptr<ImageDecoder> RuntimeImage::create_decoder_() {
       return make_unique<PngDecoder>(this);
 #endif
     default:
-      ESP_LOGE(TAG, "Unsupported image format: %d", this->format_);
+      ESP_LOGE(TAG, "Unsupported image format: %d", format);
       return nullptr;
   }
 }

esphome/components/runtime_image/runtime_image.h

@@ -3,25 +3,11 @@
 #include "esphome/components/image/image.h"
 #include "esphome/core/helpers.h"
 
+#include "image_decoder.h"
+#include "image_format.h"
+
 namespace esphome::runtime_image {
 
-// Forward declaration
-class ImageDecoder;
-
-/**
- * @brief Image format types that can be decoded dynamically.
- */
-enum ImageFormat {
-  /** Automatically detect from data. Not implemented yet. */
-  AUTO,
-  /** JPEG format. */
-  JPEG,
-  /** PNG format. */
-  PNG,
-  /** BMP format. */
-  BMP,
-};
-
 /**
  * @brief A dynamic image that can be loaded and decoded at runtime.
  *
@@ -99,7 +85,7 @@ class RuntimeImage : public image::Image {
   /**
    * @brief Check if decoding is currently in progress.
    */
-  bool is_decoding() const { return this->decoder_ != nullptr; }
+  bool is_decoding() const { return this->decoder_ != nullptr && this->decoder_->is_active(); }
 
   /**
    * @brief Check if the decoder has finished processing all data.
@@ -120,9 +106,10 @@ class RuntimeImage : public image::Image {
   ImageFormat get_format() const { return this->format_; }
 
   /**
-   * @brief Release the image buffer and free memory.
+   * @brief Release the image buffer and free its memory, ending any decode session.
    *
-   * An external buffer is let go of rather than freed.
+   * An external buffer is let go of rather than freed. The decoder object is kept
+   * warm so the next decode can reuse it without churning the heap.
    */
   void release();
 
@@ -194,9 +181,11 @@ class RuntimeImage : public image::Image {
   int get_position_(int x, int y) const;
 
   /**
-   * @brief Create decoder instance for the image's format.
+   * @brief Create decoder instance for the requested format.
+   * @param format The image format to decode.
+   * @return Unique pointer to the created decoder, or nullptr on failure.
    */
-  std::unique_ptr<ImageDecoder> create_decoder_();
+  std::unique_ptr<ImageDecoder> create_decoder_(ImageFormat format);
 
   // Memory management
   uint8_t *buffer_{nullptr};
@@ -224,7 +213,6 @@ class RuntimeImage : public image::Image {
   int buffer_height_{0};
 
   // Decoding state
-  size_t total_size_{0};
   size_t decoded_bytes_{0};
 
   /** Fixed width requested on configuration, or 0 if not specified. */

esphome/components/sendspin/image/sendspin_image.cpp

@@ -86,8 +86,8 @@ void SendspinImageSlot::on_decode_(const uint8_t *data, size_t length) {
   }
 
   const bool decoded = this->decode_frame_(data, length, target);
-  // Drops any half-finished decoder. An external buffer is let go of rather than freed, so this is
-  // safe on every path.
+  // Ends any half-finished decode session (the decoder object is kept for reuse). An external
+  // buffer is let go of rather than freed, so this is safe on every path.
   this->decode_sink_.release();
 
   if (!decoded) {

tests/components/runtime_image/__init__.py

@@ -0,0 +1,15 @@
+from esphome.components.runtime_image import enable_format
+from esphome.types import ConfigType
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # to_code is suppressed in cpptest builds; formats are normally enabled by
+    # process_runtime_image_config(). Enable all formats so the format-switch
+    # tests have two decoder types and every retained decoder is under test.
+    async def to_code_testing(config: ConfigType) -> None:
+        enable_format("BMP")
+        enable_format("PNG")
+        enable_format("JPEG")
+
+    manifest.to_code = to_code_testing