summaryrefslogtreecommitdiff
path: root/anim/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'anim/README.md')
-rw-r--r--anim/README.md126
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.