[Alaining]

Why is this PR needed: with one frame buffer, every Tab5 redraw is copied into the image the panel is sending, so the UI tears. The current code can't fix this:

• the BSP hard-codes num_fbs = 1;
• it doesn't expose the frame buffers;
• espp's Display only renders in PARTIAL mode, copying from its own draw buffers.

Description

Optional tear-free LVGL rendering on the Tab5, for the cost of one extra frame buffer. Off by
default: the default build behaves exactly as before.

Stacked on #738.

• CONFIG_M5STACK_TAB5_DPI_NUM_FBS (1-3, default 1).
• initialize_display({.render_to_frame_buffers = true}) (default false): LVGL draws into the
  frame buffer that is not on screen. The flush switches the panel to it, then waits for the panel's
  frame-done event before LVGL draws again.
• frame_buffers() for applications with their own renderer.
• Example: a menuconfig option (default off) turns it on.
• Not available in this mode: display rotation. On ESP-IDF v6.0.0, DMA2D is off with 2+ buffers.

Motivation and Context

Measured with the m5stack-tab5 example on a Tab5 (ST7123, ESP-IDF v6.0.0), BSP default draw
buffers, with the same LVGL loop in both builds:

	main	this PR (enabled)
Frame buffers	1	2
Tearing (moving-bar test)	yes	✅ none
Free PSRAM	19.0 MB	⚠️ 17.8 MB (-1.2 MB)
Small updates	57 FPS	✅ 56 FPS (same)
Full-screen redraw	10 FPS	✅ 25 FPS
Continuous animation	52 FPS	⚠️ 29 FPS

• Cost: one extra frame buffer (1.8 MB), partly offset because LVGL's separate draw buffers are no
  longer needed. Net: 1.2 MB.
• Trade-off: a frame that takes longer than one panel refresh (17 ms) to draw waits for the next
  refresh. Heavy animations therefore run at half the panel rate (29 FPS) instead of tearing.

How has this been tested?

• The example builds for esp32p4 with ESP-IDF v6.0.0, default and enabled: no new warnings,
  clang-format clean.
• On a Tab5 (ST7123): tearing check, PSRAM, FPS per phase, touch. Default config behaves the same
  as the base.
• Our application, rendering into 2 buffers with its own flush, passes its hardware bench.
• Not tested: the ILI9881 / ST7121 panels, ESP-IDF v6.0.3 / v6.1.

Types of changes

• New feature (non-breaking change which adds functionality)
• Software change

🤖 Generated with Claude Code

[Alaining]

@finger563 could you take a look when you have a moment? This adds multiple DPI frame buffers to the Tab5 BSP and is stacked on #738 (details in my comment there: #738 (comment)). It's a draft until #738 lands; the default config behaves exactly as #738 alone. Thanks!

[finger563]

Hardware results on a Tab5 (ST71xx panel, ESP-IDF v6.1)

Measured with a small display benchmark added locally to the m5stack-tab5 example. It runs before the GUI starts, sets LVGL's refresh timer to 1 ms, and runs each phase for 8 s at 0° and again at 90°:

• small: a counter label changes every frame;
• full: the whole screen changes colour every frame;
• bar: a full-height bar sweeps across the screen (tearing check);
• heavy: 24 gradient boxes move every frame.

DSI underruns were counted from the driver's "underrun happens" log lines. These are single runs. Branches tested: espp main (base), #738, and #847, both PRs with main merged in locally (see the note below).

Phase	base 0°	base 90°	#738 0°	#738 90°	#847 (1 FB) 0°	#847 (1 FB) 90°	#847 (2 FBs, direct) 0°
full	25.0 fps	10.1 fps	35.9 fps	13.1 fps	35.9 fps	13.1 fps	57.8 fps
heavy	14.8 fps	7.9 fps	18.2 fps	9.7 fps	18.2 fps	9.7 fps	19.2 fps
bar	181 fps	167 fps	283 fps	224 fps	283 fps	224 fps	57.7 fps
small	996 fps	1000 fps	1000 fps	1000 fps	1000 fps	1000 fps	57.7 fps
DSI underruns	0	0	0	0	0	0	0
PSRAM free at start	24.5 MB		24.5 MB		24.5 MB		28.3 MB

small and bar above about 58 fps only show how fast LVGL renders and flushes a small dirty area; the panel refreshes at about 58 Hz. In 2-FB direct mode each frame waits for a panel refresh, so those phases cap at the panel rate. The 2-FB mode can't rotate, so it has no 90° column. Its 3.7 MB of extra free PSRAM is because the example's full-frame LVGL draw buffers aren't needed in that mode.

Takeaways:

• fix(m5stack-tab5): rotation audit, experimental opt-in ST7121 panel rotation (default off), and DSI underrun fixes #738: DMA2D gives about 45% faster full redraws at 0° and about 30% at 90°, with no underruns and no colour problems. The camera, colours and touch look right.
• feat(m5stack-tab5): tear-free rendering with two DPI frame buffers #847 with 1 FB performs identically to fix(m5stack-tab5): rotation audit, experimental opt-in ST7121 panel rotation (default off), and DSI underrun fixes #738.
• feat(m5stack-tab5): tear-free rendering with two DPI frame buffers #847 with 2 FBs: no tearing in the bar phase, and full redraws run at the panel rate. Rotation does nothing in that mode, as documented. Rotation, touch and the camera tab work at every rotation with 1 FB.
• Rotated flushes are much slower than unrotated ones: about 76 ms per full frame through the PPA, against 28 ms without rotation (about 100 ms on main). We're looking into the PPA path next.
• Not tested: ILI9881 and ST7121, and the opt-in ST7121 hardware rotation.

Build note: neither PR builds as-is on ESP-IDF v6.1. v6.1 added esp_lcd_dpi_panel_event_callbacks_t::on_vsync, so the designated initializer in video.cpp (cbs = {.on_color_trans_done = ..., .on_refresh_done = nullptr}) fails with -Werror=missing-field-initializers. main already zero-initializes the struct and assigns the callbacks. Rebasing onto main fixes it; the only conflict is that initializer, and keeping main's form plus the PRs' additions resolves it. The rebase also brings in BSP APIs that downstream users rely on (touch_state(), touch_state_convert(), sdcard_component()).

🤖 Generated with Claude Code