From 4907e35bc45d12102d0e09380994814fc2e0a369 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 12 Nov 2026 04:45:57 -0300 Subject: canim: the introduction, from the review The introduction records the plain build (clang -O0, no instrumentation), so reverse's frame is the compiler's own push, mov and sub. The stack chapter says its convention once and keeps four free words over rsp so a push moves the pin and nothing else; reverse's rows stand under main's and are stepped, each touching its word, the call before the push, the aim drawn head first to the row it returns to. The close-up frames the bytes and the stack together with their 128 bytes marked. Nothing is named before it is shown; offsets are written in hex as the operands are; the dump folds into its tag; the map is announced before it is shown. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- anim/scenes/intro_code.zig | 102 ++++++++++++----------- anim/scenes/intro_memory.zig | 49 +++++++---- anim/scenes/intro_stack.zig | 190 +++++++++++++++++++++++++++++-------------- 3 files changed, 216 insertions(+), 125 deletions(-) (limited to 'anim/scenes') diff --git a/anim/scenes/intro_code.zig b/anim/scenes/intro_code.zig index b50c971..cbfa36b 100644 --- a/anim/scenes/intro_code.zig +++ b/anim/scenes/intro_code.zig @@ -6,13 +6,16 @@ //! of `aligned` (`interleaved`), its neighbours at a run, each line level //! with its run; then `align` to `columns`; then the working frame with the //! nodes drawn from the heap's bytes, each pane's minimap drawing itself -//! last; then the map (`surface`). The texts `above` the aligned panel, -//! then below the working frame, and the last one on the map. +//! last; then the map (`surface`). It opens on chapter II's last picture, +//! its state column staying veiled until the decoded code spans it. The +//! texts `above` the aligned panel, then below the working frame, the +//! last landing before the map surfaces under it. const std = @import("std"); const anim = @import("anim"); const sk = @import("sketch"); const canim = @import("canim"); const recordings = @import("recordings"); +const two = @import("intro_stack.zig"); pub const background = canim.background; pub const scene = anim.Live(frame, struct {}); @@ -45,43 +48,33 @@ const Page = struct { /// Chapter II's last picture (scenes/intro_stack.zig, its layout and texts /// as there): its registers and stack, a context of their own at II's last -/// moment; main's rows, faint; II3's text dimmed and II4's. -fn lastOfTwo(s: *anim.Frame, rec: *canim.Recording) struct { panels: [3]anim.Obj, texts: [2]anim.Obj } { +/// moment, the window held as II holds it; main's rows, faint, and reverse's +/// first rows under them; II4's text dimmed and II5's. +fn lastOfTwo(s: *anim.Frame, rec: *canim.Recording) struct { state: [2]anim.Obj, code: [2]anim.Obj, texts: [2]anim.Obj } { const enter = rec.call("reverse", 0).enter; const last = enter + 3; - const row = canim.theme.metric.context.row; - const head = canim.theme.metric.context.tag + canim.theme.metric.context.pad; var at = canim.cursor(s, rec, enter); at.journey(.moment, last); - at.levels = .{ .fire = .disasm, .source_rows = 14 }; - at.jump(s, last); + at.levels = .{ .fire = .disasm, .source_rows = 14, .introduction = true }; + // As II walked it: its push, `mov` and `sub` the steps behind its last moment. + at.jumpWalked(s, enter, last); var split = canim.layout.split.none; split.backtrace.h = 0; const ctx = canim.context(s, at, .{ .split = split }); - 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 top = ctx.stage.first.stack.y + head; - const rsp = rec.register(enter, "rsp"); - const window = rec.register(last, "rsp") - 16; - const rowY = struct { - fn y(t0: f32, from: u64, addr: u64) f32 { - return t0 + row * @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% from)) >> 3)); - } - }.y; + const g = two.layout(ctx.stage, rec, enter); + two.hold(s, ctx.stage, enter); const stack = canim.add(s, canim.Stack{ .cursor = ctx.cursor, .stage = ctx.stage }); - const back_y = rowY(top, rsp - 8 - 16, rsp); // (Placed at the origin: it draws at its own box.) - const caller = s.custom(s.new(canim.descent.Caller{ .rec = rec, .at = enter, .call = rec.register(enter - 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(999), .faint = s.value(1) }), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); + const caller = s.custom(s.new(canim.descent.Caller{ .rec = rec, .at = enter, .call = rec.register(enter - 1, "rip"), .box = g.caller, .in = s.value(999), .faint = s.value(1) }), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); const left = canim.theme.canvas.margin_x; const said = [2]canim.Aside{ - .{ .text = "A function's words are its frame: the saved rbp, its locals, the way back.", .x = left, .level = (rowY(top, window, window + 16) + rowY(top, window, rsp + 8)) / 2, .dim = s.value(1) }, - .{ .text = "The registers are the other place values live: seventeen of them.", .x = left, .level = rb.y + head + row * 2.5, .dim = s.value(0) }, + .{ .text = two.texts[two.texts.len - 2], .x = left, .level = g.span_y, .dim = s.value(1) }, + .{ .text = two.texts[two.texts.len - 1], .x = left, .level = g.registers_y, .dim = s.value(0) }, }; var texts: [2]anim.Obj = undefined; for (said, &texts) |a, *o| o.* = s.custom(s.new(a), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); - for ([_]anim.Obj{ ctx.registers, stack, caller, texts[0], texts[1] }) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - return .{ .panels = .{ ctx.registers, stack, caller }, .texts = texts }; + for ([_]anim.Obj{ ctx.registers, stack, caller, ctx.disasm, texts[0], texts[1] }) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + return .{ .state = .{ ctx.registers, stack }, .code = .{ caller, ctx.disasm }, .texts = texts }; } /// The variables whose tags the nodes carry, as the list scene's. @@ -89,6 +82,10 @@ const tracked = [_][]const u8{ "prev", "cur", "next", "head" }; fn frame(s: *anim.Frame) void { const rec = canim.open(recordings.intro); + // list.c's types as the pass would tell them: the recording is of the + // plain build, which tells none (its locals are the debug info's). + rec.declare("head", "*`struct node`"); + rec.declare("`struct node`", "struct(16){value@0:i64;next@8:*`struct node`;}"); const reverse = rec.call("reverse", 0); // The load: `cur->next` read, line 21's second instruction. const moment = on(rec, rec.lineMoment(21, reverse.enter), "[rax + 8]"); @@ -109,11 +106,12 @@ fn frame(s: *anim.Frame) void { var at = canim.cursor(s, rec, moment); at.journey(.moment, moment + 1); - at.levels = .{ .idea = .data, .follow = t.move, .source_rows = 8 }; + at.levels = .{ .idea = .data, .follow = t.move, .source_rows = 8, .introduction = true }; const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject }); - const list = canim.nodes(s, .{ .cursor = at, .stage = ctx.stage, .root = "head", .track = &tracked }); - ctx.map.add(s, canim.Nodes{ .cursor = at, .stage = ctx.map.stage, .root = "head", .track = &tracked }); - const joins = ctx.ties(s); + const list = canim.nodes(s, .{ .cursor = at, .stage = ctx.stage, .root = "head", .track = &tracked, .named = true }); + ctx.map.add(s, canim.Nodes{ .cursor = at, .stage = ctx.map.stage, .root = "head", .track = &tracked, .named = true }); + // The relations, and rax's link to the node as III3 names it. + const joins, const rax_link = ctx.tiesWith(s, "rax", 1.0); // Each pane's minimap under the page until III4, where they draw themselves last, top down // (over the panels, under the aligned rows landing on them; on from the panels' first frame). @@ -125,15 +123,17 @@ fn frame(s: *anim.Frame) void { const al = s.new(canim.Aligned.init(s, rec, moment)); const panel = s.custom(al, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); s.play(.{panel.fadeIn()}, .{ .seconds = 0 }); - var asides: canim.Asides = .{}; + // Texts above the panel that spans both columns: twice a beside's line (two lines in the band of 120). + var asides: canim.Asides = .{ .wrap = 2 * 40 }; const left = canim.theme.canvas.margin_x; const above = canim.theme.canvas.stage.y + 40; - // From II's last picture: it gives way (its texts 12 f, the rest 18 f), the stage clear for the code. + // From II's last picture: its texts and code give way (12 f, 18 f); its + // state column stays, veiled at 50%, until the decoded code takes both columns. s.wait(t.beat); s.play(.{ opening.texts[0].fadeOut(), opening.texts[1].fadeOut() }, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); s.cursor -= t.caption_out; - s.play(.{ opening.panels[0].fadeOut(), opening.panels[1].fadeOut(), opening.panels[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear }); + s.play(.{ opening.code[0].fadeOut(), opening.code[1].fadeOut(), opening.state[0].move(.{ .opacity = 0.5 }), opening.state[1].move(.{ .opacity = 0.5 }) }, .{ .seconds = f(18), .ease = anim.ease.linear }); s.wait(t.beat); // III1: the code's bytes, one instruction's framed. @@ -142,16 +142,23 @@ fn frame(s: *anim.Frame) void { run(s, al.bytes, 12 + 2 * 15 + 12 + 6); s.wait(t.beat); - // III2: decoded into its row, its neighbours at a run, each line level with its run. - asides.say(s, std.fmt.allocPrint(s.arena, "Decoded: `{s}`, from line {d}. Each line sits level with its code.", .{ text, insn.line orelse 0 }) catch "", left, above); + // III2: decoded into its row, its neighbours at a run, each line heading its run. + asides.say(s, std.fmt.allocPrint(s.arena, "Decoded: `{s}`, from line {d}. Each line heads the instructions it compiled to.", .{ text, insn.line orelse 0 }) catch "", left, above); + // II's state column goes as the decoded rows come to span it (12 f). + s.play(.{ opening.state[0].fadeOut(), opening.state[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.cursor -= f(12); run(s, al.decode, 60); - run(s, al.rows_in, 2 * 32 + 8); + // The neighbours at half the run's pace (rows 4 f apart): they come while the text is read. + s.play(.{al.rows_in.to(0)}, .{ .seconds = 0 }); + s.play(.{al.rows_in.to(2 * 32 + 8)}, .{ .seconds = 2 * f(2 * 32 + 8), .ease = anim.ease.linear }); run(s, al.chrome, 24); s.wait(t.beat); // III2, the other form: two columns, each line level with the first of its instructions. - asides.say(s, "Two columns: each line level with its first instruction.", left, above); - run(s, al.form, 80); + asides.say(s, "Two columns: each line by its first instruction. A square after `]`: a byte it touches.", left, above); + // `align` at two thirds of its pace (120 f for 80): the two columns come while the text is read. + s.play(.{al.form.to(0)}, .{ .seconds = 0 }); + s.play(.{al.form.to(80)}, .{ .seconds = f(120), .ease = anim.ease.linear }); s.wait(t.beat); // Into the working frame: the texts above leave; `stack`: the lines glide to @@ -168,7 +175,7 @@ fn frame(s: *anim.Frame) void { // III3: the node it reads, as bytes and drawn: the band comes in, its // elements rising from their bytes. No camera: at x1.5 the drawing's // nodes and its bytes do not both fit the frame, and the band is whole at x1. - says.line(s, "`rax` points at a list node on the heap:\nits bytes, and drawn, the node."); + says.line(s, "Later, at line 21, `rax` points at a list node on the heap:\nits bytes, and drawn, the node."); // The heap's dump first, in the band's right half (18 f); then the nodes drawn from it, rising (`establish`). s.play(.{ctx.stage.drawing.to(0)}, .{ .seconds = 0 }); s.play(.{list.fadeIn()}, .{ .seconds = f(18), .ease = anim.ease.linear }); @@ -177,20 +184,21 @@ fn frame(s: *anim.Frame) void { s.cursor -= f(12); ctx.establish(s, .{}, 3); s.wait(t.beat); - // III4: the whole frame; each pane's minimap draws itself, last, top down (24 f, 48 f apart). - says.line(s, "This is the whole frame.\nEvery view in it is these same bytes."); + // rax framed as read, its link up to the node it points at, held, drawn back. + rax_link.play(s); + s.wait(rax_link.total()); + s.wait(t.beat); + // III4: the whole frame; each pane's minimap draws itself, last, top down (24 f, 72 f apart: while the text is read). + says.line(s, "This is the whole frame. Every view in it is these same bytes;\neach strip, the whole of its pane."); const strips_from = s.cursor; for (strips, 0..) |o, k| { - s.cursor = strips_from + f(48 * @as(f32, @floatFromInt(k))); + s.cursor = strips_from + f(72 * @as(f32, @floatFromInt(k))); s.play(.{o.fadeOut()}, .{ .seconds = f(24), .ease = anim.ease.linear }); } s.wait(t.beat); - // III5: the map, and its text on it, in the key's corner (the middle column's foot, empty on this map). - s.wait(@max(says.read_by - s.cursor, 0)); - s.play(.{says.current.?.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); - s.wait(t.caption_gap); + // III5: its text lands before the move, under the map as under the frame; then `surface`. + says.line(s, "And all of it at once: the map."); ctx.map.surface(s); - asides.say(s, "And all of it at once:\nthe map.", 528, 720); - s.wait(@max(asides.read_by - s.cursor, 0)); + s.wait(@max(says.read_by - s.cursor, 0)); s.wait(t.before_cut); } diff --git a/anim/scenes/intro_memory.zig b/anim/scenes/intro_memory.zig index 7aec267..2dfda5e 100644 --- a/anim/scenes/intro_memory.zig +++ b/anim/scenes/intro_memory.zig @@ -8,7 +8,8 @@ //! made words (`regroup`); three of them addresses; then the address space //! to scale in the program column (`segments`), each cluster enlarged, its //! text beside it; back to the working frame, the dump tied to its place, -//! a visit at x4, `ink`, and three chains. +//! a visit at x2 framing the stack's box and the dump's top rows together +//! (the place marked `128 bytes` on the box), `ink`, and three chains. const std = @import("std"); const anim = @import("anim"); const canim = @import("canim"); @@ -45,7 +46,7 @@ fn frame(s: *anim.Frame) void { const space = s.new(canim.Segments.init(s, rec, moment)); const dump = s.new(canim.Words.init(s, rec, moment)); - const place = s.new(canim.segments.Place{ .segments = space, .addr = rec.register(moment, "rsp"), .x = at.bracket, .y0 = at.top + 2, .y1 = at.top + 16 * 24 - 2, .clock = s.value(-1), .quiet = s.value(0) }); + const place = s.new(canim.segments.Place{ .segments = space, .addr = rec.register(moment, "rsp"), .x = at.bracket, .y0 = at.top + 2, .y1 = at.top + 16 * 24 - 2, .clock = s.value(-1), .quiet = s.value(0), .tick = s.value(0) }); // `ink`'s echoes: the walked word's band first, then the rest at a run, 2 f apart. const values = canim.Words.read(rec, moment); @@ -64,8 +65,10 @@ fn frame(s: *anim.Frame) void { const objs = .{ s.custom(space, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(dump, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(place, .{ .x = -640, .y = -360, .scale = ui.scale }) }; inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - // The camera at x2 on the dump from the first frame (I1 to I3). - const near = ui.framing(.{ .x = 888, .y = 72, .w = 896, .h = 408 }, 2); + // The camera at x2 on the dump from the first frame (I1 to I3), with the + // room over it that the walked word's bytes and offsets fly in, and its + // sixteen rows over the stage's foot. + const near = ui.framing(.{ .x = 888, .y = 66, .w = 896, .h = 408 }, 2); var cam: canim.Camera = .{}; cam.moves[0] = .{ .from = near, .to = near, .p = s.value(1) }; cam.count = 1; @@ -73,15 +76,20 @@ fn frame(s: *anim.Frame) void { var says: canim.Narrator = .{}; var asides: canim.Asides = .{}; - // I1: the bytes, a row at a time. + // I1: the bytes, a row at a time (18 f apart), a text's lead (60 f) after it lands, not + // the first's 120: little "here" over an empty stage, and they come while it is read. s.wait(1.0); - says.line(s, "A running program is bytes in memory:\nhere, 128 of them at the top of the stack."); - run(s, dump.in, 7 * 12 + 18); + const said_at = s.cursor; + says.line(s, "A running program is bytes in memory:\nhere are 128 of them."); + const lead_end = s.cursor; + s.cursor = said_at + t.caption_in + t.caption_lead; + run(s, dump.in, 7 * canim.regroup.rows_apart + 18); + s.cursor = @max(s.cursor, lead_end); s.wait(t.beat); // I2: eight a row; the return address walked, the other fifteen at a run. says.line(s, "Eight bytes make a word, stored low byte first:\nthe lowest byte is its last two digits."); - run(s, dump.regroup, 386); + run(s, dump.regroup, canim.regroup.regroup_frames); s.wait(t.beat); // I3: three words that hold addresses, framed as read. @@ -94,7 +102,7 @@ fn frame(s: *anim.Frame) void { says.current = canim.caption(s, ""); s.wait(t.caption_gap); cam.back(s, .{}); - run(s, dump.fold, 30); + run(s, dump.fold, 48); // Folded, the three frames go with the rows: unfolded, the dump is plain words again. s.play(.{dump.framed.to(-1)}, .{ .seconds = 0 }); @@ -109,7 +117,7 @@ fn frame(s: *anim.Frame) void { const clusters = @min(l.space.clusters.len, 6); var top_end: usize = 0; while (top_end < clusters and l.space.clusters[top_end].lo > canim.segments.user_end / 2) top_end += 1; - asides.say(s, "Enlarged, the top end: the stack, then the libraries, each band with its addresses and size.", column_x, l.boxes[0].y + 12); + asides.say(s, "Enlarged, the top end: the stack, then the libraries, each file with its addresses and size.", column_x, l.boxes[0].y + 12); for (0..top_end) |i| { start(s, space.rides[i], 6 + 72 + 90 + 2 * 12 + 12); s.wait(f(78)); @@ -125,21 +133,28 @@ fn frame(s: *anim.Frame) void { // Back to the working frame: the texts leave, the drawing to the stage's height, the dump unfolds. asides.leave(s); s.play(.{space.form.to(1)}, .{ .seconds = f(24), .ease = anim.ease.linear }); - s.play(.{dump.fold.to(0)}, .{ .seconds = f(30), .ease = anim.ease.linear }); + s.play(.{dump.fold.to(0)}, .{ .seconds = f(48), .ease = anim.ease.linear }); // I7: the dump's place: the tie bracket, the link onto the stack's box. says.line(s, "These 128 bytes are here,\nat the very top of the stack."); - s.play(.{dump.placed.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); - s.cursor -= f(12); + // The rows' addresses take the stack's ink as the link's head lands and its band is framed (42), 12 f. + const placing = s.cursor; run(s, place.clock, 60); + const placed_at = s.cursor; + s.cursor = placing + f(42); + s.play(.{dump.placed.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.cursor = placed_at; s.wait(t.beat); // I8: a visit at x4 to where the link lands, and back. says.line(s, "Were the bar the Eiffel Tower,\nthey would be an atom thick, at its top."); + // At x2: the stack's box with its names, the link, and the dump's top rows to a byte's edge, + // the place marked on the box (`128 bytes`), nothing cut at the frame's edge but the rows running on. const landed = space.layout(1, s.arena); - const head = canim.Segments.place(landed, place.addr) orelse .{ 0, 0 }; - cam.go(s, .{ .x = head[0] - 112, .y = 48, .w = 224, .h = 104 }, 4, .{}); - s.wait(t.beat); + cam.go(s, .{ .x = 280, .y = 44, .w = 960, .h = 448 }, 2, .{}); + s.play(.{place.tick.?.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.wait(1.0); + s.play(.{place.tick.?.to(0)}, .{ .seconds = f(12), .ease = anim.ease.linear }); cam.back(s, .{}); // I9: `ink`: the return address walked, its band framed; the rest at a run; the link quiets. @@ -164,7 +179,7 @@ fn frame(s: *anim.Frame) void { s.wait(t.beat); // I10: the words to their field's left, then three chains, walked. - says.line(s, "Follow an address and you reach another word:\na chain."); + says.line(s, "Follow an address and you reach another word: a chain.\n`→` points to a word, `←` holds a value."); run(s, dump.left, 24); run(s, dump.chains, 36 * 2 + 30); s.wait(t.beat); diff --git a/anim/scenes/intro_stack.zig b/anim/scenes/intro_stack.zig index 49162e6..378d624 100644 --- a/anim/scenes/intro_stack.zig +++ b/anim/scenes/intro_stack.zig @@ -1,18 +1,23 @@ //! 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 `intro` recording (reverse's first -//! instruction, its `push rbp`): the address space and the dump's link +//! 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 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. +//! 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. //! //! 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 @@ -99,36 +104,30 @@ fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { fn frame(s: *anim.Frame) void { const rec = canim.open(recordings.intro); const reverse = rec.call("reverse", 0); - // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x20`. + // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x18`. const moment = reverse.enter; const framed = moment + 3; var at = canim.cursor(s, rec, moment); at.journey(.moment, framed); - at.levels = .{ .fire = .disasm, .source_rows = 14 }; + 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 }); - // Sixteen slots and the headroom under the registers' box (the words - // become them where they stand), not the column's rest. + const g = layout(ctx.stage, rec, moment); + const sb = g.stack; 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"); - // 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 rsp = g.rsp; + const first = g.first; + const top = g.top; 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(@as(i64, @bitCast(addr -% from)) >> 3)); - } - }.y; + // 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. - const reveal: canim.Stack.Reveal = .{ .offsets = s.value(-1), .roles = s.value(-1), .spans = s.value(-1) }; + // (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 }); @@ -137,10 +136,13 @@ fn frame(s: *anim.Frame) void { // (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. + // 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); - 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 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); // 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)); @@ -152,69 +154,92 @@ fn frame(s: *anim.Frame) void { 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, 386); + 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 }); - // 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) }); + // 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 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); + // The relations, and rsp's link to its word as II2 names it. + const joins, const rsp_link = ctx.tiesWith(s, "rsp", 1.0); 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). + // 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 }); 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 }); - 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); + 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. + 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)); - at.walk(s, .moment, moment + 1); s.wait(t.beat); - // 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); + // II3: 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)); 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); + at.aim(s, .drawn); + s.wait(f(24 + 30)); s.wait(t.beat); - // 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); + // 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). + 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 }); - lift(s, &.{regs_rows[0]}, 0, 12); - lift(s, lane[3..], 2, 12); + 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); s.wait(f(12)); + at.levels.carry = .after_touch; + at.walk(s, .moment, moment + 1); + at.levels.carry = .off; + s.wait(t.beat); + + // II5: 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); at.walk(s, .moment, framed); - run(s, reveal.roles, 2 * @as(f32, @floatFromInt(slots)) + 12); - run(s, reveal.spans, 2 * 4 + 12); + run(s, reveal.roles, column); + run(s, reveal.spans, reveal.apart * 4 + 12); s.wait(t.beat); - // `frame up`: its rules (12 f), then its tag and strip (12 f). + // `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); + 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); + s.cursor = at_tags; lift(s, &.{ stack_chrome[0], stack_chrome[4] }, 0, 12); s.wait(t.beat); - // 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); + // 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); @@ -222,3 +247,46 @@ fn frame(s: *anim.Frame) void { s.wait(@max(asides.read_by - s.cursor, 0)); s.wait(t.before_cut); } + +/// The chapter's texts, in order (chapter III opens on the last two). +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; + +/// 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 { + 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 } { + 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. + stage.first.stack.h = canim.layout.panelH(16 + held_free); + stage.first.stack.y = rb.y + rb.h + canim.theme.canvas.row_gap; + 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 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 }; +} + +fn rowY(t0: f32, from: u64, addr: u64) f32 { + return t0 + row * @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% from)) >> 3)); +} -- cgit v1.3