From eab50d1c040774351f332a1568fa332c377860bd Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 12 Nov 2026 11:32:59 -0300 Subject: canim: the introduction as one video, with a chapter on registers From the user. One scene, intro, in four chapters: memory, registers, the stack, code and meaning (210 s). The registers chapter builds the panel before the stack needs it: sixteen rows with their chains, rip pinned on the code band and rsp and rbp on the stack's, rdi opened into its parts as mov edi changes one byte, a call to malloc stepped over with its result in rax, the registers a scene never changes folded. The chapters join at seams that say their title and keep it as the clock's label; one recording (from push(9), no agent, the heap from --heap) and one clock. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- anim/scenes/intro_stack.zig | 256 +++++++++++++++----------------------------- 1 file changed, 84 insertions(+), 172 deletions(-) (limited to 'anim/scenes/intro_stack.zig') diff --git a/anim/scenes/intro_stack.zig b/anim/scenes/intro_stack.zig index 378d624..3fb0213 100644 --- a/anim/scenes/intro_stack.zig +++ b/anim/scenes/intro_stack.zig @@ -1,121 +1,64 @@ -//! The introduction, chapter II: the stack (design/motion.md, "A scene: the -//! introduction", II1 to II4, here six beats; mock 31). It opens on chapter -//! I's last 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 four `free` over rsp, the window held -//! there so that nothing in the panel moves while the frame is made) and -//! become it; the convention said there (lower addresses drawn higher), the -//! offsets coming down the rows. rsp's and rbp's rows arrive over the stack, -//! rsp's pin landing on the top word. The call first: 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`, drawn head first, -//! standing at 60% through the push). Then reverse's first rows under -//! main's (the disassembly) and `push rbp` walked: the pc's mark on its -//! row, the touch to the word, rbp's value carried to it and struck, rsp's -//! pin climbing. `mov rbp, rsp` and `sub rsp` walked: the frame; its roles -//! (the way back named) and spans, a `column` each, the panels' tags 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, -//! over the code. +//! The introduction, chapter III: the stack (design/motion.md, "A scene: +//! the introduction", III1 to III5; mock 31), a function the scene `intro` +//! calls after II's seam. It goes on from chapter II's last picture, on +//! II's context (its registers, folded to the scene's one set; reverse's +//! rows at the program column's foot, no panel round them; the clock): the +//! 128 bytes, back at the rows II gave them, become the stack panel where +//! they stand (sixteen words and four `free` over rsp, the window held +//! there so that nothing in the panel moves while the frame is made); the +//! convention said there (lower addresses drawn higher), the offsets coming +//! down the rows; rsp's pin landing on the top word and its link to it. The +//! call first: 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`, drawn head first, standing at 60% through the push). +//! Then `push rbp` walked: the pc's mark on its row, the touch to the word, +//! rbp's value carried to it and struck, rsp's pin climbing. `mov rbp, rsp` +//! and `sub rsp` walked: the frame; its roles (the way back named) and +//! spans, a `column` each, the panels' tags last (`frame up`). The text +//! stands beside on the left, in the program column, over the code. //! -//! What a beat has not reached yet is under the page (`Cover`, and the +//! What a beat has not reached yet is under the page (`intro.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"); const canim = @import("canim"); -const recordings = @import("recordings"); - -pub const background = canim.background; -pub const scene = anim.Live(frame, struct {}); +const intro = @import("intro.zig"); +const registers = @import("intro_registers.zig"); const t = canim.theme.time; const row = canim.theme.metric.context.row; -const tag = canim.theme.metric.context.tag; -const pad = canim.theme.metric.context.pad; - -fn f(frames: f32) f32 { - return frames / 60; -} - -fn place(s: *anim.Frame, data: anytype) anim.Obj { - return s.custom(data, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); -} - -/// The page over a part of a panel the beat has not reached: lifted (its fade out) as the beat says it. -const Cover = struct { - box: canim.Rect, - pub fn draw(c: *const Cover, fr: *sk.Frame, placed: anim.Placed) void { - (canim.ui.Ui{ .f = fr, .at = placed }).fill(c.box, canim.theme.color.page); +const f = intro.f; +const run = intro.run; +const place = intro.place; +const cover = intro.cover; +const lift = intro.lift; + +/// The chapter's last picture, which chapter IV opens on. +pub const Three = struct { + /// The state column (the registers, the stack) and the code (main's rows, reverse's, the ties). + state: [2]anim.Obj, + code: [3]anim.Obj, + clock: anim.Obj, + /// The cursor the clock counts on (II's and III's). + at: canim.Cursor, + asides: canim.Asides, + e: f32, + + pub fn texts(three: *const Three, s: *anim.Frame) []const anim.Obj { + return registers.standing(s, &three.asides); } }; -/// A value framed as read (6 f in with its object's fade). -const Read = struct { - box: canim.Rect, - pub fn draw(r: *const Read, fr: *sk.Frame, placed: anim.Placed) void { - (canim.ui.Ui{ .f = fr, .at = placed }).read(r.box, 1); - } -}; - -fn cover(s: *anim.Frame, box: canim.Rect) anim.Obj { - const o = place(s, s.new(Cover{ .box = box })); - s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - return o; -} - -/// A panel's tag and rules under the page, for `frame up`. -fn chrome(s: *anim.Frame, b: canim.Rect, strip: bool) [5]?anim.Obj { - const w = canim.theme.stroke.rule; - return .{ - cover(s, .{ .x = b.x, .y = b.y, .w = b.w, .h = tag }), - cover(s, .{ .x = b.x, .y = b.y + tag, .w = w, .h = b.h - tag }), - cover(s, .{ .x = b.x + b.w - w, .y = b.y + tag, .w = w, .h = b.h - tag }), - cover(s, .{ .x = b.x, .y = b.y + b.h - w, .w = b.w, .h = w }), - if (strip) cover(s, .{ .x = b.x + b.w - canim.theme.strip.cost, .y = b.y + tag, .w = canim.theme.strip.cost - w, .h = b.h - tag - w }) else null, - }; -} - -/// Lifts `covers` one after another, `apart` frames apart, `each` frames each, from the cursor; the cursor after the last. -fn lift(s: *anim.Frame, covers: []const ?anim.Obj, apart: f32, each: f32) void { - const at = s.cursor; - var end = at; - for (covers, 0..) |o, i| if (o) |obj| { - s.cursor = at + f(apart * @as(f32, @floatFromInt(i))); - s.play(.{obj.fadeOut()}, .{ .seconds = f(each), .ease = anim.ease.linear }); - end = s.cursor; - }; - s.cursor = end; -} - -/// 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.intro); - const reverse = rec.call("reverse", 0); +/// From the seam's opening (the cursor), on chapter II's context. +pub fn chapter(s: *anim.Frame, rec: *canim.Recording, two: registers.Two, title: intro.Title) Three { + const ctx = two.ctx; + var at = two.at; // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x18`. - const moment = reverse.enter; + const moment = rec.call("reverse", 0).enter; const framed = moment + 3; - var at = canim.cursor(s, rec, moment); - at.journey(.moment, framed); - at.levels = .{ .fire = .disasm, .source_rows = 14, .introduction = true }; - var split = canim.layout.split.none; - split.backtrace.h = 0; - const ctx = canim.context(s, at, .{ .split = split }); const g = layout(ctx.stage, rec, moment); const sb = g.stack; - const rb = ctx.stage.first.registers; const rsp = g.rsp; const first = g.first; const top = g.top; @@ -123,78 +66,57 @@ fn frame(s: *anim.Frame) void { // The window held where it is, four `free` words over rsp: the push and `sub rsp` fill them. hold(s, ctx.stage, moment); - // 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. // (Rows 4 f apart: the offsets come down while the convention is read.) const reveal: canim.Stack.Reveal = .{ .offsets = s.value(-1), .roles = s.value(-1), .spans = s.value(-1), .apart = 4 }; 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| - // (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: rsp's row's lifted with rsp, the rest (rbp's pin) with the push. var lane: [32]?anim.Obj = @splat(null); const rsp_row: usize = held_free; for (0..@min(slots, 32)) |k| lane[k] = cover(s, .{ .x = sb.x + 2, .y = top + row * @as(f32, @floatFromInt(k)), .w = canim.theme.metric.slot.lane_end - 2, .h = row }); - const stack_chrome = chrome(s, sb, true); - // Reverse's first rows, the disassembly under main's: its rows with the push, its tag and strip last. - const disasm_chrome = chrome(s, ctx.stage.first.disasm, true); + const stack_chrome = intro.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)); - const dump = s.new(canim.Words.init(s, rec, moment)); + // The 128 bytes become the stack's rows where they stand (II8 put them there). + const dump = two.dump; dump.panel = .{ .x = sb.x, .top = top, .first = first }; - const at_ = canim.regroup.at; - const tie = s.new(canim.segments.Place{ .segments = space, .addr = rsp, .x = at_.bracket, .y0 = at_.top + 2, .y1 = at_.top + 16 * 24 - 2, .clock = s.value(60), .quiet = s.value(24) }); - for ([_]anim.Value{ space.form, dump.placed }) |v| set(s, v, 1); - set(s, space.whole, 999); - for (space.rides) |v| set(s, v, 999); - for ([_]anim.Value{ dump.in, dump.ink, dump.chains }) |v| set(s, v, 999); - set(s, dump.regroup, canim.regroup.regroup_frames); - 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 }); + // (Over the page that covers the stack's lane: the addresses travel across it.) + const dump_obj = place(s, dump); // main's rows, in the program column over reverse's; the aim joins them to the word. const back_y = rowY(top, first, rsp); const main_rows = s.new(canim.descent.Caller{ .rec = rec, .at = moment, .call = rec.register(moment - 1, "rip"), .box = g.caller, .in = s.value(-1), .faint = s.value(0) }); - s.play(.{place(s, main_rows).fadeIn()}, .{ .seconds = 0 }); + const caller = place(s, main_rows); 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 })); - // The relations, and rsp's link to its word as II2 names it. + const word_frame = place(s, s.new(intro.Read{ .box = main_word })); + // The relations, and rsp's link to its word as III2 names it. const joins, const rsp_link = ctx.tiesWith(s, "rsp", 1.0); - s.play(.{joins.fadeIn()}, .{ .seconds = 0 }); + const opening = s.cursor; + s.play(.{ caller.fadeIn(), joins.fadeIn(), two.dump_obj.fadeOut(), dump_obj.fadeIn() }, .{ .seconds = 0 }); + s.cursor = opening; 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). Where it first - // stands, its convention said, unlike the bar's: the offsets come down - // its rows (a column, 4 f apart), growing as the addresses do. - s.wait(t.beat); - s.play(.{ objs[0].fadeOut(), objs[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear }); + // The opening (126 to 174): the bytes fade, the addresses and the words glide into the + // stack's rows (36 f) and become the panel (12 f). Where it first stands, its convention + // said, unlike the bar's: the offsets come down its rows (a column, 4 f apart). s.play(.{dump.become.to(1)}, .{ .seconds = f(36), .ease = anim.ease.linear }); - s.play(.{ stack.fadeIn(), objs[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.play(.{ stack.fadeIn(), dump_obj.fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + title.out(s); asides.say(s, texts[0], left, rowY(top, first, first) + row / 2); const column = reveal.apart * @as(f32, @floatFromInt(slots)) + 12; run(s, reveal.offsets, column); s.wait(t.beat); - // II2: rsp's and rbp's rows arrive over the stack (12 f), rsp's pin lands on the top word (12 f), - // then rsp's link from its row down to the word, held, drawn back. + // III2: rsp's pin lands on the top word (12 f), then rsp's link from its row down to the + // word, held, drawn back. Its row was built in II: nothing arrives. asides.say(s, texts[1], left, back_y + row / 2); - lift(s, &.{ regs_rows[0], regs_rows[1] }, 0, 12); lift(s, &.{lane[rsp_row]}, 0, 12); rsp_link.play(s); s.wait(rsp_link.total()); s.wait(f(18)); s.wait(t.beat); - // II3: the call, first: the way back main left, framed; main's rows; the aim drawn to its row. + // III3: the call, first: the way back main left, framed; main's rows; the aim drawn to its row. asides.say(s, texts[2], left, back_y + row / 2); s.play(.{word_frame.fadeIn()}, .{ .seconds = f(6), .ease = anim.ease.linear }); s.wait(f(12)); @@ -204,12 +126,11 @@ fn frame(s: *anim.Frame) void { s.wait(f(24 + 30)); s.wait(t.beat); - // II4: the push: reverse's first rows under main's, rbp's pin; `push rbp` walked - // (its row fires, the touch to the word, rbp's value carried there and struck, rsp's pin climbing). + // III4: the push: rbp's pin; `push rbp` walked (its row fires, the touch to the word, + // rbp's value carried there and struck, rsp's pin climbing). Reverse's rows are on screen since II. asides.say(s, texts[3], left, rowY(top, first, rsp - 8) + row / 2); at.aim(s, .standing); s.play(.{ word_frame.fadeOut(), main_rows.faint.to(1) }, .{ .seconds = f(18), .ease = anim.ease.linear }); - s.play(.{ctx.disasm.fadeIn()}, .{ .seconds = f(12), .ease = anim.ease.linear }); var lanes: [32]?anim.Obj = lane; lanes[rsp_row] = null; lift(s, &lanes, 0, 12); @@ -219,7 +140,7 @@ fn frame(s: *anim.Frame) void { at.levels.carry = .off; s.wait(t.beat); - // II5: the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tags last. + // III5: the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tags last. asides.say(s, texts[4], left, g.span_y); at.aim(s, .off); at.walk(s, .moment, moment + 2); @@ -229,48 +150,40 @@ fn frame(s: *anim.Frame) void { s.wait(t.beat); // `frame up`: the rules (12 f), then the tags and strips (12 f). const at_rules = s.cursor; - lift(s, disasm_chrome[1..4], 0, 12); + lift(s, two.disasm_chrome[1..4], 0, 12); s.cursor = at_rules; lift(s, stack_chrome[1..4], 0, 12); const at_tags = s.cursor; - lift(s, &.{ disasm_chrome[0], disasm_chrome[4] }, 0, 12); + lift(s, &.{ two.disasm_chrome[0], two.disasm_chrome[4] }, 0, 12); s.cursor = at_tags; lift(s, &.{ stack_chrome[0], stack_chrome[4] }, 0, 12); - s.wait(t.beat); - - // II6: the registers built over the stack, a row at a time, their tag last. - asides.say(s, texts[5], left, g.registers_y); - 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. + // The chapter's last picture, held until its last text is read: then the seam. s.wait(@max(asides.read_by - s.cursor, 0)); - s.wait(t.before_cut); + return .{ .state = .{ two.registers, stack }, .code = .{ caller, two.disasm, joins }, .clock = two.clock, .at = at, .asides = asides, .e = s.cursor }; } -/// The chapter's texts, in order (chapter III opens on the last two). +/// The chapter's texts, in order. pub const texts = [_][]const u8{ "Here lower addresses are drawn higher: down a word is up a row.", "`rsp` holds the address of the top of the stack.", "A call pushes the address to come back to: here, `main+50`.", "A push moves `rsp` down a word and stores there: `push rbp` keeps the caller's `rbp`.", "`rbp` marks the frame's base. A function's words are its frame: the saved rbp, its locals, the way back.", - "The registers are the other place values live: seventeen of them.", }; /// Free words over rsp in the held window. -pub const held_free = 4; +const held_free = 4; -/// The stack's window held from the first frame (no scroll to it), `held_free` words over rsp at `moment`. -pub fn hold(s: *anim.Frame, stage: *canim.Stage, moment: u64) void { +/// The stack's window held from here (no scroll to it), `held_free` words over rsp at `moment`. +fn hold(s: *anim.Frame, stage: *canim.Stage, moment: u64) void { s.play(.{ stage.hold.to(@floatFromInt(moment)), stage.hold_free.to(held_free), stage.hold_in.to(1) }, .{ .seconds = 0 }); } -/// Where the chapter's parts stand (chapter III opens on its last picture, -/// laid out the same): the stack under the registers, its window from -/// `first` (four free words over rsp), its rows from `top`; main's rows -/// in the program column level with the lower stack, reverse's under them. -pub fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { stack: canim.Rect, rsp: u64, first: u64, top: f32, caller: canim.Rect, span_y: f32, registers_y: f32 } { +/// Where the chapter's parts stand: the stack under the registers' eleven +/// rows (356 to 868), its window from `first` (four free words over rsp), +/// its rows from `top`; main's rows in the program column (604 to 700) over +/// reverse's six, where chapter II put them (712 to 888). +fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { stack: canim.Rect, rsp: u64, first: u64, top: f32, caller: canim.Rect, span_y: f32 } { const rb = stage.first.registers; // Sixteen slots and the headroom under the registers' box (the words // become them where they stand), not the column's rest. @@ -279,12 +192,11 @@ pub fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { const sb = stage.first.stack; const rsp = rec.register(moment, "rsp"); const first = rsp - 8 * held_free; - const top = sb.y + tag + pad; - const caller: canim.Rect = .{ .x = canim.theme.layout.program.x, .y = rowY(top, first, rsp) + row / 2 + 152, .w = canim.theme.layout.program.w, .h = 4 * row }; - // Seven rows: reverse's from its first, which none of the chapter's steps scrolls away. - stage.first.disasm = .{ .x = caller.x, .y = caller.y + caller.h + canim.theme.canvas.row_gap, .w = caller.w, .h = canim.layout.panelH(7) }; + const top = sb.y + canim.theme.metric.context.tag + canim.theme.metric.context.pad; + const code = stage.first.disasm; + const caller: canim.Rect = .{ .x = code.x, .y = code.y - canim.theme.canvas.row_gap - 4 * row, .w = code.w, .h = 4 * row }; const rsp_framed = rec.register(moment + 3, "rsp"); - return .{ .stack = sb, .rsp = rsp, .first = first, .top = top, .caller = caller, .span_y = (rowY(top, first, rsp_framed) + rowY(top, first, rsp + 8)) / 2, .registers_y = rb.y + tag + pad + row * 2.5 }; + return .{ .stack = sb, .rsp = rsp, .first = first, .top = top, .caller = caller, .span_y = (rowY(top, first, rsp_framed) + rowY(top, first, rsp + 8)) / 2 }; } fn rowY(t0: f32, from: u64, addr: u64) f32 { -- cgit v1.3