picogame: optional Framebuffer.sync hook for tear-free full repaints

Framebuffer gains a settable `sync` attribute: an optional 0-arg callable that
Scene.refresh() invokes on the framebuffer path BEFORE compositing a large
(>= half-screen) region - e.g. a camera move that repaints most of the frame.
Small sprite-only dirty rects skip it, so per-frame latency is unaffected.

This decouples the engine from any specific backend (the plan's guidance): the
platform supplies the callable - on Fruit Jam picogame_game.setup() wires it to
picodvi Framebuffer.wait_for_vblank(), so a full repaint starts at the DVI frame
boundary and races ahead of scanout instead of tearing mid-screen. None = off
(SPI panels, sim, older firmware). Addresses the reported camera-move tearing;
pairs with the picodvi wait_for_vblank() primitive.

Author: lynt-smitka

shared-bindings/picogame/Scene.c

@@ -422,6 +422,20 @@ static mp_obj_t scene_refresh_fb(picogame_scene_obj_t *self) {
     // Snapshots are already advanced; stay in the needs-full-repaint state until the
     // render completes, so a BaseException mid-render (Ctrl-C in a StripDraw) leaves a
     // scene whose NEXT refresh repaints everything instead of keeping a torn frame.
+    // Before compositing a LARGE region (e.g. a camera move that repaints most of the frame),
+    // invoke the framebuffer's optional sync hook (e.g. picodvi wait_for_vblank) so the repaint
+    // starts at a frame boundary and races ahead of scanout instead of tearing mid-screen. Small
+    // sprite-only dirty rects skip it - the wait would only add latency with nothing to tear.
+    if (fbt->sync != mp_const_none) {
+        int area = 0;
+        for (int i = 0; i < nr; i++) {
+            area += (rects[i].x2 - rects[i].x1) * (rects[i].y2 - rects[i].y1);
+        }
+        if (area * 2 >= w * h) {       // >= half the screen -> treat as a full repaint
+            mp_call_function_0(fbt->sync);
+        }
+    }
+
     self->cleared = false;
     for (int i = 0; i < nr; i++) {
         mp_obj_t exc = picogame_render_framebuffer(fbt->fb, fbt->width, fbt->height, fbt->native_rgb565,

shared-bindings/picogame/__init__.c

@@ -1400,6 +1400,7 @@ static mp_obj_t picogame_framebuffer_make_new(const mp_obj_type_t *type, size_t
     self->width = width;
     self->height = height;
     self->native_rgb565 = args[ARG_native_rgb565].u_bool;
+    self->sync = mp_const_none;
     return MP_OBJ_FROM_PTR(self);
 }
 
@@ -1415,9 +1416,27 @@ static mp_obj_t picogame_framebuffer_get_height(mp_obj_t self_in) {
 static MP_DEFINE_CONST_FUN_OBJ_1(picogame_framebuffer_get_height_obj, picogame_framebuffer_get_height);
 MP_PROPERTY_GETTER(picogame_framebuffer_height_obj, (mp_obj_t)&picogame_framebuffer_get_height_obj);
 
+//|     sync: Optional[Callable[[], None]]
+//|     """An optional 0-arg callable invoked right before a large/full-screen region is
+//|     composited (e.g. a picodvi ``Framebuffer.wait_for_vblank``). Lets a full repaint start at a
+//|     frame boundary so it does not tear, with no cost on small (sprite-only) frames. ``None`` = off."""
+static mp_obj_t picogame_framebuffer_get_sync(mp_obj_t self_in) {
+    return ((picogame_framebuffer_obj_t *)MP_OBJ_TO_PTR(self_in))->sync;
+}
+static MP_DEFINE_CONST_FUN_OBJ_1(picogame_framebuffer_get_sync_obj, picogame_framebuffer_get_sync);
+static mp_obj_t picogame_framebuffer_set_sync(mp_obj_t self_in, mp_obj_t value) {
+    ((picogame_framebuffer_obj_t *)MP_OBJ_TO_PTR(self_in))->sync = value;
+    return mp_const_none;
+}
+static MP_DEFINE_CONST_FUN_OBJ_2(picogame_framebuffer_set_sync_obj, picogame_framebuffer_set_sync);
+MP_PROPERTY_GETSET(picogame_framebuffer_sync_obj,
+    (mp_obj_t)&picogame_framebuffer_get_sync_obj,
+    (mp_obj_t)&picogame_framebuffer_set_sync_obj);
+
 static const mp_rom_map_elem_t picogame_framebuffer_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_width), MP_ROM_PTR(&picogame_framebuffer_width_obj) },
     { MP_ROM_QSTR(MP_QSTR_height), MP_ROM_PTR(&picogame_framebuffer_height_obj) },
+    { MP_ROM_QSTR(MP_QSTR_sync), MP_ROM_PTR(&picogame_framebuffer_sync_obj) },
 };
 static MP_DEFINE_CONST_DICT(picogame_framebuffer_locals_dict, picogame_framebuffer_locals_dict_table);
 

shared-module/picogame/__init__.h

@@ -178,6 +178,9 @@ typedef struct {
     int height;
     bool native_rgb565;  // false = wire-order (default); true = each finished region is
                          // byte-swapped to NATIVE RGB565 (picodvi / canvas scanout targets)
+    mp_obj_t sync;       // optional 0-arg callable, invoked BEFORE compositing a large/full-screen
+                         // region (e.g. picodvi Framebuffer.wait_for_vblank) so a full repaint
+                         // starts at a frame boundary and does not tear; mp_const_none = no sync
 } picogame_framebuffer_obj_t;
 
 // Full-frame RAM-framebuffer backend: same layered compositor as the SPI strip path