summaryrefslogtreecommitdiff
path: root/anim/scenes
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 14:48:26 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:14:31 -0300
commit7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch)
treea6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/scenes
parented46c51fe127377eb1fde8dee83da984e0f61860 (diff)
downloadcomputeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz
computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip
canim: animations of recordings, as a debugger's whole context with a lens beside it
A package of its own (anim/), on sketchbook's anim module and pardes's syntax. A scene opens a recording, takes a cursor into it, and declares blocks that read the moment the cursor is at: the state column (registers each followed as a pointer and inked by where it points, the stack telescope, the backtrace), the program column (the whole source, the disassembly in address order, and the scene's lens: a node-link list over a hexdump of its heap, array cells, a call tree, a syscall crossing), and ties between them. Motion is a step told as a sentence (the line fires, its effects cascade a level at a time, the mark moves on last), timed by what the step contains; walk, hurry and sprint pace a loop. Five scenes from real recordings of fib, a linked list, a sort and syscalls. First drafts, by the agent's own handover: the frame of the design's second revision, the hexdump lens and the ties; no disassembly annotations, no gallery, scenes not yet reviewed against the mocks.
Diffstat (limited to 'anim/scenes')
-rw-r--r--anim/scenes/fib.zig59
-rw-r--r--anim/scenes/list.zig52
-rw-r--r--anim/scenes/sort.zig63
-rw-r--r--anim/scenes/syscalls.zig49
-rw-r--r--anim/scenes/title.zig22
-rw-r--r--anim/scenes/zoom.zig50
6 files changed, 295 insertions, 0 deletions
diff --git a/anim/scenes/fib.zig b/anim/scenes/fib.zig
new file mode 100644
index 0000000..e98727d
--- /dev/null
+++ b/anim/scenes/fib.zig
@@ -0,0 +1,59 @@
+//! Recursion: fib(5), a call at a time. The debugger's whole context, from
+//! one recording of every instruction, and beside it the lens: every call
+//! of fib as a tree.
+//!
+//! How it moves (design/motion.md): the picture is established, then one
+//! call is walked in full (the line fires, `rdi` and `rsp` strike, the
+//! stack's words, then the backtrace's row and the tree's node; last the
+//! marks move on); the way down the first branch is hurried, a run that
+//! ramps in and out; the first return is walked (the answer in `rax`, the
+//! frame leaving); the rest of the tree is a sprint with the context
+//! veiled; and the last return, `fib(5)` itself, is walked again.
+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);
+ // The calls of fib, in the order they are made: fib(5), fib(4), fib(3), fib(2), fib(1), fib(0), ...
+ const call = struct {
+ fn of(r: *canim.Recording, nth: usize) canim.Recording.Call {
+ return r.call("fib", nth);
+ }
+ }.of;
+ const split = canim.layout.split.beside;
+ // From main's line, about to call fib(5), to where fib(5) has returned to it.
+ var at = canim.cursor(s, rec, rec.lineMoment(10, rec.call("main", 0).enter));
+ at.levels = .{ .idea = .calls, .source_rows = 8 };
+ at.journey(.line, call(rec, 0).exit.?);
+ const ctx = canim.context(s, at, .{ .split = split });
+ // The lens: every call of fib as a tree, beside the frames they are on the stack.
+ const tree = canim.callTree(s, .{ .cursor = at, .box = split.lens, .function = "fib", .focus = true });
+ var says: canim.Narrator = .{};
+
+ // Staging: the whole picture, still, before a word; the words, before a step.
+ const joins = canim.ties(s, .{ .cursor = at });
+ canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, tree, joins });
+ says.line(s, "`fib` calls itself. A call is a frame on the stack and a node\nin the tree; its argument arrives in `rdi`.");
+ // The call, once, in full; and the two lines that lead to the next one.
+ at.walk(s, .line, rec.lineMoment(6, call(rec, 0).enter));
+ s.wait(canim.theme.time.beat);
+
+ // Pacing: the same three lines three times more. Seen once, so
+ // hurried: down the first branch at a run, to the call that does not call.
+ at.hurry(s, .line, rec.lineMoment(5, call(rec, 4).enter), .{});
+
+ says.line(s, "`fib(1)` needs no other call. Its answer leaves in `rax`,\nand its frame goes.");
+ // The return, in full: what recursion is for.
+ at.walk(s, .line, call(rec, 4).exit.?);
+
+ says.line(s, "And so on through every branch: fifteen calls,\nto add up `fib(5)`.");
+ // The pattern is known: the rest of the tree at a sprint, the tree its
+ // subject, slowing into the last answers.
+ at.hurry(s, .line, call(rec, 10).exit.?, .{ .pace = canim.theme.time.sprint });
+ at.walk(s, .line, call(rec, 0).exit.?);
+ s.wait(canim.theme.time.before_cut);
+}
diff --git a/anim/scenes/list.zig b/anim/scenes/list.zig
new file mode 100644
index 0000000..5f2c843
--- /dev/null
+++ b/anim/scenes/list.zig
@@ -0,0 +1,52 @@
+//! A linked list reversed in place: no node moves, each `next` is rewritten
+//! to point the other way. The debugger's context, and beside it the lens:
+//! the nodes and their arrows over a hexdump of the heap they are made of.
+//!
+//! How it moves (design/motion.md): the picture is established; the first
+//! trip round the loop is walked (each local strikes on the stack and in
+//! the table, then its tag slides to its node; the pointer's rewrite is
+//! armed with its old arrow going dashed, strikes, and the new arrow grows
+//! to the node it lands on); the second trip is hurried, with a rest; the
+//! third is walked again, and `head` takes the last node.
+const anim = @import("anim");
+const canim = @import("canim");
+const recordings = @import("recordings");
+
+pub const background = canim.background;
+pub const scene = anim.Live(frame, struct {});
+
+/// Each a pigment, the same on its tag in the list and in the table.
+const tracked = [_][]const u8{ "prev", "cur", "next" };
+
+fn frame(s: *anim.Frame) void {
+ const rec = canim.open(recordings.list);
+ const t = canim.theme.time;
+ const reverse = rec.call("reverse", 0);
+ // From reverse's first line (the list of three is built) to its last.
+ var at = canim.cursor(s, rec, rec.lineMoment(18, reverse.enter));
+ // The nodes are the idea; a tag slides and an arrow grows after its strike.
+ at.levels = .{ .cpu = false, .idea = .data, .follow = t.move, .source_rows = 5 };
+ const end = rec.lineMoment(27, reverse.enter);
+ at.journey(.line, end);
+ // The idea is the subject: the lens a size up, the nodes over the bytes they are.
+ const split = canim.layout.split.subject;
+ const ctx = canim.context(s, at, .{ .split = split, .quiet = true });
+ const lens = split.lens;
+ const list = canim.nodes(s, .{ .cursor = at, .box = .{ .x = lens.x, .y = lens.y, .w = lens.w, .h = 192 }, .root = "head", .track = &tracked, .focus = true });
+ const bytes = canim.hexdump(s, .{ .cursor = at, .box = .{ .x = lens.x, .y = lens.y + 204, .w = lens.w, .h = lens.h - 204 }, .base = rec.allocations[0].ptr - 16 });
+ var says: canim.Narrator = .{};
+
+ const joins = canim.ties(s, .{ .cursor = at });
+ canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, list, bytes, joins });
+ says.line(s, "A list is nodes on the heap, each holding the address of the next.\nReversing it moves no node: it rewrites every `next`.");
+ // Three names are set up, then the first trip round the loop, in full.
+ at.walk(s, .line, rec.lineMoment(20, rec.lineMoment(24, reverse.enter)));
+ says.line(s, "`next` remembers the way on, `cur->next` is turned round,\nand `prev` and `cur` each step along.");
+ // Pacing: the second trip is the same, so hurried; it keeps its rest.
+ at.hurry(s, .line, rec.lineMoment(20, rec.lineMoment(24, at.moment(s))), .{});
+ // The third in full again: the last `next` turns, and `cur` runs off the end.
+ at.walk(s, .line, rec.lineMoment(26, at.moment(s)));
+ says.line(s, "`head` takes the last node: the same three nodes,\nin the same places, read the other way.");
+ at.walk(s, .line, end);
+ s.wait(t.before_cut);
+}
diff --git a/anim/scenes/sort.zig b/anim/scenes/sort.zig
new file mode 100644
index 0000000..0f14269
--- /dev/null
+++ b/anim/scenes/sort.zig
@@ -0,0 +1,63 @@
+//! Insertion sort: neighbours compared, and swapped while the left is larger.
+//!
+//! How it moves (design/motion.md): it opens where `i` has reached 12, the
+//! first value out of order; the compare is walked (its two cells framed:
+//! the swap's anticipation), the caption about the swap stands two
+//! seconds before it, and the swap is two flights on arcs, the second a
+//! little behind the first, each cell struck as its value lands. The next
+//! trips are a run, the long middle a sprint, and the last swap is walked.
+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.sort);
+ const t = canim.theme.time;
+ const sort = rec.call("sort", 0);
+ // The `while`, about to compare 31 with 12: the stop before the one that calls swap.
+ var start = sort.enter;
+ while (rec.next(.over, rec.next(.over, start)) < rec.call("swap", 0).enter) start = rec.next(.over, start);
+ var at = canim.cursor(s, rec, start);
+ // The array is the idea; `i` and `j` are memory, and strike a beat before their tags slide.
+ at.levels = .{ .cpu = false, .idea = .data, .follow = t.quick, .source_rows = 8 };
+ // Its last compare: nothing larger is left of 20.
+ const last = rec.call("swap", 9);
+ const end = rec.next(.over, rec.next(.over, last.exit.?));
+ at.journey(.over, end);
+ // The context is the instrumented program's: its registers are unmarked.
+ const split = canim.layout.split.beside;
+ const ctx = canim.context(s, at, .{ .split = split, .quiet = true });
+ // The lens: the array as cells, and the two indices that walk it.
+ const cells = canim.array(s, .{ .cursor = at, .box = split.lens, .variable = "a", .indices = &.{ "i", "j" }, .focus = true });
+ var says: canim.Narrator = .{};
+ // A swap, start to finish, as one step of sort(): over the call.
+ const swap = struct {
+ fn step(c: canim.Cursor, frame_: *anim.Frame, r: *canim.Recording) void {
+ c.step(frame_, r.next(.over, c.moment(frame_)), canim.Array.swap, canim.Array.swap.total);
+ }
+ }.step;
+
+ const joins = canim.ties(s, .{ .cursor = at });
+ canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, cells, joins });
+ says.line(s, "`i` walks right. Everything left of it is in order,\nand 12 is not yet in its place.");
+ // The compare: both cells framed. It is the swap's anticipation.
+ at.walk(s, .over, rec.next(.over, start));
+ says.line(s, "While the one on the left is larger, they trade places,\nand `j` follows the smaller value down.");
+ // The caption of the step the scene is about stands a second longer.
+ s.wait(t.caption_lead);
+ // Arcs: the two values fly past each other, one over, one under.
+ swap(at, s, rec);
+ at.walk(s, .over, rec.next(.over, at.moment(s)));
+
+ // Pacing: the same again, so at a run; then the long way 5 has to go,
+ // at a sprint; slowing for the last swap.
+ at.hurry(s, .over, rec.call("swap", 3).enter - 1, .{ .to = t.run, .settle = false });
+ at.hurry(s, .over, last.enter - 1, .{ .pace = t.sprint, .from = t.run });
+ swap(at, s, rec);
+ at.walk(s, .over, end);
+ says.line(s, "Nothing larger is left of 20. The array is sorted.");
+ s.wait(t.before_cut - t.caption_lead);
+}
diff --git a/anim/scenes/syscalls.zig b/anim/scenes/syscalls.zig
new file mode 100644
index 0000000..1516251
--- /dev/null
+++ b/anim/scenes/syscalls.zig
@@ -0,0 +1,49 @@
+//! A program that needs the kernel four times: open, read, close, write.
+//! The debugger's context, and the kernel's side of each call as the lens.
+//!
+//! How it moves (design/motion.md): no effect before its cause. Each call
+//! has its own caption, up a second before the line fires; the registers
+//! that carry it are framed one at a time; the arrow goes down through
+//! the line, and only then does the kernel's side take the call: its
+//! name, its rows, its card. The bytes are copied two frames apart; the
+//! arrow comes back; `rax` is struck. A call is as long as what it does.
+const anim = @import("anim");
+const canim = @import("canim");
+const recordings = @import("recordings");
+
+pub const background = canim.background;
+pub const scene = anim.Live(frame, struct {});
+
+/// What the narrator says before each of main's calls, in order.
+const lines = [_][]const u8{
+ "`open`: a name goes down, and a small number comes back.\nThat number is the file from now on.",
+ "`read`: the kernel copies the file's bytes into `buf`,\nand says how many.",
+ "`close`: the number is handed back.",
+ "`write`: the same bytes go the other way,\nfrom `buf` to file number 1, the output.",
+};
+
+fn frame(s: *anim.Frame) void {
+ const rec = canim.open(recordings.hello);
+ // From main's first call to its last line.
+ var at = canim.cursor(s, rec, rec.lineMoment(6, rec.call("main", 0).enter));
+ at.journey(.line, rec.lineMoment(10, at.first));
+ const split = canim.layout.split.beside;
+ at.levels = .{ .source_rows = 8 };
+ const ctx = canim.context(s, at, .{ .split = split, .syscalls = true });
+ // The lens: the kernel's side of each call.
+ const kernel = canim.crossing(s, .{ .cursor = at, .box = split.lens, .focus = true });
+ var says: canim.Narrator = .{};
+ const t = canim.theme.time;
+
+ const joins = canim.ties(s, .{ .cursor = at });
+ canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, kernel, joins });
+ says.line(s, "A program cannot open a file or reach the screen itself.\nIt asks the kernel, and waits.");
+
+ // One call a phrase: its caption while nothing moves, then the crossing.
+ for (lines) |line| {
+ says.line(s, line);
+ canim.syscalls.step(at, s, .line);
+ s.wait(t.phrase_rest);
+ }
+ s.wait(t.before_cut - t.phrase_rest);
+}
diff --git a/anim/scenes/title.zig b/anim/scenes/title.zig
new file mode 100644
index 0000000..3646da4
--- /dev/null
+++ b/anim/scenes/title.zig
@@ -0,0 +1,22 @@
+//! The card before the scenes: what the series is, and the marks every
+//! picture in it uses.
+const anim = @import("anim");
+const canim = @import("canim");
+
+pub const background = canim.background;
+pub const scene = anim.Live(frame, struct {});
+
+fn frame(s: *anim.Frame) void {
+ const size = canim.theme.size.sans;
+ const text = canim.theme.color.text;
+ const series = canim.label(s, .{ .text = "How programs really run", .box = .{ .x = 64, .y = 138, .w = 900, .h = 48 }, .size = size.kicker, .color = text.dim });
+ const title = canim.label(s, .{ .text = "Five small programs,\none step at a time", .box = .{ .x = 64, .y = 220, .w = 1792, .h = size.title_leading }, .face = .sans_bold, .size = size.title, .color = text.bright });
+ const under = canim.label(s, .{ .text = "recorded as they ran: every line, register and byte", .box = .{ .x = 64, .y = 500, .w = 1792, .h = 60 }, .face = .sans, .size = size.subtitle, .color = text.dim });
+ const marks = canim.legend(s, .{ .box = canim.theme.cols(0, 12, 512, 256) });
+ const t = canim.theme.time;
+ s.play(.{ series.fadeIn(), title.fadeIn() }, .{ .seconds = t.layout, .ease = canim.ease.enter });
+ s.play(.{under.fadeIn()}, .{ .seconds = t.move });
+ s.wait(t.beat);
+ s.play(.{marks.fadeIn()}, .{ .seconds = t.travel });
+ s.wait(4);
+}
diff --git a/anim/scenes/zoom.zig b/anim/scenes/zoom.zig
new file mode 100644
index 0000000..6eb3248
--- /dev/null
+++ b/anim/scenes/zoom.zig
@@ -0,0 +1,50 @@
+//! One line of C, all the way down: the instructions it is, the registers
+//! they change, the words they write on the stack. Every level is on
+//! screen the whole time; the scene steps an instruction at a time and
+//! says which one to look at.
+//!
+//! How it moves (design/motion.md): a step is an instruction: the pc's
+//! row fires in the disassembly, the registers it changed strike, then
+//! the stack, and the mark walks down the listing. The camera goes
+//! nearer once, announced (its target framed, the rest cleared first),
+//! for the call: the eight bytes of the way back, and the frame built
+//! under them; then back, and the line is where it was, one call deeper.
+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);
+ const t = canim.theme.time;
+ // fib(5), about to run line 6: `return fib(n-1) + fib(n-2);`. Its first call is fib(4).
+ const call = rec.call("fib", 1);
+ var at = canim.cursor(s, rec, rec.lineMoment(6, rec.call("fib", 0).enter));
+ const end = rec.lineMoment(6, call.enter);
+ at.journey(.moment, end);
+ // A step is an instruction: it fires on the pc's row.
+ at.levels = .{ .fire = .disasm, .source_rows = 14 };
+ const split = canim.layout.split.none;
+ const ctx = canim.context(s, at, .{ .split = split });
+ var cam: canim.Camera = .{};
+ var says: canim.Narrator = .{};
+
+ const joins = canim.ties(s, .{ .cursor = at });
+ canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, joins });
+ says.line(s, "A line of C is a handful of instructions.\nThis one calls `fib(n-1)`: follow it down.");
+ // The CPU's level: an instruction a step. The argument is worked out in `rdi`.
+ at.walk(s, .moment, call.enter - 1);
+
+ says.line(s, "`call` writes eight bytes on the stack: the way back.\nThe new frame saves `rbp` under them, then its own `n`.");
+ // Nearer, for the bytes: the stack alone, twice the size.
+ cam.go(s, canim.layout.stack, 2, .{ ctx.source, ctx.disasm, ctx.registers, ctx.backtrace });
+ at.walk(s, .moment, call.enter + 4);
+ cam.back(s, .{ ctx.source, ctx.disasm, ctx.registers, ctx.backtrace });
+
+ says.line(s, "Eleven instructions and three words of stack later\n`fib(4)` begins: the same lines, one call deeper.");
+ at.walk(s, .line, end);
+ s.wait(t.before_cut);
+ cam.apply(s);
+}