summaryrefslogtreecommitdiff
path: root/anim/scenes/intro_stack.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-12 01:44:59 -0300
committerGabriel Schneider <[email protected]>2026-11-12 03:17:32 -0300
commitbf0dfa135319f8c7ca49eace4d1f81152ebfd23e (patch)
tree9c80ade769dc9a741c9d00f63770d34dc1769ced /anim/scenes/intro_stack.zig
parentaefde257db6e7cf683b923498c0d471885ab67a9 (diff)
downloadcomputeranim-bf0dfa135319f8c7ca49eace4d1f81152ebfd23e.tar.gz
computeranim-bf0dfa135319f8c7ca49eace4d1f81152ebfd23e.zip
canim: the introduction, three chapters
From the user: a first-principles showcase that builds the views. I, memory: the stack's bytes, words read low byte first, the address space to true scale with each cluster enlarged and every band's addresses and size, the bytes tied to their place, ink and chains. II, the stack: the words become the stack panel, a real push, the return address aimed at the row it returns to, rbp and the frame, the registers. III, code: an instruction's bytes decoded into one listing of lines and addresses, then two columns, then the working frame assembled and the map. Recorded from main's call of reverse with record --until. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/scenes/intro_stack.zig')
-rw-r--r--anim/scenes/intro_stack.zig141
1 files changed, 86 insertions, 55 deletions
diff --git a/anim/scenes/intro_stack.zig b/anim/scenes/intro_stack.zig
index e504ffc..49162e6 100644
--- a/anim/scenes/intro_stack.zig
+++ b/anim/scenes/intro_stack.zig
@@ -1,17 +1,22 @@
//! The introduction, chapter II: the stack (design/motion.md, "A scene: the
//! introduction", II1 to II4; mock 31). It opens on chapter I's last
-//! picture, at the same moment of the `list` recording (reverse's first
-//! call, line 17): the address space and the dump's link fade, the words
-//! glide into the stack panel's rows where it stands in the working frame
-//! and become it; a push walked from the recording (that call's: the
-//! address to come back to, rsp's pin climbing onto it); the return
-//! address main left, and the offsets; rbp's pin and the panel's tag last;
-//! then the registers built over it a row at a time, their tag last. The
-//! text stands beside on the left, in the program column, empty until
-//! chapter III.
+//! picture, at the same moment of the `intro` recording (reverse's first
+//! instruction, its `push rbp`): the address space and the dump's link
+//! fade, the words glide into the stack panel's rows where it stands in the
+//! working frame (sixteen of them and two `free` over rsp) and become it.
+//! rsp's row arrives over the stack and its pin lands on the top word; the
+//! push walked from the recording (rsp's pin climbing onto the saved rbp).
+//! The way back main left framed, main's three rows round its call arriving
+//! in the program column, the word aimed at the row it returns to (`aim`,
+//! this beat only), the offsets a `column`. rbp's row and pin, `mov rbp,
+//! rsp` and `sub rsp` walked: the frame; its roles and spans, a `column`
+//! each, the panel's tag last (`frame up`). Then the registers built over
+//! it a row at a time, their tag last. The text stands beside on the left,
+//! in the program column, empty until chapter III but for main's rows.
//!
-//! What a beat has not reached yet is under the page (`Cover`), lifted as
-//! the beat says it: the context's panels draw every column at once.
+//! What a beat has not reached yet is under the page (`Cover`, and the
+//! stack's own `reveal`), lifted as the beat says it: the context's panels
+//! draw every column at once.
const std = @import("std");
const anim = @import("anim");
const sk = @import("sketch");
@@ -80,59 +85,62 @@ fn lift(s: *anim.Frame, covers: []const ?anim.Obj, apart: f32, each: f32) void {
s.cursor = end;
}
-fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 {
- var buf: [256]u8 = undefined;
- var i = from;
- while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.indexOf(u8, here.text, text) != null) return i;
- return from;
-}
-
/// A value at once, from the cursor.
fn set(s: *anim.Frame, v: anim.Value, to: f32) void {
s.play(.{v.to(to)}, .{ .seconds = 0 });
}
+/// Clock `v` from 0 to `frames`, linear, from the cursor; the cursor after it.
+fn run(s: *anim.Frame, v: anim.Value, frames: f32) void {
+ s.play(.{v.to(0)}, .{ .seconds = 0 });
+ s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear });
+}
+
fn frame(s: *anim.Frame) void {
- const rec = canim.open(recordings.list);
+ const rec = canim.open(recordings.intro);
const reverse = rec.call("reverse", 0);
- // Chapter I's moment: reverse's first call, whose push is walked here.
- const moment = on(rec, reverse.enter, "call");
+ // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x20`.
+ const moment = reverse.enter;
+ const framed = moment + 3;
var at = canim.cursor(s, rec, moment);
- at.journey(.moment, moment + 1);
+ at.journey(.moment, framed);
at.levels = .{ .fire = .disasm, .source_rows = 14 };
- // The working frame with no backtrace: the stack goes to the stage's foot under the registers.
var split = canim.layout.split.none;
split.backtrace.h = 0;
const ctx = canim.context(s, at, .{ .split = split });
- const sb = ctx.stage.first.stack;
+ // Sixteen slots and the headroom under the registers' box (the words
+ // become them where they stand), not the column's rest.
const rb = ctx.stage.first.registers;
+ ctx.stage.first.stack.h = canim.layout.panelH(18);
+ ctx.stage.first.stack.y = rb.y + rb.h + canim.theme.canvas.row_gap;
+ const sb = ctx.stage.first.stack;
const rsp = rec.register(moment, "rsp");
- const rsp_after = rec.register(moment + 1, "rsp");
// The window has two `free` words over rsp; rows from the panel's tag and padding.
const first = rsp - 16;
const top = sb.y + tag + pad;
const slots = canim.layout.rowsIn(sb.h);
const rowY = struct {
fn y(t0: f32, from: u64, addr: u64) f32 {
- return t0 + row * @as(f32, @floatFromInt((addr - from) / 8));
+ return t0 + row * @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% from)) >> 3));
}
}.y;
- // What has not been said yet, under the page: the stack's offsets, the
- // pins' lane under rsp's row, its tag, rules and strip; the registers' rows, tag and rules.
- var offsets: [32]?anim.Obj = @splat(null);
- var lane: [32]?anim.Obj = @splat(null);
- const rsp_row = (rsp - first) / 8;
- for (0..@min(slots, 32)) |k| {
- const y = top + row * @as(f32, @floatFromInt(k));
- offsets[k] = cover(s, .{ .x = sb.x + 92, .y = y, .w = 84, .h = row });
- if (k > rsp_row) lane[k] = cover(s, .{ .x = sb.x + 2, .y = y, .w = 88, .h = row });
- }
- const stack_chrome = chrome(s, sb, true);
+ // The panels and the page over what they have not said yet, first: chapter I's
+ // picture, the words gliding into the stack among them, draws over them.
+ // The stack, its offsets, roles and spans under the page until their beats.
+ const reveal: canim.Stack.Reveal = .{ .offsets = s.value(-1), .roles = s.value(-1), .spans = s.value(-1) };
+ const stack = canim.add(s, canim.Stack{ .cursor = ctx.cursor, .stage = ctx.stage, .reveal = reveal });
+ // The registers, under the page: rbp's and rsp's rows (the scene's two, the first two), the rest, the chrome.
+ s.play(.{ctx.registers.fadeIn()}, .{ .seconds = 0 });
var regs_rows: [16]?anim.Obj = @splat(null);
for (0..@min(canim.layout.rowsIn(rb.h), 16)) |k|
- regs_rows[k] = cover(s, .{ .x = rb.x + 2, .y = rb.y + tag + pad + row * @as(f32, @floatFromInt(k)), .w = rb.w - 4, .h = row });
+ // (From the third row on 2 higher: the rule over the folded rows goes with them.)
+ regs_rows[k] = cover(s, .{ .x = rb.x + 2, .y = rb.y + tag + pad + row * @as(f32, @floatFromInt(k)) - @as(f32, if (k >= 2) 2 else 0), .w = rb.w - 4, .h = row + @as(f32, if (k >= 2) 2 else 0) });
const regs_chrome = chrome(s, rb, false);
+ // The pins' lane under the free words: rsp's row's lifted with rsp, the rest with rbp.
+ var lane: [32]?anim.Obj = @splat(null);
+ for (2..@min(slots, 32)) |k| lane[k] = cover(s, .{ .x = sb.x + 2, .y = top + row * @as(f32, @floatFromInt(k)), .w = 116, .h = row });
+ const stack_chrome = chrome(s, sb, true);
// Chapter I's last picture: the address space, the words with their chains, the link standing.
const space = s.new(canim.Segments.init(s, rec, moment));
@@ -148,33 +156,57 @@ fn frame(s: *anim.Frame) void {
set(s, dump.left, 24);
const objs = .{ place(s, space), place(s, dump), place(s, tie) };
inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 });
- const main_word: canim.Rect = .{ .x = sb.x + canim.theme.metric.slot.address + 12 * 12 + canim.theme.metric.context.arrow_w, .y = rowY(top, rsp_after - 16, rsp + 8 * dump.walked), .w = 6 * 12, .h = row };
- const framed = place(s, s.new(Read{ .box = main_word }));
+
+ // main's rows, in the program column under II2's text; the aim joins them to the word.
+ const rsp_after = rec.register(moment + 1, "rsp");
+ const back_y = rowY(top, rsp_after - 16, rsp);
+ const main_rows = s.new(canim.descent.Caller{ .rec = rec, .at = moment, .call = rec.register(moment - 1, "rip"), .box = .{ .x = canim.theme.layout.program.x, .y = back_y + row / 2 + 176, .w = canim.theme.layout.program.w, .h = 4 * row }, .in = s.value(-1), .faint = s.value(0) });
+ s.play(.{place(s, main_rows).fadeIn()}, .{ .seconds = 0 });
+ const main_word: canim.Rect = .{ .x = sb.x + canim.theme.metric.slot.address + 12 * 12 + canim.theme.metric.context.arrow_w, .y = back_y, .w = @as(f32, @floatFromInt(canim.ui.digits(rec.register(moment - 1, "rip") + 5))) * 12, .h = row };
+ const word_frame = place(s, s.new(Read{ .box = main_word }));
+ const joins = ctx.ties(s);
+ s.play(.{joins.fadeIn()}, .{ .seconds = 0 });
var asides: canim.Asides = .{};
const left = canim.theme.canvas.margin_x;
// II1: the address space and the link fade (18 f); the words glide into
- // the stack's rows (36 f) and become the panel (12 f); then the push.
+ // the stack's rows (36 f) and become the panel (12 f).
s.wait(t.beat);
s.play(.{ objs[0].fadeOut(), objs[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear });
s.play(.{dump.become.to(1)}, .{ .seconds = f(36), .ease = anim.ease.linear });
- s.play(.{ ctx.stack.fadeIn(), objs[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear });
- asides.say(s, "`rsp` holds the address of the stack's top; a push moves it down a word.", left, rowY(top, first, rsp) + row / 2);
+ s.play(.{ stack.fadeIn(), objs[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear });
+ asides.say(s, "`rsp` holds the address of the top of the stack. A push moves it down a word.", left, rowY(top, first, rsp) + row / 2);
+ // rsp's row arrives over the stack (12 f), then its pin lands on the top word (12 f).
+ lift(s, &.{regs_rows[1]}, 0, 12);
+ lift(s, &.{lane[2]}, 0, 12);
+ s.wait(f(18));
at.walk(s, .moment, moment + 1);
s.wait(t.beat);
- // II2: the address the call pushed, and main's under it; the offsets, a column.
- asides.say(s, "Each call pushes where to come back to: `main+50` is main's.", left, main_word.y + row / 2);
- s.play(.{framed.fadeIn()}, .{ .seconds = f(6), .ease = anim.ease.linear });
- s.wait(f(24));
- lift(s, &offsets, 2, 12);
+ // II2: the way back main left, framed; main's rows; the aim; the offsets, a column.
+ asides.say(s, "A call pushes the address to come back to: here, `main+50`.", left, back_y + row / 2);
+ s.play(.{word_frame.fadeIn()}, .{ .seconds = f(6), .ease = anim.ease.linear });
+ s.wait(f(12));
+ run(s, main_rows.in, 12 + 2 * 2 + 12);
+ s.wait(f(6));
+ at.aim(s, .standing);
+ s.wait(f(30));
+ run(s, reveal.offsets, 2 * @as(f32, @floatFromInt(slots)) + 12);
s.wait(t.beat);
- // II3: a function's frame: rbp's pin, and the panel's tag, last.
- asides.say(s, "A function's words are its frame: saved rbp, locals, the way back.", left, rowY(top, rsp_after - 16, rec.register(moment + 1, "rbp")) + row / 2);
- s.play(.{framed.fadeOut()}, .{ .seconds = f(18), .ease = anim.ease.linear });
- s.cursor -= f(18);
- lift(s, &lane, 2, 12);
+ // II3: rbp's row and its pin; the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tag last.
+ const rsp_framed = rec.register(framed, "rsp");
+ const span_y = (rowY(top, rsp_framed - 16, rsp_framed) + rowY(top, rsp_framed - 16, rsp + 8)) / 2;
+ asides.say(s, "A function's words are its frame: the saved rbp, its locals, the way back.", left, span_y);
+ at.aim(s, .off);
+ s.play(.{ word_frame.fadeOut(), main_rows.faint.to(1) }, .{ .seconds = f(18), .ease = anim.ease.linear });
+ lift(s, &.{regs_rows[0]}, 0, 12);
+ lift(s, lane[3..], 2, 12);
+ s.wait(f(12));
+ at.walk(s, .moment, moment + 2);
+ at.walk(s, .moment, framed);
+ run(s, reveal.roles, 2 * @as(f32, @floatFromInt(slots)) + 12);
+ run(s, reveal.spans, 2 * 4 + 12);
s.wait(t.beat);
// `frame up`: its rules (12 f), then its tag and strip (12 f).
lift(s, stack_chrome[1..4], 0, 12);
@@ -183,8 +215,7 @@ fn frame(s: *anim.Frame) void {
// II4: the registers built over the stack, a row at a time, their tag last.
asides.say(s, "The registers are the other place values live: seventeen of them.", left, rb.y + tag + pad + row * 2.5);
- s.play(.{ctx.registers.fadeIn()}, .{ .seconds = 0 });
- lift(s, &regs_rows, 12, 12);
+ lift(s, regs_rows[2..], 12, 12);
lift(s, regs_chrome[1..4], 0, 12);
lift(s, &.{regs_chrome[0]}, 0, 12);
// The chapter's last picture.