Andrew Kesterson
8f848d80be
docs/22-ui.md covers the clay-backed UI: what clay owns against what libakgl owns, bring-up and the arena refusal contract, the frame bracket and where it sits in a real frame, the consumed-event rules (with the one-frame-stale hit test stated plainly), the three widgets, menus across keyboard, gamepad and mouse, writing raw CLAY() with an application-owned press edge, images and styles, and how layout errors surface from frame_end with a captured trace. Every listing is a checked block: one linked-and-run example with pinned output, eight excerpts quoting examples/uidemo and examples/jrpg/textbox.c, and the chapter figure is a frame out of uidemo via docs_game_figures. The chapter owes and pays the comparison the tutorials earn: the dialog widget's default style reproduces the JRPG textbox palette, the two listings sit side by side, and the trade is stated -- 125 lines you own completely against one call that costs you the subsystem. Neither is deprecated; chapter 21 keeps teaching the hand-rolled panel on purpose. The appendix moves to 23 (links in chapters 4, 5, 6, 7, 13 and the TOC updated) and gains the ui.h status cross-reference, the AKGL_UI_* limits table, and the new draw primitives' rows. Its status-band figures were stale at COUNT 5 / LIMIT 261 while the band already held six codes; now correct at 7 / 263. Chapter 4 gains AKGL_ERR_UI (262) in the excerpt, the table and the name list. Co-Authored-By: Claude Code (Claude Fable 5, claude-fable-5) <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.