Generate the documentation's figures from the listings they illustrate

Chapters 6 and 8 described what a verb draws in prose. Eight figures now show
it, and each one is produced by running the BASIC listing printed immediately
above it -- so a picture cannot drift away from the code beside it, which is the
way a screenshot goes wrong and the way nothing notices.

tools/screenshot.c is a second SDL host, much smaller than the frontend: dummy
video driver, software renderer, run to completion, read the target back, write
a PNG. It draws no text layer on purpose, so a READY in the corner is not noise
in a figure about BOX and no font has to be resolved.

tools/docs_screenshots.sh reads the new screenshot=NAME fence tag straight out
of the markdown. size=WxH is the second tag, and SCALE's figure uses it: the
point being made is a 320x200 listing filling a larger window, which cannot be
made on a 320x200 surface.

Two gates, answering different questions. docs_examples fails a tagged block
with no image, in both configurations, so a figure cannot be added and
forgotten. docs_screenshots -- a CTest, AKGL build only -- re-renders every
figure and compares byte for byte, so a listing edited without regenerating
fails. Only the second catches a stale picture.

The PNGs are checked in because a reader on the forge has no build tree, and
docs/images/README.md says loudly that they are generated. Regenerating is never
part of a build: the target is run deliberately, so a make cannot put eight
binary diffs in front of whoever ran it.

Drawing the BOX figure caught a defect in TODO.md itself. Deviation 16 claimed
in bold that BOX fills on a negative angle while its own paragraph said the fill
was filed rather than implemented. BOX cannot fill, and filled_rect is reached
by no verb as a result.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-01 07:37:04 -04:00
parent 737fdc760f
commit 16b38c1138
18 changed files with 759 additions and 40 deletions

View File

@@ -58,12 +58,33 @@ operation.
## Showing and moving
```basic requires=akgl setup=ship
10 SPRSAV "ship.png", 1
20 SPRITE 1, 1, 3
30 MOVSPR 1, 100, 50
```basic requires=akgl screenshot=sprites
10 COLOR 1, 2
20 CIRCLE 1, 20, 20, 18, 18
30 PAINT 1, 20, 20
40 SSHAPE A$, 0, 0, 40, 40
50 GRAPHIC 1, 1
60 FOR N# = 1 TO 3
70 SPRSAV A$, N#
80 NEXT N#
90 SPRITE 1, 1
100 SPRITE 2, 1, 6
110 SPRITE 3, 1, 8, 0, 1, 1
120 MOVSPR 1, 30, 80
130 MOVSPR 2, 110, 80
140 MOVSPR 3, 190, 60
```
![](images/sprites.png)
Three sprites from one drawing: the first in the default colour, the second in colour
6, and the third in colour 8 with both expansion bits set, which is what makes it twice
the size. `GRAPHIC 1, 1` on line 50 wipes the drawing the sprites were captured from —
the picture would otherwise still show the original disc in the top-left corner.
**A sprite's colour multiplies the artwork rather than replacing it**, so a white disc
takes the colour cleanly and a coloured one comes out darker than you asked for.
`SPRITE n [,on] [,colour] [,priority] [,xexpand] [,yexpand] [,multicolour]`. Only the
number is required and **an argument you leave out is left alone**, so `SPRITE 1, 1`
turns sprite 1 on without disturbing its colour.
@@ -113,6 +134,27 @@ Only type 1, sprite-to-sprite, is implemented. Types 2 and 3 are refused by name
Collision is by bounding box, not by pixel: two sprites whose boxes overlap but whose
artwork does not are reported as colliding.
```basic requires=akgl screenshot=sprite-collision
10 COLOR 1, 2
20 CIRCLE 1, 20, 20, 14, 14
30 PAINT 1, 20, 20
40 BOX 1, 0, 0, 40, 40
50 SSHAPE A$, 0, 0, 40, 40
60 GRAPHIC 1, 1
70 SPRSAV A$, 1
80 SPRSAV A$, 2
90 SPRITE 1, 1, 6
100 SPRITE 2, 1, 3
110 MOVSPR 1, 110, 55
120 MOVSPR 2, 145, 90
```
![](images/sprite-collision.png)
The artwork here includes a border around the whole 40 by 40 sprite, so each sprite
draws its own bounding box. Those boxes overlap at one corner and the two discs are
nowhere near each other — and `BUMP(1)` reports a collision.
## Reading state back
| Function | Gives |