From de54fc879a9eb733606bb0711d4082f51c521918 Mon Sep 17 00:00:00 2001 From: Chuck <33324927+ChuckBuilds@users.noreply.github.com> Date: Thu, 24 Sep 2026 14:27:37 -0400 Subject: [PATCH] docs(offscreen): the two GIL experiments, and what each can and cannot cover Co-Authored-By: Claude Opus 5.5 --- docs/OFFSCREEN_RENDERING.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/OFFSCREEN_RENDERING.md b/docs/OFFSCREEN_RENDERING.md index ac43ddcb..c0f64f39 100644 --- a/docs/OFFSCREEN_RENDERING.md +++ b/docs/OFFSCREEN_RENDERING.md @@ -284,9 +284,20 @@ updates are disabled while sync is active. removes the pauses, but the work still needs the GIL. Pillow drawing holds it, and a waiting thread only gets it back after the switch interval (default 5 ms). Expect some single-refresh late frames while a prefetch - runs. Measure with the soak. Lowering `sys.setswitchinterval` during Vegas - (e.g. 1 ms) is a one-line experiment, and a render process separate from - plugin work is the structural answer (the "native presenter" step). + runs. Measure with the soak. A render process separate from plugin work + is the structural answer (the "native presenter" step). Two opt-in + experiments try to get most of the way first, both off by default until + the soak says otherwise: + - `vegas_scroll.switch_interval_ms` lowers the switch interval for a Vegas + run (1 ms is the obvious try), so the render thread waits at most that + long behind bytecode. It does nothing for a C call that keeps the GIL. + - `vegas_scroll.prefetch_gate` (`src/common/render_gate.py`) lets the + prefetch thread run Python only while the render thread is blocked in + `SwapOnVSync`, up to just before the refresh the swap returns on, and + parks it the rest of the time. That covers C calls too, since the gate is + checked before each one starts. It never parks the thread while it holds + a lock the render thread takes, and never for more than 50 ms. It needs + the rebuilt binding, which releases the GIL during the swap. ## What this does not fix