# canim 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 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, 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` (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 ```zig const anim = @import("anim"); const canim = @import("canim"); const recordings = @import("recordings"); pub const background = canim.background; 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 var at = canim.cursor(s, rec, rec.lineMoment(10, rec.call("main", 0).enter)); 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 // 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.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 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, 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 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 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 | | --- | --- | --- | --- | | 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 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,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 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.