From 880e86b3ab3d249c9a059ef581f02d8e0ea89088 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Fri, 20 Nov 2026 08:15:25 -0600 Subject: [PATCH] Bit World: pygraphics draws without returning an Area Bit World never reads the Area a pygraphics drawing call returns, so its pygraphics frames ask for none (FrameBuffer areas=False, pygraphics#104). On MicroPython that removes the garbage left by text, alpha glows and large copies. A pygraphics without the keyword returns them as before. On unix MicroPython with pygraphics#105, update, sound and repaint into two alternating 800x480 buffers allocate, per frame: Workshop 983 -> 498 bytes, Sky Ruins 587 -> 414, Cyber-Deck 762 -> 528. tests/repaint_check.py prints bad 0 at 800x480, and the CPython tests pass with the released pygraphics (the fallback) and with pygraphics#105. Refs #189 --- apps/bit_world/AGENTS.md | 2 +- apps/bit_world/act_deck.py | 2 +- apps/bit_world/bit_palette.py | 23 +++++++++++++++++------ 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/apps/bit_world/AGENTS.md b/apps/bit_world/AGENTS.md index acfc2d3..c8c72e1 100644 --- a/apps/bit_world/AGENTS.md +++ b/apps/bit_world/AGENTS.md @@ -9,5 +9,5 @@ - Tick callbacks take the timer argument (`def step(self, timer=None)`). Without it you get a black frame and a single traceback. - On a board whose panel gives out two scan-out buffers (`display_drv.share_framebuffer` with two entries from `framebuffers()`), the app draws straight into the back buffer and repaints only what moved: each act's `draw_changes` must give the same pixels as its `draw`. After changing an act, run `tests/repaint_check.py`; it compares the two frame by frame. - Never slice a panel's buffer from Python (`buf[a:b] = ...`): on an ESP32-S3 each row costs milliseconds. Copy rectangles with `FrameBuffer.blit`, as `restore_rects` does. -- Draw into frames from `make_fb` or `make_canvas`. On MicroPython they draw with the built-in framebuf, which allocates nothing, and send text, `text16`, `blit_alpha` and big copies to pygraphics, whose every call returns a new `Area`. A frame that allocates a few kilobytes collects every few seconds, and on an ESP32 with PSRAM a collection stops the picture for about 200 ms. Measure with `gc.mem_alloc()` around `update` and `draw_changes`, and keep text and tuples out of the per-frame path when their values haven't changed. +- Draw into frames from `make_fb` or `make_canvas`. On MicroPython they draw with the built-in framebuf, which allocates nothing, and send text, `text16`, `blit_alpha` and big copies to a pygraphics `FrameBuffer` made by `gfx_frame` with `areas=False`, so those return nothing either; a pygraphics without that keyword returns a new `Area` from each. A frame that allocates a few kilobytes collects every few seconds, and on an ESP32 with PSRAM a collection stops the picture for about 200 ms. Measure with `gc.mem_alloc()` around `update` and `draw_changes`, and keep text and tuples out of the per-frame path when their values haven't changed. - Keep what changes every frame in whole numbers: positions in fixed point, timers in milliseconds, repaint rectangles in reused arrays. On MicroPython every float result is a new heap object, and one particle's position, speed and life made three a frame. diff --git a/apps/bit_world/act_deck.py b/apps/bit_world/act_deck.py index 92f892b..219d4e5 100644 --- a/apps/bit_world/act_deck.py +++ b/apps/bit_world/act_deck.py @@ -183,7 +183,7 @@ def __init__(self, layout, sprites, sound, background=None): ) # The needles' hub, drawn once and then blitted with framebuf, which allocates - # nothing; pygraphics' circles return an Area each. + # nothing; a pygraphics without areas=False makes an Area for each circle. self._hub = make_canvas(bytearray(11 * 11 * 2), 11, 11) self._hub.fill(KEY) hub_draw = make_draw(self._hub) diff --git a/apps/bit_world/bit_palette.py b/apps/bit_world/bit_palette.py index 12fe64e..02b20c2 100644 --- a/apps/bit_world/bit_palette.py +++ b/apps/bit_world/bit_palette.py @@ -322,6 +322,17 @@ def draw_pixel_wipe(fb, x, y, w, h, progress, col_main=VOID, col_edge=CYAN): fb.fill_rect(bx, top_y - 3, bw, 3, col_edge) +# A pygraphics FrameBuffer over buf. Bit World never reads the Area a drawing call +# returns, so it asks for none: on MicroPython each one is a new object, and a frame +# of them is enough garbage to stop the picture for a collection. A pygraphics +# without areas= returns them anyway. +def gfx_frame(buf, w, h): + try: + return FrameBuffer(buf, w, h, RGB565, areas=False) + except TypeError: + return FrameBuffer(buf, w, h, RGB565) + + if framebuf is None: Canvas = None else: @@ -329,8 +340,8 @@ def draw_pixel_wipe(fb, x, y, w, h, progress, col_main=VOID, col_edge=CYAN): class Canvas(framebuf.FrameBuffer): """An RGB565 frame drawn with MicroPython's framebuf, which allocates nothing per call. - Each pygraphics drawing call returns a new ``Area``, and a frame makes a few - hundred of them: enough garbage for a collection every few seconds, which + A pygraphics without ``areas=False`` returns a new ``Area`` from each drawing + call, and a frame makes a few hundred of them: enough garbage for a collection every few seconds, which stops the picture for a fifth of a second on a board with a large heap. The calls framebuf lacks, and text, whose 8x8 font differs, go to a pygraphics ``FrameBuffer`` on the same memory, in ``gfx``. @@ -338,7 +349,7 @@ class Canvas(framebuf.FrameBuffer): def __init__(self, buf, w, h): super().__init__(buf, w, h, framebuf.RGB565) - self.gfx = FrameBuffer(buf, w, h, RGB565) + self.gfx = gfx_frame(buf, w, h) # Draw text in pygraphics' 8x8 font, which isn't framebuf's. def text(self, s, x, y, c): @@ -356,7 +367,7 @@ def blit_alpha(self, mask, x, y, w, h, c): # Wrap w x h RGB565 pixels in buf for drawing: a Canvas where framebuf exists. def make_canvas(buf, w, h): if Canvas is None: - return FrameBuffer(buf, w, h, RGB565) + return gfx_frame(buf, w, h) return Canvas(buf, w, h) @@ -402,8 +413,8 @@ def copy_frame(fb, src): # Rectangles up to this many pixels are copied by framebuf, which allocates nothing. -# Larger ones go to pygraphics, whose row copies are much faster but which returns -# a new Area for each. +# Larger ones go to pygraphics, whose row copies are much faster; a pygraphics without +# areas=False also makes a new Area for each. SMALL_COPY = 2048