display: tear-free frame path via triple buffering + scan tracking

draw_bitmap on a direct fb pointer only updates the driver's
cur_fb_index; the DPI DMA reloads that index at the END of the
in-progress frame scan (~21ms period at ~47Hz). Under double
buffering, flipping and immediately decoding the next frame into
the other fb writes a buffer the DMA may still be scanning out —
a torn frame. This regime is common now that the TCP window fix
delivers frames back-to-back (decode starts ~6ms after flip).

Fix with zero added latency: num_fbs 2 -> 3 (+1.15MB PSRAM of 25MB
free), track the actually-scanning fb via on_refresh_done (fires in
the DMA-done ISR exactly when the DMA reloads cur_fb_index), and
pick the decode target as the fb that is neither pending display
nor scanning. Three buffers minus at most two excluded roles =
always a free one; no waiting on vsync anywhere.

Instrumented: /state tear_guard_engaged counts back-buffer picks
made while the previous fb was still mid-scan — each one is a
frame that would have torn under double buffering.

1 files changed, 13 insertions, 6 deletions

diff --git a/main/display.h b/main/display.h
index 0ecff4d..679a408 100644
--- a/main/display.h
+++ b/main/display.h
@@ -48,13 +48,20 @@ esp_err_t display_present_rgb565(const uint16_t *src,
 // 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).
+// Framebuffer accessors for the zero-memcpy frame path. The DPI panel
+// owns three BGR888 framebuffers (triple buffering): one scanning out,
+// one pending display at the next frame boundary, one free.
+// `display_back_buffer` hands back the free one — guaranteed not to be
+// touched by the DSI DMA — so callers (the JPEG decoder) can fill it in
+// place with no tear risk and no waiting. When the buffer is ready,
+// `display_flip_back_buffer` swaps it in — 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);
+
+// Count of back-buffer picks made while the previously-flipped fb was
+// still scanning out — i.e. frames that would have torn under the old
+// double-buffer scheme. Monotonic since boot; exposed via /state.
+uint32_t   display_tear_guard_engaged(void);