# 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.