diff options
Diffstat (limited to 'anim/README.md')
| -rw-r--r-- | anim/README.md | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/anim/README.md b/anim/README.md new file mode 100644 index 0000000..9878765 --- /dev/null +++ b/anim/README.md @@ -0,0 +1,126 @@ +# 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. |
