41 lines
2.4 KiB
Markdown
41 lines
2.4 KiB
Markdown
|
# The figures in this directory are generated, and are tracked deliberately
|
||
|
|
|
||
|
|
Every `.png` beside this file is **output**, not art. Each one is rendered by
|
||
|
|
`tools/docs_screenshots.sh` from a ```` ```c screenshot=NAME ```` block in a
|
||
|
|
chapter — the same code the reader is looking at, compiled against
|
||
|
|
`tools/docs_screenshot.c`, run headless, and read back off the render target.
|
||
|
|
|
||
|
|
They are committed to the repository **on purpose**: a reader looking at the
|
||
|
|
manual on the forge has no build tree, and a chapter whose figures only exist
|
||
|
|
after `cmake --build` renders as a page of broken images. This is the same
|
||
|
|
tracked-generated-artifact contract `AGENTS.md` spells out for
|
||
|
|
`include/akgl/SDL_GameControllerDB.h`. Do not delete them, do not add them to
|
||
|
|
`.gitignore`, and do not "clean up" the fact that generated files are tracked.
|
||
|
|
|
||
|
|
Working rules:
|
||
|
|
|
||
|
|
- **Never hand-edit one, and never replace one with a hand-taken screenshot.**
|
||
|
|
The whole point of the arrangement is that the picture follows the code. A
|
||
|
|
figure that was retouched is a figure that has stopped being of the listing
|
||
|
|
beside it, silently — which is exactly the failure this replaced.
|
||
|
|
- **An ordinary build does not touch them.** Regeneration is
|
||
|
|
`cmake --build build --target docs_screenshots`, and nothing else runs the
|
||
|
|
script. A build that quietly rewrote eight binaries would put that diff in
|
||
|
|
front of whoever happened to run `make`.
|
||
|
|
- **Regenerate as a deliberate change**, in the same commit as whatever moved
|
||
|
|
the picture, so the binary diff is attributable.
|
||
|
|
- **`ctest -R docs_screenshots` re-renders every figure and compares it byte for
|
||
|
|
byte**, into a scratch directory. It never repairs what it finds: a test that
|
||
|
|
fixes what it is measuring passes the second time for the wrong reason.
|
||
|
|
- **`ctest -R docs_examples` fails a tagged block with no image here**, so a new
|
||
|
|
figure cannot be added to a chapter and then forgotten.
|
||
|
|
|
||
|
|
A byte comparison of a rendered PNG is a deliberate bet: that the dummy video
|
||
|
|
driver and the software renderer are reproducible run to run and build to build.
|
||
|
|
They are. What that does not cover is an SDL upgrade shifting one pixel of a
|
||
|
|
diagonal — and the answer to that is to regenerate the figures in the same
|
||
|
|
commit as the bump, not to weaken the check to a size comparison that would pass
|
||
|
|
for every wrong picture of the right dimensions.
|
||
|
|
|
||
|
|
See `docs/MAINTENANCE.md` for the fence tags and the rest of the harness.
|