summaryrefslogtreecommitdiff
path: root/anim/scenes
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 09:41:45 -0300
committerGabriel Schneider <[email protected]>2026-11-11 10:14:30 -0300
commit390872b7bb9cdcf3e8095442af88af0dfcb40602 (patch)
treeab767cf46dfca036e61e0e19bb5e1c4772cb1d4d /anim/scenes
parent378379807fb4cd751e90808c8363caddb365bcd8 (diff)
downloadcomputeranim-390872b7bb9cdcf3e8095442af88af0dfcb40602.tar.gz
computeranim-390872b7bb9cdcf3e8095442af88af0dfcb40602.zip
canim: what the verification review found, fixed
A register's chain reads memory as its panel shows it, and follows again only after the bytes land: rsi no longer shows what read returns before the kernel writes it. Bytes keep their old value through the arm and change at their own strike, in every dump, stack word and loupe. The dive lands once. Captions lead what they name: the longest still in the syscalls scene is 2.8 s where it was 13. Pins hold through a sprint; a row of a view carries the pin of the register that points at it; a left child's badge sits on its left shoulder; a log scrolls with the row that arrives. The zoom scene's camera holds the disassembly's rows and the stack in one view. Six programs, the title says now. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/scenes')
-rw-r--r--anim/scenes/gallery.zig28
-rw-r--r--anim/scenes/heap.zig7
-rw-r--r--anim/scenes/list.zig9
-rw-r--r--anim/scenes/sqlite.zig50
-rw-r--r--anim/scenes/syscalls.zig9
-rw-r--r--anim/scenes/title.zig8
-rw-r--r--anim/scenes/zoom.zig18
7 files changed, 80 insertions, 49 deletions
diff --git a/anim/scenes/gallery.zig b/anim/scenes/gallery.zig
index bd363d5..693553e 100644
--- a/anim/scenes/gallery.zig
+++ b/anim/scenes/gallery.zig
@@ -33,7 +33,8 @@ const Pages = struct {
pub fn draw(p: *const Pages, f: *sk.Frame, at: anim.Placed) void {
const u: ui.Ui = .{ .f = f, .at = at };
- if (at.t < 1) atoms(u, p) else if (at.t < 2) rowsPage(u, p);
+ // Each page 3 s: long enough to be looked at.
+ if (at.t < 3) atoms(u, p) else if (at.t < 6) rowsPage(u, p);
}
};
@@ -183,12 +184,15 @@ fn atoms(u: ui.Ui, p: *const Pages) void {
y = 698;
title(u, 64, y, "pin");
- note(u, 140, y, "row; under; a count after three names");
+ note(u, 140, y, "row, end; under; a count after three names");
y += 12;
u.pinRow(64, y, &.{ "rsp", "rbp" }, region.stack);
+ // At a view's row's end (a dump has no lane before its addresses).
+ _ = u.pinEnd(440, y, &.{"rsi"}, region.stack);
u.pinRow(64, y + row, &.{ "rax", "rdi", "rsi", "r8" }, region.heap);
- u.fill(.{ .x = 400, .y = y - 20, .w = 116, .h = 20 }, theme.color.raised);
- u.pinUnder(458, y, &.{ "rax", "rdi" }, region.heap, theme.size.mono.context);
+ // Clear of the note over it.
+ u.fill(.{ .x = 520, .y = y - 20, .w = 116, .h = 20 }, theme.color.raised);
+ u.pinUnder(578, y, &.{ "rax", "rdi" }, region.heap, theme.size.mono.context);
y = 698;
title(u, 700, y, "bracket");
@@ -322,20 +326,20 @@ fn frame(s: *anim.Frame) void {
const joins = ctx.ties(s);
const says = canim.caption(s, "The gallery: the frame, at rest. Every panel, the thread,\nthe lens beside it: the list and the bytes it is drawn from.");
const panels = .{ ctx.clock, ctx.registers, ctx.stack, ctx.backtrace, ctx.source, ctx.disasm, list, joins, says };
- s.wait(2);
+ s.wait(6);
var all: [panels.len]anim.Animation = undefined;
inline for (panels, 0..) |o, i| all[i] = o.fadeIn();
s.play(all, .{ .seconds = 0 });
- // A step at 3 s, its strikes and ties at about 3.6.
- s.wait(3 - s.cursor);
+ // A step at 9 s, its strikes and ties at about 9.6; each state 3 s.
+ s.wait(9 - s.cursor);
at.walk(s, .line, rec.next(.line, rest));
- s.wait(5 - s.cursor);
+ s.wait(12 - s.cursor);
ctx.stage.relayout(s, canim.layout.split.subject);
- s.wait(7 - s.cursor);
+ s.wait(15 - s.cursor);
ctx.stage.relayout(s, canim.layout.split.none);
- s.wait(9 - s.cursor);
+ s.wait(18 - s.cursor);
near.open(s);
- s.wait(9.8 - s.cursor);
+ s.wait(18.8 - s.cursor);
deeper.open(s);
- s.wait(11 - s.cursor);
+ s.wait(21 - s.cursor);
}
diff --git a/anim/scenes/heap.zig b/anim/scenes/heap.zig
index 544ae91..1f82766 100644
--- a/anim/scenes/heap.zig
+++ b/anim/scenes/heap.zig
@@ -220,7 +220,10 @@ const Lists = struct {
const shows: f32 = if (from == null) after(now, 0, 12) else if (to == null) 1 - after(now, 0, 12) else 1;
const nv = v.faded(shows);
const r: canim.Rect = .{ .x = xy[0], .y = xy[1], .w = w, .h = h };
- _ = nv.address(r.x + 16, r.y - 8, node, .{ .ink = ui.rgb(theme.color.region.heap) });
+ // On its way between the rows its address goes and comes back (the first and last quarter): it never passes over a pin's names.
+ const travels = s0.row != s1.row or s0.k != s1.k;
+ const label = if (travels) std.math.clamp(@max(1 - 4 * p, 4 * p - 3), 0, 1) else 1;
+ _ = nv.faded(label).address(r.x + 16, r.y - 8, node, .{ .ink = ui.rgb(theme.color.region.heap) });
// Nothing turns in a frame: a node that changes lists turns as it lands (its last 12 f),
// and its value and link, where they change and are not struck, crossfade with the idea (12 f).
const lands = after(now, 36, 12);
@@ -346,7 +349,7 @@ const Chunks = struct {
// The heap new in this step (the first malloc's): its rows come in, unmarked, over 12 f with memory's slot.
const new = !now.resting() and heapAt(f.scratch, c.cursor.rec, now.stops[1]) == null;
const comes: f32 = if (new) std.math.clamp(now.since(.memory, 0) / (12.0 / 60.0), 0, 1) else 1;
- canim.hexdump.fielded(.{ .u = v.u.faded(comes), .rows = v.rows, .box = v.box }, now, cm.tag + cm.pad, .{ .base = view_base, .len = view_len, .fields = fieldsAt(f.scratch, c.cursor.rec, now.stop(.memory)), .watched = if (new) 0 else std.math.maxInt(usize) });
+ canim.hexdump.fielded(.{ .u = v.u.faded(comes), .rows = v.rows, .box = v.box }, now, cm.tag + cm.pad, .{ .base = view_base, .len = view_len, .fields = fieldsAt(f.scratch, c.cursor.rec, now.stop(.memory)), .was = fieldsAt(f.scratch, c.cursor.rec, now.stops[1]), .watched = if (new) 0 else std.math.maxInt(usize), .pins = true });
v.veil(now);
}
};
diff --git a/anim/scenes/list.zig b/anim/scenes/list.zig
index 39d413b..71cdf53 100644
--- a/anim/scenes/list.zig
+++ b/anim/scenes/list.zig
@@ -57,15 +57,16 @@ fn frame(s: *anim.Frame) void {
at.walk(s, .line, rec.lineMoment(19, reverse.enter));
says.line(s, "`cur` takes the head, and the loop begins\nat the first node.");
at.walk(s, .line, first_trip);
- // The loop's caption leads the loop.
- says.line(s, "`next` remembers the way on, `cur->next` is turned round,\nand `prev` and `cur` each step along.");
+ // The loop's caption leads the loop: as long as its step (the rest of the trip has captions of its own).
+ says.line(s, "`next` remembers the way on,\nbefore `cur->next` is turned round.");
at.walk(s, .line, loaded);
// A beat of its own: the pointer just loaded is opened, and the one in it.
- says.line(s, "`rax` holds `cur->next`: under it opens the heap round that node,\nand from its `next`, one deeper, the node after it.");
+ says.line(s, "`rax` holds `cur->next`: the heap round that node opens\nunder it, and from its `next`, the node after.");
near.open(s);
s.wait(t.beat);
deeper.open(s);
- s.wait(2 * t.beat + t.loupe.open);
+ // Held while the caption is read: 2 s at most without a change.
+ s.wait(2.0);
deeper.close(s);
s.wait(t.stagger * 3);
near.close(s);
diff --git a/anim/scenes/sqlite.zig b/anim/scenes/sqlite.zig
index db0e6d9..e19a7be 100644
--- a/anim/scenes/sqlite.zig
+++ b/anim/scenes/sqlite.zig
@@ -56,20 +56,22 @@ fn leaf(arena: std.mem.Allocator, page: []const u8) []const Field {
std.debug.assert(page[0] == 0x0d);
const cells = std.mem.readInt(u16, page[3..5], .big);
var out: std.ArrayList(Field) = .empty;
+ // Read as the caption names them: the page's type, then the rest of its
+ // header (3 cells), then the cell pointers, then each cell.
out.appendSlice(arena, &.{
.{ .at = 0, .len = 1, .mark = 0 },
- .{ .at = 1, .len = 2, .reads = .bytes, .big = true, .mark = 0 },
- .{ .at = 3, .len = 2, .big = true, .mark = 0 },
- .{ .at = 5, .len = 2, .reads = .bytes, .big = true, .mark = 0 },
- .{ .at = 7, .len = 1, .reads = .bytes, .mark = 0 },
+ .{ .at = 1, .len = 2, .reads = .bytes, .big = true, .mark = 1 },
+ .{ .at = 3, .len = 2, .big = true, .mark = 1 },
+ .{ .at = 5, .len = 2, .reads = .bytes, .big = true, .mark = 1 },
+ .{ .at = 7, .len = 1, .reads = .bytes, .mark = 1 },
}) catch @panic("OOM");
- for (0..cells) |k| out.append(arena, .{ .at = 8 + 2 * k, .len = 2, .big = true, .mark = 1 }) catch @panic("OOM");
+ for (0..cells) |k| out.append(arena, .{ .at = 8 + 2 * k, .len = 2, .big = true, .mark = 2 }) catch @panic("OOM");
for (0..cells) |k| {
const at: usize = std.mem.readInt(u16, page[8 + 2 * k ..][0..2], .big);
const size = page[at];
const header = page[at + 2];
std.debug.assert(size < 0x80 and page[at + 1] < 0x80 and header == 2);
- const mark: u8 = @intCast(2 + k);
+ const mark: u8 = @intCast(3 + k);
out.appendSlice(arena, &.{
.{ .at = at, .len = 1, .reads = .bytes, .mark = mark },
.{ .at = at + 1, .len = 1, .mark = mark },
@@ -135,7 +137,7 @@ fn frame(s: *anim.Frame) void {
std.debug.assert(bytes.len == 4096 and bytes[0] == 0x0d and bytes[4] == 3);
std.debug.assert(std.mem.eql(u8, bytes[8..14], &.{ 0x0f, 0xf7, 0x0f, 0xef, 0x0f, 0xe6 }));
std.debug.assert(rec.register(handed, "rsi") == write.args[1]);
- const page_marks = s.new([_]anim.Value{ s.value(0), s.value(0), s.value(0), s.value(0), s.value(0) });
+ const page_marks = s.new([_]anim.Value{ s.value(0), s.value(0), s.value(0), s.value(0), s.value(0), s.value(0) });
const page = canim.add(s, canim.hexdump.Dump{
.cursor = at,
.stage = ctx.stage,
@@ -144,7 +146,9 @@ fn frame(s: *anim.Frame) void {
.marks = page_marks,
.since = handed,
});
- const joins = ctx.ties(s);
+ // rdi, the table's cursor, opened as the caption names it; rsi, the row, linked to the view's row it points at.
+ const btcursor = canim.loupe(s, .{ .cursor = at, .stage = ctx.stage, .from = .{ .register = "rdi" } });
+ const joins, const row_link = ctx.tiesWith(s, "rsi", 1.0);
var says: canim.Narrator = .{};
const fade = struct {
@@ -178,9 +182,17 @@ fn frame(s: *anim.Frame) void {
fade.in(s, row);
says.line(s, "`sqlite3VdbeExec`, the bytecode's loop, calls the B-tree: `rdi` is\nthe table's cursor, `rsi` the row: rowid 1, a record of 7 bytes.");
- // Each field as the caption reaches it: the rowid, then the record's length.
+ // As the caption names them: rdi's cursor opened under it (a beat of
+ // its own), then rsi linked to the row; then each field: the rowid, the record's length.
+ const named = s.cursor;
+ btcursor.open(s);
+ row_link.play(s);
+ s.cursor = named + t.loupe.open + row_link.total();
+ btcursor.close(s);
+ // Spread over the caption's reading: never more than 2 s still.
+ s.wait(1.4);
mark.in(s, row_marks[0]);
- s.wait(2 * t.beat);
+ s.wait(2.0);
mark.in(s, row_marks[1]);
says.line(s, "Two more continues, the same call: rowid 2, then 3, records\nof 6 and 7 bytes. The rows are in memory, not yet on disk.");
@@ -203,16 +215,18 @@ fn frame(s: *anim.Frame) void {
const crossing = canim.syscalls.Plan.of(write);
at.step(s, back, crossing.step(), crossing.total);
- says.line(s, "Page 2 as the kernel took it: `0d`, a table's leaf; 3 cells;\ntheir offsets, `0ff7 0fef 0fe6`, each a row at the page's end.");
- mark.in(s, page_marks[0]);
- s.wait(3 * t.beat);
- mark.in(s, page_marks[1]);
- says.line(s, "Each cell: its length, its rowid, the record's header, the text.\n'alpha' went in first and sits last: cells fill from the end.");
- mark.out(s, page_marks[0..2]);
+ // Each field as the caption reaches it, 2 s apart: the picture is never still longer.
+ says.line(s, "Page 2 as the kernel took it: `0d`, a table's leaf; 3 cells,\nat `0ff7 0fef 0fe6`: each a row at the page's end.");
+ for (page_marks[0..3], 0..) |v, k| {
+ s.wait(if (k == 0) 0.4 else 2.0);
+ mark.in(s, v);
+ }
+ says.line(s, "Each cell: its length, rowid, header and text. 'alpha'\nwent in first and sits last: cells fill from the end.");
+ mark.out(s, page_marks[0..3]);
// The rows from the page's end: the first one in, then the next two.
- for (page_marks[2..]) |v| {
+ for (page_marks[3..], 0..) |v, k| {
+ s.wait(if (k == 0) 0.4 else 2.0);
mark.in(s, v);
- s.wait(2 * t.beat);
}
says.close(s);
}
diff --git a/anim/scenes/syscalls.zig b/anim/scenes/syscalls.zig
index 0d39089..e9f0ae5 100644
--- a/anim/scenes/syscalls.zig
+++ b/anim/scenes/syscalls.zig
@@ -54,12 +54,15 @@ fn frame(s: *anim.Frame) void {
says.line(s, "A program cannot open a file itself.\nIt asks the kernel, and waits.");
cur.walk(s, .line, rec.lineMoment(6, main.enter));
+ // Each caption leads its beat, and is read while it plays: the call's
+ // caption the line that makes it, the descend's the descend, so that no
+ // still picture waits out a reading time.
+ says.line(s, "`main` calls `open` by its stub in the PLT, with \"note\"\nin rdi and O_RDONLY in rsi.");
cur.walk(s, .moment, stub - 1);
- says.line(s, "`main` calls `open` by its stub in the PLT. The arguments\nare in rdi and rsi: \"note\" and O_RDONLY.");
+ says.line(s, "The call goes down: main's call waits, ringed;\nthe stub's three rows open under it.");
canim.descent.step(cur, s, .moment);
s.wait(t.phrase_rest);
- says.line(s, "The call went down: main's window keeps its call, ringed,\nand the stub's three rows open under it.");
- says.line(s, "The stub's jmp reads open@got, the GOT's slot,\nand goes on to libc's `open`.");
+ says.line(s, "The stub's jmp reads open@got\nand goes on to libc's `open`.");
canim.descent.step(cur, s, .moment);
s.wait(t.phrase_rest);
// The wrapper at a run, veiled; its last three instructions walked, named as they run.
diff --git a/anim/scenes/title.zig b/anim/scenes/title.zig
index d5af819..e412bd7 100644
--- a/anim/scenes/title.zig
+++ b/anim/scenes/title.zig
@@ -10,14 +10,14 @@ 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 = "Four 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 title = canim.label(s, .{ .text = "Six 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 = "fib, a list, a sort, hello, malloc and SQLite: 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 });
- // Ten marks to learn: long enough to read them all.
- s.wait(8);
+ // Twelve marks to learn: long enough to read them all.
+ s.wait(10);
}
diff --git a/anim/scenes/zoom.zig b/anim/scenes/zoom.zig
index 1f23c05..426d3a3 100644
--- a/anim/scenes/zoom.zig
+++ b/anim/scenes/zoom.zig
@@ -7,8 +7,9 @@
//! 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.
+//! for the call: the instructions and the stack's words in one view, 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");
@@ -39,17 +40,22 @@ fn frame(s: *anim.Frame) void {
at.walk(s, .moment, call.enter - 1);
says.line(s, "`call` writes eight bytes on the stack: the way back.");
- // Nearer, for the bytes: the stack alone, twice the size.
- cam.go(s, split.stack, 2, .{ ctx.source, ctx.disasm, ctx.registers, ctx.backtrace });
- // Under the camera the stack holds still: six free words above rsp for the new frame.
+ // The stack holds still under the camera, set before it moves: six free
+ // words above rsp for the new frame (rsp-30 to rsp+8).
ctx.stage.holdStack(s, at.moment(s), 6);
+ // Nearer, cause and effect in one view: the instructions as they run
+ // (mnemonics, operands, what each leaves) and the stack's words they
+ // write with their chains and roles (`fib+42`, `saved rbp`, `n`): from
+ // the mnemonics to the roles' end is all the stage holds at x1.16 (at
+ // x1.5 the stack's names and roles are off it); the rest cleared.
+ cam.go(s, .{ .x = 190, .y = 342, .w = 1525, .h = 480 }, 1.16, .{ ctx.source, ctx.registers, ctx.backtrace });
at.walk(s, .moment, call.enter);
// The frame built under them, under a caption of its own (12 s at most).
says.line(s, "The new frame saves `rbp` under them,\nthen stores its own `n`.");
at.walk(s, .moment, call.enter + 4);
s.wait(canim.theme.time.beat);
ctx.stage.releaseStack(s);
- cam.back(s, .{ ctx.source, ctx.disasm, ctx.registers, ctx.backtrace });
+ cam.back(s, .{ ctx.source, ctx.registers, ctx.backtrace });
says.line(s, "Nine instructions and three words of stack later\n`fib(4)` begins: the same lines, one call deeper.");
at.walk(s, .line, end);