From f8b917a7ac58b3d96bd351b7e87ecb809e18ebe0 Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Wed, 18 Nov 2026 10:11:34 -0800 Subject: [PATCH 1/5] lvgl: run background tasks during display.refresh() An explicit refresh() renders on the VM thread, so audio buffers were not refilled until it returned. A playlist scroll on the Metro ESP32-P4 with the Pi Touch Display 2 ran audio at 0.67x speed. Run background tasks after each flushed chunk, like the legacy framebufferio path does since #11875. A paced frame callback that fires during that yield waits for the next frame instead of starting a nested render. Co-Authored-By: Claude Opus 5.5 --- shared-module/displayio/lvgl/Group.c | 5 ++++- shared-module/displayio/lvgl/lvgl_internal.h | 4 ++++ shared-module/framebufferio/lvgl/FramebufferDisplay.c | 11 +++++++++++ shared-module/framebufferio/lvgl/FramebufferDisplay.h | 3 +++ 4 files changed, 22 insertions(+), 1 deletion(-) diff --git a/shared-module/displayio/lvgl/Group.c b/shared-module/displayio/lvgl/Group.c index 70a4395321d..5ec4ea08650 100644 --- a/shared-module/displayio/lvgl/Group.c +++ b/shared-module/displayio/lvgl/Group.c @@ -50,6 +50,7 @@ static const lvgl_protocol_t *_layer_protocol(mp_obj_t *layer) { static displayio_group_t *cp_lvgl_root_group = NULL; static bool cp_lvgl_inited = false; +bool displayio_lvgl_refresh_yield = false; // The port lock is recursive. Keeping the recursion at the port instead of counting here matters // once LVGL renders on its own task: a shared depth counter would let the render task believe it @@ -201,7 +202,9 @@ void displayio_lvgl_refresh_unsafe_displays(void) { void displayio_lvgl_refresh_paced_displays(void) { #if CIRCUITPY_FRAMEBUFFERIO static bool refreshing = false; - if (refreshing) { + // An explicit display.refresh() runs background tasks while it renders. A frame callback + // queued among them must not start a nested render; it draws at the next frame instead. + if (refreshing || displayio_lvgl_refresh_yield) { return; } refreshing = true; diff --git a/shared-module/displayio/lvgl/lvgl_internal.h b/shared-module/displayio/lvgl/lvgl_internal.h index 3c5da8c4863..8facf95c06f 100644 --- a/shared-module/displayio/lvgl/lvgl_internal.h +++ b/shared-module/displayio/lvgl/lvgl_internal.h @@ -77,6 +77,10 @@ void displayio_lvgl_refresh_unsafe_displays(void); // LVGL lock. void displayio_lvgl_refresh_paced_displays(void); +// True while an explicit display.refresh() renders on the CircuitPython thread. Long +// render steps (TileGrid compose, display flush) run background tasks when it is set. +extern bool displayio_lvgl_refresh_yield; + // Attach/detach the compositor's root group. Implemented in lvgl/Group.c. NULL detach. void displayio_lvgl_set_root_group(displayio_group_t *group); diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.c b/shared-module/framebufferio/lvgl/FramebufferDisplay.c index 78eb2d5ae13..3d484923276 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.c +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.c @@ -212,6 +212,12 @@ static void framebufferio_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *are self->framebuffer_protocol->swapbuffers(self->framebuffer, self->lv_dirty_row_bitmask); memset(self->lv_dirty_row_bitmask, 0, self->lv_dirty_row_bitmask_size); lv_display_flush_ready(disp); + + // A refresh can take longer than the audio buffers last. Like the legacy + // framebufferio, let background tasks run between chunks of an explicit refresh. + if (self->lv_refresh_yield) { + RUN_BACKGROUND_TASKS; + } } @@ -268,6 +274,7 @@ void common_hal_framebufferio_framebufferdisplay_construct(framebufferio_framebu self->lv_dirty_row_bitmask_size = 0; self->lv_direct = false; self->lv_paced = false; + self->lv_refresh_yield = false; framebufferdisplay_construct_cleanup_t cleanup = { .self = self, .locked = false }; nlr_push_jump_callback(&cleanup.node, framebufferdisplay_construct_abort); self->framebuffer_protocol = mp_proto_get_or_throw(MP_QSTR_protocol_framebuffer, framebuffer); @@ -479,7 +486,11 @@ bool common_hal_framebufferio_framebufferdisplay_refresh(framebufferio_framebuff if (self->lv_display != NULL) { // The renderer refreshes on its own thread too, so this has to exclude it. displayio_lvgl_lock(); + self->lv_refresh_yield = true; + displayio_lvgl_refresh_yield = true; lv_refr_now(self->lv_display); + displayio_lvgl_refresh_yield = false; + self->lv_refresh_yield = false; displayio_lvgl_unlock(); } self->core.last_refresh = supervisor_ticks_ms64(); diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.h b/shared-module/framebufferio/lvgl/FramebufferDisplay.h index 639b4af317b..beb40af7170 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.h +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.h @@ -42,6 +42,9 @@ typedef struct { // The framebuffer reports frame boundaries, so this display renders on those instead of the // LVGL autorefresh tick. bool lv_paced; + // Set while display.refresh() renders on the CircuitPython thread, so the flush + // callback can run background tasks (audio, USB) between chunks. + bool lv_refresh_yield; } framebufferio_framebufferdisplay_obj_t; void framebufferio_framebufferdisplay_background(framebufferio_framebufferdisplay_obj_t *self); From 69f8917d52073e46a7433fc12c248eed04667dfd Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Wed, 18 Nov 2026 10:11:34 -0800 Subject: [PATCH 2/5] lvgl: yield between TileGrid compose batches during refresh() A full re-render of a large text grid is one flush chunk but can take longer than the I2S DMA buffers last. Run background tasks after each batch of 64 cells when called from an explicit refresh(). Co-Authored-By: Claude Opus 5.5 --- shared-module/displayio/lvgl/TileGrid.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/shared-module/displayio/lvgl/TileGrid.c b/shared-module/displayio/lvgl/TileGrid.c index 15cdab1db9c..eedf94ab8a7 100644 --- a/shared-module/displayio/lvgl/TileGrid.c +++ b/shared-module/displayio/lvgl/TileGrid.c @@ -910,6 +910,10 @@ static bool _compose(displayio_tilegrid_t *self, lv_area_t *dirty) { queued++; if (queued == DISPLAYIO_LVGL_COMPOSE_BATCH) { lv_canvas_finish_layer(self->lv_canvas, &layer); + // A big compose (a re-rendered text grid) can outlast the audio buffers. + if (displayio_lvgl_refresh_yield) { + RUN_BACKGROUND_TASKS; + } lv_canvas_init_layer(self->lv_canvas, &layer); queued = 0; } From 9475c9ba79e7e5160e922120c7a7effd2a6e767c Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Wed, 18 Nov 2026 10:11:34 -0800 Subject: [PATCH 3/5] lvgl: compose indexed TileGrid cells with a palette lookup For 1/2/4/8 bit bitmaps with a Palette, write cell pixels straight into the ARGB8888 or RGB565 canvas through a 256 entry lookup table instead of one lv_draw_image() per cell. Clear cells with memset rather than lv_draw_buf_clear(), which flushed the cache for whole rows each call. Framebuffer CRCs match the old path at both color depths. Co-Authored-By: Claude Opus 5.5 --- shared-module/displayio/lvgl/TileGrid.c | 94 ++++++++++++++++++++++++- 1 file changed, 93 insertions(+), 1 deletion(-) diff --git a/shared-module/displayio/lvgl/TileGrid.c b/shared-module/displayio/lvgl/TileGrid.c index eedf94ab8a7..82286a38ce4 100644 --- a/shared-module/displayio/lvgl/TileGrid.c +++ b/shared-module/displayio/lvgl/TileGrid.c @@ -822,6 +822,55 @@ static void _cell_display_area(displayio_tilegrid_t *self, uint32_t x, uint32_t // or dispatch each task, so drawing a long queue at once takes time with the square of its length. #define DISPLAYIO_LVGL_COMPOSE_BATCH 64 +// Fast compose for the common case: an indexed source (I1/I2/I4/I8) with a palette. Each +// cell is a straight palette lookup into the buffer, which is what lv_draw_image() of the cell +// onto a cleared buffer produces, without a draw task per cell. LVGL's per-task cost is tens of +// microseconds, which a 1500-cell text grid turns into 100+ ms per refresh. +typedef struct { + bool ok; + bool argb; + uint8_t bpp; + uint32_t lut32[256]; + uint16_t lut16[256]; +} _fast_compose_t; + +static void _fast_compose_init(displayio_tilegrid_t *self, _fast_compose_t *fc) { + fc->ok = false; + const lv_image_dsc_t *src = self->lv_src; + if (src != &self->lv_src_dsc || src == NULL || src->data == NULL || src->palette == NULL || + !LV_COLOR_FORMAT_IS_INDEXED(src->header.cf)) { + return; + } + lv_color_format_t dcf = self->lv_buf->header.cf; + if (dcf != LV_COLOR_FORMAT_ARGB8888 && dcf != LV_COLOR_FORMAT_RGB565) { + return; + } + fc->bpp = lv_color_format_get_bpp(src->header.cf); + if (fc->bpp != 1 && fc->bpp != 2 && fc->bpp != 4 && fc->bpp != 8) { + return; + } + fc->argb = dcf == LV_COLOR_FORMAT_ARGB8888; + uint32_t n = 1u << fc->bpp; + for (uint32_t i = 0; i < n; i++) { + lv_color32_t c = src->palette[i]; + if (fc->argb) { + memcpy(&fc->lut32[i], &c, sizeof(uint32_t)); + } else { + fc->lut16[i] = lv_color_to_u16(lv_color_make(c.red, c.green, c.blue)); + } + } + fc->ok = true; +} + +// lv_draw_buf_clear() without its cache write-back: the ESP handler syncs whole buffer rows per +// call, and _compose() writes back the union of the cells once at the end anyway. +static void _clear_cell_area(lv_draw_buf_t *buf, const lv_area_t *a) { + uint32_t bytes = (lv_area_get_width(a) * lv_color_format_get_bpp(buf->header.cf) + 7) >> 3; + for (int32_t y = a->y1; y <= a->y2; y++) { + lv_memzero(lv_draw_buf_goto_xy(buf, a->x1, y), bytes); + } +} + // Compose every cell that changed into the buffer. Returns false when nothing was drawn so the // caller can skip the invalidation. `dirty` comes back as the union of the composed cells, in // container coordinates. @@ -860,6 +909,42 @@ static bool _compose(displayio_tilegrid_t *self, lv_area_t *dirty) { uint32_t cells = _cell_count(self); uint32_t tiles_w = self->width_in_tiles; + _fast_compose_t fc; + _fast_compose_init(self, &fc); + if (fc.ok) { + // Write the fast cells directly, one pixel line across every changed cell of a tile + // row at a time. The loop below then only does the bookkeeping for these cells. + const lv_image_dsc_t *src = self->lv_src; + for (uint32_t cy = 0; cy < self->height_in_tiles; cy++) { + for (uint16_t y = 0; y < self->tile_height; y++) { + uint8_t *line = lv_draw_buf_goto_xy(self->lv_buf, 0, cy * self->tile_height + y); + for (uint32_t cx = 0; cx < tiles_w; cx++) { + uint32_t cell = cy * tiles_w + cx; + if (!full && !_cell_is_marked(self, cell)) { + continue; + } + uint16_t tile_index = _tile_index(self, cell); + if (tile_index == DISPLAYIO_TILEGRID_BLANK_TILE) { + continue; + } + uint16_t x0, y0; + _tile_origin(self, tile_index, &x0, &y0); + const uint8_t *row = src->data + (uint32_t)(y0 + y) * src->header.stride; + if (fc.argb) { + uint32_t *d = (uint32_t *)(void *)line + cx * self->tile_width; + for (uint16_t x = 0; x < self->tile_width; x++) { + d[x] = fc.lut32[_source_index(row, x0 + x, fc.bpp)]; + } + } else { + uint16_t *d = (uint16_t *)(void *)line + cx * self->tile_width; + for (uint16_t x = 0; x < self->tile_width; x++) { + d[x] = fc.lut16[_source_index(row, x0 + x, fc.bpp)]; + } + } + } + } + } + } for (uint32_t cell = 0; cell < cells; cell++) { if (!full && !_cell_is_marked(self, cell)) { continue; @@ -876,7 +961,13 @@ static bool _compose(displayio_tilegrid_t *self, lv_area_t *dirty) { // Start from transparent (ARGB8888) or black (RGB565): lv_draw_image() writes nothing // where the source is transparent, which is exactly where the hole has to stay. // ESP_LOGI(TAG, "clearing cell area %d,%d-%d,%d", cell_area.x1, cell_area.y1, cell_area.x2, cell_area.y2); - lv_draw_buf_clear(self->lv_buf, &cell_area); + if (fc.ok && self->lv_src->data != NULL && + _tile_index(self, cell) != DISPLAYIO_TILEGRID_BLANK_TILE) { + // pixels already written by the raster pass above + drawn_cell_area = cell_area; + goto cell_done; + } + _clear_cell_area(self->lv_buf, &cell_area); if (self->lv_src != NULL && self->lv_src->data != NULL) { uint16_t x0, y0; @@ -919,6 +1010,7 @@ static bool _compose(displayio_tilegrid_t *self, lv_area_t *dirty) { } } } + cell_done: _clear_cell(self, cell); lv_area_t cell_display; _cell_display_area(self, cx, cy, &cell_display); From 5a800a5b41440d8e2508c5515d731a7d6bf267f3 Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Wed, 18 Nov 2026 11:56:57 -0800 Subject: [PATCH 4/5] lvgl: don't render BusDisplays during a refresh() yield A BusDisplay auto-refresh queued while an explicit refresh() runs background tasks could start a nested lv_refr_now() in the middle of the framebuffer render. Skip it; it draws on the next tick, like the paced framebuffer displays. Co-Authored-By: Claude Opus 5.5 --- shared-module/displayio/lvgl/Group.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/shared-module/displayio/lvgl/Group.c b/shared-module/displayio/lvgl/Group.c index 5ec4ea08650..8580748d6e0 100644 --- a/shared-module/displayio/lvgl/Group.c +++ b/shared-module/displayio/lvgl/Group.c @@ -172,11 +172,12 @@ bool displayio_lvgl_auto_refresh(void) { // Render the displays that can't run on the render task. The guard keeps the proxy from // re-entering LVGL rendering if a background callback is processed while a refresh is already -// active on the CircuitPython thread. +// active on the CircuitPython thread, including an explicit display.refresh() that is running +// background tasks mid-render. void displayio_lvgl_refresh_unsafe_displays(void) { #if CIRCUITPY_BUSDISPLAY static bool refreshing = false; - if (refreshing) { + if (refreshing || displayio_lvgl_refresh_yield) { return; } refreshing = true; From 63e9866d3cbb5709d50173257ee939a64426d8a6 Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Wed, 18 Nov 2026 12:01:50 -0800 Subject: [PATCH 5/5] lvgl: use one flag for the refresh() yield The per-display lv_refresh_yield was always set together with the global displayio_lvgl_refresh_yield. The LVGL lock is held for the whole explicit refresh, so only that display's flush can see the global. Co-Authored-By: Claude Opus 5.5 --- shared-module/framebufferio/lvgl/FramebufferDisplay.c | 5 +---- shared-module/framebufferio/lvgl/FramebufferDisplay.h | 3 --- 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.c b/shared-module/framebufferio/lvgl/FramebufferDisplay.c index 3d484923276..ea685b1978d 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.c +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.c @@ -215,7 +215,7 @@ static void framebufferio_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *are // A refresh can take longer than the audio buffers last. Like the legacy // framebufferio, let background tasks run between chunks of an explicit refresh. - if (self->lv_refresh_yield) { + if (displayio_lvgl_refresh_yield) { RUN_BACKGROUND_TASKS; } } @@ -274,7 +274,6 @@ void common_hal_framebufferio_framebufferdisplay_construct(framebufferio_framebu self->lv_dirty_row_bitmask_size = 0; self->lv_direct = false; self->lv_paced = false; - self->lv_refresh_yield = false; framebufferdisplay_construct_cleanup_t cleanup = { .self = self, .locked = false }; nlr_push_jump_callback(&cleanup.node, framebufferdisplay_construct_abort); self->framebuffer_protocol = mp_proto_get_or_throw(MP_QSTR_protocol_framebuffer, framebuffer); @@ -486,11 +485,9 @@ bool common_hal_framebufferio_framebufferdisplay_refresh(framebufferio_framebuff if (self->lv_display != NULL) { // The renderer refreshes on its own thread too, so this has to exclude it. displayio_lvgl_lock(); - self->lv_refresh_yield = true; displayio_lvgl_refresh_yield = true; lv_refr_now(self->lv_display); displayio_lvgl_refresh_yield = false; - self->lv_refresh_yield = false; displayio_lvgl_unlock(); } self->core.last_refresh = supervisor_ticks_ms64(); diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.h b/shared-module/framebufferio/lvgl/FramebufferDisplay.h index beb40af7170..639b4af317b 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.h +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.h @@ -42,9 +42,6 @@ typedef struct { // The framebuffer reports frame boundaries, so this display renders on those instead of the // LVGL autorefresh tick. bool lv_paced; - // Set while display.refresh() renders on the CircuitPython thread, so the flush - // callback can run background tasks (audio, USB) between chunks. - bool lv_refresh_yield; } framebufferio_framebufferdisplay_obj_t; void framebufferio_framebufferdisplay_background(framebufferio_framebufferdisplay_obj_t *self);