From 659da7f36473a21494693f031a39fb6bb977b90a Mon Sep 17 00:00:00 2001 From: Luke Hoersten Date: Wed, 15 Jul 2026 19:10:57 -0500 Subject: display: tear-free frame path via triple buffering + scan tracking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- main/display.h | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'main/display.h') 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); -- cgit v1.2.3