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:
@@ -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
|
||||
```
|
||||
|
||||

|
||||
|
||||
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
|
||||
```
|
||||
|
||||

|
||||
|
||||
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 |
|
||||
|
||||
Reference in New Issue
Block a user