Write down that a redraw has to fit inside one batch

"Drawing does not persist across frames; redraw it every frame" was the advice,
and it is not sufficient on its own. The host runs a fixed number of source
lines and then presents, and presenting discards the drawing buffer -- so a run
of drawing verbs longer than one budget is **torn**, not merely transient, and
an `SSHAPE` at the end of it captures only what was issued since the present,
over whatever the frame before left behind.

Measured against the standalone frontend's 256: after synchronising to a jiffy
edge, 220 lines of drawing survive a capture and 250 do not.

There is no fix available that does not change what a host owns -- the budget is
the host's and so is the present -- so this is documentation, in the three
places it belongs. Chapter 13 beside the note it qualifies, with the numbers.
Chapter 6 where `SSHAPE` is introduced, which is where a program meets it.
Chapter 14 from the step loop's side, naming `AKBASIC_FRONTEND_STEPS_PER_FRAME`
and explaining the one thing a script can do about it: `settime()` is called once
a frame, so `TI#` changes on the first step of a batch and nowhere else, and
spinning until it changes is the only frame synchronisation this dialect has.

**Untested, deliberately.** Reproducing it needs the real frontend, a clock and
a timing window, and a test that reproduced it would be reproducing a race.
Recorded in TODO.md rather than left looking like an oversight.

TODO.md section 9 item 5, struck as a documentation outcome.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-02 00:23:36 -04:00
parent c8b917d205
commit c3d9e91bbd
2 changed files with 24 additions and 2 deletions

View File

@@ -244,3 +244,11 @@ The graphics verbs draw straight to the renderer rather than into a display list
anything drawn is overwritten by the text layer on the next frame. A program that wants
its drawing to persist has to redraw it. This is recorded as a defect rather than a
design; see Chapter 13.
**A redraw also has to fit inside one batch.** The host runs a fixed number of source
lines and then presents, and presenting throws the drawing buffer away — so a run of
drawing verbs longer than one batch is torn rather than merely transient, and an
`SSHAPE` at the end of it captures only the part issued since the present. Watching
`TI#` change is how a program finds the boundary; Chapter 13 has the measured numbers and
[Chapter 18](18-tutorial-breakout-artwork.md#step-4-find-the-frame-boundary) has a
routine that uses them.