Andrew Kesterson
0972472cfa
Both examples gain --screenshot PATH and --screenshot-frame N. The capture sits between the world being drawn and the frame being presented, because SDL_RenderPresent is where the target stops being readable, and it works under the dummy video driver and the software renderer like the rest of the headless path does. `cmake --build build --target docs_game_figures` regenerates docs/images/sidescroller.png and docs/images/jrpg.png by running each game to a chosen frame. Same contract as docs_screenshots: deliberate, never part of a build, because the PNGs are tracked. There is no --check counterpart, and the target says why -- the sidescroller drives its physics from the wall clock, so a byte comparison would fail for reasons that have nothing to do with the documentation. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KzBDV2fqgnUAcqCKqKvc71
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 runmake. - Regenerate as a deliberate change, in the same commit as whatever moved the picture, so the binary diff is attributable.
ctest -R docs_screenshotsre-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_examplesfails 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.