# 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 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. ```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 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`, `../../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 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.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 var says: canim.Narrator = .{}; canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, 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 }); 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. **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`. ## The blocks | Block | File | Reads | Use | | --- | --- | --- | --- | | `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) | ## 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: | 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 | ## 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.