firmware: double-buffer the panel + zero-copy decode → ~22 fps ceiling

Per-frame paint cost drops from ~24 ms to ~45 µs (≈500× faster) by
enabling num_fbs=2 on the DPI panel and decoding straight into the
back framebuffer. Measured on the bench:

  before: lock=7us ttfb=370us body=40ms dec=6ms paint=24ms post=35us = ~70ms / ~14fps
  after : lock=7us ttfb=330us body=38ms dec=6ms paint=42us  post=25us = ~45ms / ~22fps

How the win actually lands:
- num_fbs=2 in the esp_lcd_dpi_panel_config_t makes the IDF driver
  allocate two framebuffers and stream from one while we fill the
  other.
- display_back_buffer() returns the inactive fb pointer + its size.
- jpeg_decoder_decode() now accepts a caller-provided destination
  buffer instead of owning its own scratch. http_api passes the panel
  back-fb so the hardware JPEG decoder writes BGR888 pixels straight
  into where the DSI will eventually scan from. Zero memcpy in the
  hot path.
- display_flip_back_buffer() calls esp_lcd_panel_draw_bitmap with the
  fb pointer. Because the buffer is inside the panel's own fb range,
  the IDF driver skips its memcpy and just does a cache writeback +
  swaps cur_fb_index. The actual flip happens on the next vsync,
  asynchronously — the call returns in microseconds.

The remaining ceiling is network body time (~38 ms for ~210 KB JPEGs)
and the hardware decoder (~6 ms). Per-viewport JPEG quality (smaller
files = shorter body) is the next lever; everything firmware-side is
already at or near floor.

Also drop the old static jpeg output scratch + JPEG_DECODER_MAX_OUTPUT_BYTES
constant — nothing references them anymore.

5 files changed, 92 insertions, 35 deletions

diff --git a/main/display.c b/main/display.c
index 1acddba..ca1690e 100644
--- a/main/display.c
+++ b/main/display.c
@@ -117,8 +117,18 @@ static esp_lcd_dsi_bus_handle_t s_dsi_bus;
 static esp_lcd_panel_handle_t   s_panel;
 static bool                     s_up;
 static uint8_t                  s_last_pwm;
-// RGB888 panel-sized scratch buffer (800*480*3 ≈ 1.15 MB in PSRAM).
+// BGR888 panel-sized scratch buffer used by local_screens' CPU
+// conversion + rotation path (~1.15 MB in PSRAM). Hot /frame path
+// instead writes the JPEG decoder output directly into the panel's
+// double-buffered framebuffer (see s_panel_fbs).
 static uint8_t                 *s_rot_buf;
+// The DPI driver owns the two framebuffers when num_fbs = 2. We grab
+// pointers to both after panel_init and alternate which one we hand to
+// the JPEG decoder + the panel for each /frame. draw_bitmap with a
+// pointer that's inside one of these turns into a cache writeback +
+// index swap (microseconds), eliminating the previous ~24 ms memcpy.
+static uint8_t                 *s_panel_fbs[2];
+static int                      s_back_fb;     // index of the fb the next paint will fill
 
 // ============================================================================
 // ATTINY88 I2C helpers
@@ -304,7 +314,10 @@ static esp_err_t dsi_bring_up(void)
         .pixel_format       = LCD_COLOR_PIXEL_FORMAT_RGB888,
         .in_color_format    = LCD_COLOR_FMT_RGB888,
         .out_color_format   = LCD_COLOR_FMT_RGB888,
-        .num_fbs            = 1,
+        // Double-buffer the panel: the DSI engine streams one fb while
+        // we fill the other. esp_lcd_panel_draw_bitmap(fb) becomes a
+        // cache writeback + index swap (~µs) instead of a ~24 ms memcpy.
+        .num_fbs            = 2,
         .video_timing = {
             .h_size            = PANEL_H_ACTIVE,
             .v_size            = PANEL_V_ACTIVE,
@@ -337,6 +350,16 @@ static esp_err_t dsi_bring_up(void)
 
     ESP_RETURN_ON_ERROR(esp_lcd_panel_init(s_panel), TAG, "panel_init");
 
+    // Grab pointers to both framebuffers so we can hand them to the
+    // JPEG decoder as the direct decode destination — that triggers
+    // the IDF DPI driver's fast path in draw_bitmap (no memcpy).
+    void *fb0 = NULL, *fb1 = NULL;
+    ESP_RETURN_ON_ERROR(esp_lcd_dpi_panel_get_frame_buffer(s_panel, 2, &fb0, &fb1),
+                       TAG, "get_frame_buffer");
+    s_panel_fbs[0] = fb0;
+    s_panel_fbs[1] = fb1;
+    s_back_fb      = 1;   // fb0 is the one the driver shows first; we fill fb1 next
+
     // Continuous HS clock — TC358762's internal FLL needs a stable
     // reference, and we still allow LP data-lane blanking so command
     // packets can be inserted between frames.
@@ -437,6 +460,24 @@ esp_err_t display_present_bgr888(const void *bgr888)
                                      bgr888);
 }
 
+void *display_back_buffer(size_t *out_size)
+{
+    if (!s_up) return NULL;
+    if (out_size) *out_size = (size_t)PANEL_H_ACTIVE * PANEL_V_ACTIVE * 3;
+    return s_panel_fbs[s_back_fb];
+}
+
+esp_err_t display_flip_back_buffer(void)
+{
+    if (!s_up) return ESP_ERR_INVALID_STATE;
+    void *fb = s_panel_fbs[s_back_fb];
+    esp_err_t err = esp_lcd_panel_draw_bitmap(s_panel, 0, 0,
+                                              PANEL_H_ACTIVE, PANEL_V_ACTIVE,
+                                              fb);
+    if (err == ESP_OK) s_back_fb ^= 1;   // next /frame fills the other one
+    return err;
+}
+
 esp_err_t display_present_rgb565(const uint16_t *src,
                                  uint16_t        src_w,
                                  uint16_t        src_h)
diff --git a/main/display.h b/main/display.h
index 5f939b9..0ecff4d 100644
--- a/main/display.h
+++ b/main/display.h
@@ -43,4 +43,18 @@ esp_err_t display_present_rgb565(const uint16_t *src,
 // hand it straight to esp_lcd_panel_draw_bitmap. No CPU pixel work, no
 // format conversion, no rotation — Scrypted is responsible for sending
 // the buffer pre-rotated and pre-scaled to panel-native dimensions.
+// If the buffer happens to be one of the panel's own framebuffers
+// (see display_back_buffer / display_flip_back_buffer below), the IDF
+// driver skips the memcpy entirely; otherwise it copies via CPU.
 esp_err_t display_present_bgr888(const void *bgr888);
+
+// Double-buffer accessors for the zero-memcpy /frame path. The DPI
+// panel owns two BGR888 framebuffers; `display_back_buffer` hands back
+// the one that is NOT currently being streamed by the DSI engine so
+// callers (the JPEG decoder) can fill it in place. When the buffer is
+// ready, `display_flip_back_buffer` swaps it in — turns into a cache
+// writeback + index swap inside the IDF driver (no memcpy).
+//   `out_size` (if non-null) is set to the buffer's byte size, useful
+//   for passing to jpeg_decoder_process as its output capacity.
+void      *display_back_buffer(size_t *out_size);
+esp_err_t  display_flip_back_buffer(void);
diff --git a/main/http_api.c b/main/http_api.c
index c87b8dc..447cb52 100644
--- a/main/http_api.c
+++ b/main/http_api.c
@@ -365,9 +365,13 @@ static esp_err_t frame_post_handler(httpd_req_t *req)
 
     int64_t t_recv = esp_timer_get_time();
 
-    void   *rgb = NULL;
+    // Decode straight into the panel's back framebuffer — no scratch
+    // buffer, no later memcpy. The flip below is a cache writeback +
+    // index swap inside the IDF DPI driver.
+    size_t back_size = 0;
+    void *back = display_back_buffer(&back_size);
     uint16_t w = 0, h = 0;
-    esp_err_t dec_err = jpeg_decoder_decode(got, &rgb, &w, &h);
+    esp_err_t dec_err = jpeg_decoder_decode(got, back, back_size, &w, &h);
     int64_t t_decode = esp_timer_get_time();
     if (dec_err != ESP_OK) {
         viewport_state_lock();
@@ -392,7 +396,7 @@ static esp_err_t frame_post_handler(httpd_req_t *req)
         return respond_status(req, "400 Bad Request", msg);
     }
 
-    esp_err_t paint_err = display_present_bgr888(rgb);
+    esp_err_t paint_err = display_flip_back_buffer();
     int64_t t_paint = esp_timer_get_time();
     int64_t t_post  = 0;
     if (paint_err != ESP_OK) {
diff --git a/main/jpeg_decoder.c b/main/jpeg_decoder.c
index 2538f69..cbb98d8 100644
--- a/main/jpeg_decoder.c
+++ b/main/jpeg_decoder.c
@@ -14,8 +14,6 @@ static jpeg_decoder_handle_t s_engine;
 static SemaphoreHandle_t     s_mutex;
 static void   *s_in_buf;
 static size_t  s_in_cap;
-static void   *s_out_buf;
-static size_t  s_out_cap;
 
 esp_err_t jpeg_decoder_init(void)
 {
@@ -29,23 +27,18 @@ esp_err_t jpeg_decoder_init(void)
     ESP_RETURN_ON_ERROR(jpeg_new_decoder_engine(&cfg, &s_engine),
                        TAG, "jpeg_new_decoder_engine");
 
-    // DMA-aligned PSRAM scratch buffers. Allocate once, reuse.
+    // DMA-aligned PSRAM scratch buffer for the inbound JPEG body. The
+    // OUTPUT buffer is no longer owned here — callers pass in a target
+    // (the display back-buffer) so the decoder writes the BGR888 pixels
+    // straight into the panel framebuffer with no intermediate copy.
     jpeg_decode_memory_alloc_cfg_t in_cfg  = { .buffer_direction = JPEG_DEC_ALLOC_INPUT_BUFFER };
-    jpeg_decode_memory_alloc_cfg_t out_cfg = { .buffer_direction = JPEG_DEC_ALLOC_OUTPUT_BUFFER };
-
     s_in_buf = jpeg_alloc_decoder_mem(JPEG_DECODER_MAX_INPUT_BYTES,  &in_cfg,  &s_in_cap);
     if (!s_in_buf) {
         ESP_LOGE(TAG, "jpeg input buf alloc failed");
         return ESP_ERR_NO_MEM;
     }
-    s_out_buf = jpeg_alloc_decoder_mem(JPEG_DECODER_MAX_OUTPUT_BYTES, &out_cfg, &s_out_cap);
-    if (!s_out_buf) {
-        ESP_LOGE(TAG, "jpeg output buf alloc failed");
-        return ESP_ERR_NO_MEM;
-    }
 
-    ESP_LOGI(TAG, "decoder ready (in=%u bytes, out=%u bytes)",
-             (unsigned)s_in_cap, (unsigned)s_out_cap);
+    ESP_LOGI(TAG, "decoder ready (in=%u bytes)", (unsigned)s_in_cap);
     return ESP_OK;
 }
 
@@ -61,19 +54,20 @@ void jpeg_decoder_unlock(void)
 
 void *jpeg_decoder_input_buffer(void) { return s_in_buf; }
 
-esp_err_t jpeg_decoder_decode(size_t   jpeg_len,
-                              void   **out_bgr888,
+esp_err_t jpeg_decoder_decode(size_t    jpeg_len,
+                              void     *out_buf,
+                              size_t    out_cap,
                               uint16_t *out_width,
                               uint16_t *out_height)
 {
     if (jpeg_len == 0 || jpeg_len > s_in_cap) return ESP_ERR_INVALID_SIZE;
+    if (!out_buf || out_cap == 0)             return ESP_ERR_INVALID_ARG;
 
-    // Hardware decode directly into a panel-native BGR888 buffer.
-    // _BGR rgb_order swaps the channel layout so memory ends up as
-    // [B, G, R] per pixel — exactly what the ESP32-P4 DSI engine +
-    // TC358762 + Pi panel pipeline wants. Total firmware-side cost in
-    // the hot /frame path: this hardware decode + one DMA hand-off to
-    // the panel. No CPU pixel work.
+    // Hardware decode directly into the caller's BGR888 buffer (the
+    // panel back-framebuffer in the /frame path). _BGR rgb_order swaps
+    // the channel layout so memory ends up as [B, G, R] per pixel —
+    // exactly what the ESP32-P4 DSI engine + TC358762 + Pi panel
+    // pipeline wants. Zero firmware-side pixel work.
     jpeg_decode_cfg_t dec_cfg = {
         .output_format = JPEG_DECODE_OUT_FORMAT_RGB888,
         .rgb_order     = JPEG_DEC_RGB_ELEMENT_ORDER_BGR,
@@ -89,14 +83,13 @@ esp_err_t jpeg_decoder_decode(size_t   jpeg_len,
 
     uint32_t out_size = 0;
     err = jpeg_decoder_process(s_engine, &dec_cfg,
-                               s_in_buf,  jpeg_len,
-                               s_out_buf, s_out_cap, &out_size);
+                               s_in_buf, jpeg_len,
+                               out_buf,  out_cap, &out_size);
     if (err != ESP_OK) {
         ESP_LOGW(TAG, "jpeg_decoder_process: %s", esp_err_to_name(err));
         return err;
     }
 
-    *out_bgr888 = s_out_buf;
     *out_width  = info.width;
     *out_height = info.height;
     return ESP_OK;
diff --git a/main/jpeg_decoder.h b/main/jpeg_decoder.h
index 2ac436d..e8a8504 100644
--- a/main/jpeg_decoder.h
+++ b/main/jpeg_decoder.h
@@ -23,12 +23,17 @@ void jpeg_decoder_unlock(void);
 // JPEG_DECODER_MAX_INPUT_BYTES. Caller fills before calling decode.
 void *jpeg_decoder_input_buffer(void);
 
-// Decode the JPEG sitting in the input buffer. Fills out_bgr888 with a
-// pointer to the decoded 24-bit image (3 bytes/pixel, BGR memory order so
-// the DSI engine + TC358762 + Pi panel render channels correctly) and
-// reports the image's width/height in pixels. The output buffer is owned
-// by the decoder — valid only until the next jpeg_decoder_unlock().
-esp_err_t jpeg_decoder_decode(size_t   jpeg_len,
-                              void   **out_bgr888,
+// Decode the JPEG sitting in the input buffer into the caller-provided
+// out_buf (must be at least out_cap bytes, ≥ 800*480*3 for a full
+// panel-sized frame). Bytes land in BGR memory order so the DSI engine
+// + TC358762 + Pi panel render channels correctly. Reports image
+// width/height in pixels.
+//
+// In the /frame hot path the caller passes display_back_buffer() so
+// the hardware decoder writes pixels straight into the panel's back
+// framebuffer with zero intermediate copies.
+esp_err_t jpeg_decoder_decode(size_t    jpeg_len,
+                              void     *out_buf,
+                              size_t    out_cap,
                               uint16_t *out_width,
                               uint16_t *out_height);