From 165bb6c1344b98de7bef1d3c2b72147b4a40797a Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 16:05:20 -0300 Subject: canim: the renderer speaks the design language The blocks, their states and the tokens carry the catalogue's names: atoms in ui, chain/reg/slot in rows, insn with its line column, jump lane and annotations (read, write, taken or not, a call with its arguments, a return, a syscall) in disasm, bytes and hexdump with field paper and the reading column, the three splits and relayout in stage, the ties (thread, link and pin, projection, echo). A lens is a band over the whole context, its drawing left and its bytes right. Frames' spans on the stack, each instruction's line and a callee's parameter count come from the tracer. A gallery scene draws every block; the test compares six of its pages with pictures kept in test/gallery, drawn from a recording kept there too. The scenes are ported; the motion checks report no pop and no metronome in any of them. Co-Authored-By: Claude Fable 5.2 --- anim/README.md | 161 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 98 insertions(+), 63 deletions(-) (limited to 'anim/README.md') diff --git a/anim/README.md b/anim/README.md index 9878765..74596bb 100644 --- a/anim/README.md +++ b/anim/README.md @@ -2,29 +2,26 @@ Animations of how a program ran, from a `ztrace` recording, on sketchbook's `anim` (live scenes). The frame is a debugger's whole context, as pwndbg -shows it, with one lens beside it; how it looks is `../design/README.md` -(revision 2) and how it moves is `../design/motion.md`. - -**State of this tree: mid-change, handed over.** The motion model (a step as -a sentence) and the context frame are in and every scene builds and runs; -the look was not checked against the design's mocks after the last round of -changes, and the scripted tests only check that scenes run. See "What is -not done" at the end. +shows it, with one lens over it; the names, sizes and colours of everything +in it are the design language's catalogue (`../design/README.md`), and how +it moves is `../design/motion.md`. Code and design share one set of names: +a block of the catalogue is a function or a component of the same name here. ```sh zig build record # the recordings, into zig-out/recordings zig build run -Dscene=fib # a scene in a window, hot reload (zig build lib --watch) zig build export -Dscene=fib -- DIR --fps 60 --size 1920x1080 # frames as PNGs (or - for raw RGBA) zig build videos -Doptimize=ReleaseFast # every scene: out/NAME-1080.mp4 and out/NAME-2160.mp4 (x264, 60 fps) -zig build test # unit tests, and each scene run headless +zig build test # unit tests, each scene run headless, and the gallery against its pictures +zig build gallery # the gallery's pictures drawn anew into test/gallery zig build bench # what a recording costs a frame zig build bench -- NAME BY [FUNCTION] # a recording's steps (BY: moment, line, over), with what each changed python3 tools/chart.py chart out/fib-1080.mp4 --out out/motion/fib # the designer's timing chart and five checks ``` -Needs what sketchbook and ztrace need, and `setarch`, `clang++` and -`llvm-config` (the pass plugin), `ffmpeg` (videos), python with numpy and -Pillow (charts). Dependencies are by path (`..` is ztrace, `../../sketchbook`, +Needs what sketchbook and ztrace need, and `setarch`, `clang` (the pass +plugin), `ffmpeg` (videos), python with numpy and Pillow (charts). +Dependencies are by path (`..` is ztrace, `../../sketchbook`, `../../02-pardes-code`); `zig-pkg` is a symlink to pardes's. ## A scene @@ -39,88 +36,126 @@ pub const scene = anim.Live(frame, struct {}); fn frame(s: *anim.Frame) void { const rec = canim.open(recordings.steps); // a recording the build made and embedded - const split = canim.layout.split.beside; // how the program column is shared var at = canim.cursor(s, rec, rec.lineMoment(10, rec.call("main", 0).enter)); - at.levels = .{ .idea = .calls, .source_rows = 8 }; // what a step is timed by + at.levels = .{ .idea = .calls, .source_rows = 10 }; // what a step is timed by at.journey(.line, rec.call("fib", 0).exit.?); // the clock's whole way - const ctx = canim.context(s, at, .{ .split = split }); // source, disassembly, registers, stack, backtrace, clock - const tree = canim.callTree(s, .{ .cursor = at, .box = split.lens, .function = "fib", .focus = true }); - const joins = canim.ties(s, .{ .cursor = at }); // connections between panes; add it last + // The stage: the band (the lens) over the program column and the state column. + const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject }); + const tree = canim.callTree(s, .{ .cursor = at, .stage = ctx.stage, .function = "fib" }); + const joins = ctx.ties(s); // thread, link, projection; add it last var says: canim.Narrator = .{}; - canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, tree, joins }); + canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, tree, joins }); says.line(s, "`fib` calls itself."); // old caption out, a gap, new one in, then stillness at.walk(s, .line, rec.lineMoment(6, rec.call("fib", 0).enter)); // each step in full, timed by its content at.hurry(s, .line, rec.call("fib", 4).enter, .{}); // a run: ramps in and out, counted on the clock - at.hurry(s, .line, rec.call("fib", 10).exit.?, .{ .pace = canim.theme.time.sprint }); + ctx.stage.relayout(s, canim.layout.split.none); // a change of split, 48 f s.wait(canim.theme.time.before_cut); } ``` `frame` runs every frame and builds the whole timeline each time; a component is an `anim` object (`fadeIn`, `fadeOut`) that draws the program's -state at the cursor. +state at the cursor, at the box its `Stage` gives it now. **The cursor** (`src/cursor.zig`) moves in steps from one moment straight to a later one (`Recording.Stop`: `.moment`, `.line`, `.over`, `.call`, -`.syscall`). For each step it writes a timetable, a `Plan`: the line fires -(0.20 s); each level the step touched strikes 0.30 s after the one before, in -the order CPU, memory, idea (a level the scene does not show, or the step did -not touch, gives up its slot); a hold to read; the mark advances last; a rest. -`walk` plays steps in full, `hurry` ramps the pace down and up again (each -step 0.6 of the one before) to a run (0.30 s a step) or a sprint, `step` -takes an explicit `Plan` (`Array.swap`, `syscalls.step`). Components read it -through `Cursor.now(at)`: `landed(level)`, `shown(level)`, `written(addr, -size, level, delay)`, `register(i, delay)`, `reading(level)`, `moving(level, -lead, seconds)`, `fires(view)`, `advancing()`, `marks`. +`.syscall`). For each step it writes a timetable, a `Plan`: the cascade. +The line fires (12 f); each level the step touched strikes 18 f after the one +before, in the order CPU, memory, idea (a level the scene does not show, or +the step did not touch, gives up its slot; a drawing made of bytes strikes +when the projection from them arrives, 24 f after them, and its write 12 f +later still); the writes of one step strike 6 f apart; a hold to read; the +mark advances last; a rest. `walk` plays steps in full, `hurry` ramps the +pace down and up again (each step 0.6 of the one before) to a run (0.30 s a +step) or a sprint, `step` takes an explicit `Plan` (`Array.swap`, +`syscalls.step`). Components read it through `Cursor.now(at)`. ## The blocks -| Block | File | Reads | Use | +The catalogue's layers, and where each block is. Every block is drawn in +every state the code has in the `gallery` scene. + +| Layer | Block | Where | Notes | | --- | --- | --- | --- | -| `Recording` | `src/Recording.zig` | every moment once, at open | the index: lines, calls, syscalls, allocations, which registers and bytes each moment changed; `next`, `lineMoment`, `call`, `variable`, `assigned`, `instruction`, `viewFirst` | -| `ui.Ui` | `src/ui.zig` | | rects, text on a baseline, `panel`, `value` (a value by its class), `chainArrow`, `struck`/`readFrame` (marks in the context), `written`/`readMark` (marks in a lens's cell), `arrow`, `clip`, `veil` | -| `context.chain` | `src/context.zig` | `zt.telescope.chase` | a value followed as far as it points, each link in its region's ink | -| `Registers` | `src/context.zig` | `Moment.regs`, mappings | 18 rows: sixteen, rip (a current mark), the flags; options `syscalls`, `quiet` | -| `Stack` | `src/context.zig` | `Moment.regs`, `Moment.read` | eight words from rsp as a telescope, plaques for rsp and rbp, frame notes | -| `Backtrace` | `src/context.zig` | `zt.telescope.backtrace` | the call chain by frame pointer, newest on top | -| `Disasm` | `src/context.zig` | the recorded instructions | rows round the pc in address order, the pc's row fixed | -| `Source` | `src/source.zig` | `Moment.line` (the index) | the whole file in a window, pardes's colours, the current mark and its trail | -| `Clock` | `src/words.zig` | the cursor | the progress rule over the caption, `moment N of M`, the step counter | -| `Caption`, `Narrator` | `src/words.zig`, `src/root.zig` | | the narrator's sentence, one at a time | -| `CallTree` | `src/calls.zig` | the index of calls | lens: every call of a function as a tree | -| `Nodes` | `src/nodes.zig` | `Moment.variables`, `Moment.read`, `Moment.allocation`, types | lens: structs the program's pointers reach, as nodes and arrows, with variable tags | -| `Hexdump` | `src/hexdump.zig` | `Moment.read`, `Moment.allocation`, types | lens: sixteen bytes a row, each word marked as what it is | -| `Array` | `src/array.zig` | `Moment.variables`, `Moment.read`, reads and writes | lens: an array's cells, index tags, values in flight | -| `Crossing` | `src/syscalls.zig` | the index of syscalls | lens: the kernel's side of a system call, on vellum | -| `Ties` | `src/ties.zig` | anchors the others publish | connections between panes: the gold thread, the step's link, a written word and its node | -| `Camera` | `src/root.zig` | | announced moves: `go(box, zoom, others)`, `back(others)`, `apply` | -| `Locals`, `Memory`, `Heap`, `Timeline`, `Legend`, `Label`, `Veil` | `src/registers.zig`, `memory.zig`, `heap.zig`, `syscalls.zig`, `words.zig` | | first-pass blocks, still built; only `Legend` and `Label` are used (the title card) | +| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes"; JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 | +| 1 atom | `address` (`lead`, `name`, `rwx`), `value`, `arrow` (`points`, `holds`, `more`), `mark`s, `plaque` (`chip`), `pin` (`row`, `under`), `bracket` (`quiet`, `tie`, `thread`), `tag` | `src/ui.zig` (`Ui.address`, `.value`, `.arrow`, `.written`, `.read`, `.cellWritten`, `.cellRead`, `.current`, `.trail`, `.unknown`, `.chip`, `.pinRow`, `.pinUnder`, `.bracket`, `.panel`) | marks in the context: `armed`, `struck`, `held` (a tick), `read`; in a lens's cell the same with a bar | +| | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `allocator`, `unread`; `pad` | +| 2 row | `chain`, `reg` (and `rip` with the flags), `slot`, `line`, `bytes`, `call` (`span`, `callRow`) | `src/rows.zig` | `chain` follows `zt.telescope.chase`; cut at its far end, `more` | +| | `insn` | `src/disasm.zig` | columns at 2, 31, 40, 134, 180, 264, 564; `current`, `ran`, `ahead`, `outside`; the annotation from the moment's `touch` and `branch` | +| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's `call` spans and the backtrace from `zt.telescope.frames` | +| | `source` | `src/source.zig` | the whole file in a window, its middle third | +| | `disasm` | `src/disasm.zig` | 17 rows (11 as subject), fewer above near a function's start | +| | `hexdump` | `src/hexdump.zig` | a lens's right half: `bytes` rows and their reading | +| | lenses: `nodes`, `array`, `calls`, `syscalls` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`) | in the band; `nodes` and `array` with their dump | +| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, draws in the channels | +| 5 frame | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject` (`theme.layout.split`) | +| | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the title card is `scenes/title.zig` | +| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `advance`, `cascade`, `run`, `sprint`, `establish`, `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time` | + +`Recording` (`src/Recording.zig`) is the index every block reads: lines, +calls, syscalls, allocations, which registers and bytes each moment changed +and read (a debugger's `touch` reads count), each moment's `touch` and +`branch`, and each instruction's line. ## The recordings `build.zig` records four programs of `tools/` under `ztrace record` (the debugger: registers, the stack, what they point at, the instructions round -the pc, at every stop), each by a bare name in a directory of its own with -an empty environment, without address randomisation: +the pc with their lines and callees' parameter counts, at every stop), each +by a bare name in a directory of its own with an empty environment, without +address randomisation. The instrumented ones are built `-no-pie`, so their +code and heap have short addresses as the design's columns expect. | Name | Program | Stops | Also | | --- | --- | --- | --- | | `steps` | `fib.c`, static musl, `-O0` | every instruction | | | `hello` | `hello.c`, static musl | every line | reads `tools/note` | | `sort` | `sort.c` built by `ztrace cc` (`calls,vars,stores,loads`) | every line | `--ring` | -| `list` | `list.c` built by `ztrace cc` (`calls,vars,stores`) | every line | `--alloc --preload` the agent | +| `list` | `list.c` built by `ztrace cc` (`calls,vars,stores,loads`) | every line | `--alloc --preload` the agent: allocator headers are read | +| `gallery` | a copy of `list`, kept in `test/gallery/list.ztrace` | | the gallery's pictures depend on the drawing only | + +## Motion, as measured + +`tools/chart.py chart` on the 1080p exports (the designer's five checks; the +baseline is `design/motion.md`'s table, measured before the frame changed): + +| | fib | list | sort | syscalls | zoom | +| --- | --- | --- | --- | --- | --- | +| POP, before / now | 68 / 0 | 40 / 0 | 35 / 0 | 0 / 0 | 1 / 0 | +| CROWD, before / now | 75 / 7 | 43 / 2 | 44 / 10 | 4 / 5 | 5 / 4 | +| METRONOME, before / now | 68 steps / none | 15 / none | 36 / none | 4 / none | none | +| RUSH, now | 0 | 0 | 2 | 1 | 0 | +| seconds | 40.6 | 59.3 | 39.5 | 34.8 | 30.2 | + +What still fires, and why it is left: + +- CROWD at each `advance` that crosses a function (source, disassembly and + rip move together: the catalogue's `advance` says they are one mark), + inside `run` and `sprint` stretches (steps that are not to be read), and + in fib at 22.25 s: a one-frame change in the disassembly and the stack on + a step's first frame, beside the fire, not yet found. +- AIR at each scene's opening: the designed stillness, 1 s and 0.5 s a panel. +- RUSH in sort and syscalls at the last caption: the last step's cool and + ticks still settle under it. ## What is not done -- The look was not compared with `design/mock/09` to `11` after the frame - changed; the designer's later notes (a catalogue of blocks, ties as a - design form, the disassembly's annotations) are not in. -- The disassembly has no operand note, no call, jump or return annotation - (`touch` and `branch` events are not read). -- The motion checks (`tools/chart.py`) were last run before the frame - changed; no scene is known to pass them now. -- `test/*.script` only run each scene to three instants; there are no pixel - assertions and no gallery. -- 4K exports and performance at the context's density were not measured - after the change. +- The instrumented recordings (`list`, `sort`) clobber registers between + lines, so their registers are `quiet` (no strikes, no links) and their + pins name variables. A `--by insn` recording of `list` with only `vars` + is 1.6 M moments (the loader and libc start-up): too many. So `link`, and + `ran` rows with the jump lane, are seen in the scenes of `steps` (fib, + zoom) only; a recording by line knows no instructions between its stops. +- `establish` for a lens (its elements rising from their rows by + projection) is not drawn: lenses fade in with the panels. +- The `thread`'s brackets on the disassembly change runs at the middle of + the advance; only the source's slides. +- `value` classes `fd`, `flags` (other than rip's), `bool`, `char` are not drawn. +- Back pointers between nodes run under the nodes and can cross a pin's stub. +- `heap` and `pages` lenses are not in the band (`Timeline` is the old far view). +- The camera rests at x2 in `zoom` (the stack of the `none` split fills it); + x1.5 is supported (`theme.camera.scales`) but no scene uses it. +- `zig build test` prints "failed command" for each scripted scene: that is + the run echoing its stderr (the Vulkan headless warning), not a failure; + the summary line is the verdict. -- cgit v1.3