//! The introduction's dump (design/motion.md, "A scene: the introduction", //! chapter I; "A word read"; mocks 29, 30, 37): the 128 bytes at the top of //! the stack, where the stack panel will stand (the state column), and the //! verbs that make words of them, each a clock the scene plays (frames, //! linear): //! //! - `in`: the rows arrive, sixteen bytes a row, 18 f each, 18 f apart; no //! ink, the addresses faint. //! - `regroup` (design/README.md, 6. Verbs): sixteen a row to eight, the //! return address walked (its offsets, `low byte`, `high byte`, its bytes //! flying low byte first to its word's field, on nested arcs, or over a //! top row one at a time; the gaps closing, `zeros in front`), the other //! fifteen at a run. //! - `framed`: three words that hold addresses framed as read, 30 f apart. //! - `fold`: the rows glide up into the header (24 f), the header becomes //! the tag, the tag to the shelf (24 f, `glide`); back, the reverse. //! - `ink` (6. Verbs): a word's digits to its region's ink, the walked one //! framed with its bytes (its band in `segments` is the scene's echo); //! the rest at a run, 2 f apart. //! - `left`: the words to their field's left (24 f, `glide`); `chains`: //! three chains grow (`extend`), 36 f apart. //! //! Every byte and word from the recording at its moment. const std = @import("std"); const sk = @import("sketch"); const anim = @import("anim"); const zt = @import("ztrace"); const ui = @import("ui.zig"); const rows = @import("rows.zig"); const Recording = @import("Recording.zig"); const theme = ui.theme; const Rect = ui.Rect; const t = theme.color.text; pub const words = 16; /// `in`: frames between one row's arrival and the next's (motion.md's 12: /// the rows come while the first text is read, and its reading has them). pub const rows_apart = 18; /// The walked word's flights (motion.md, "A word read": 36 f, 6 f apart): /// over its row there is room for one in the air at a time, so each is /// 24 f and the next lifts as it comes down (18 f apart), nothing crossing /// in the air; what follows them is `later` by as much. const flight = 24; const flight_apart = 18; const later: f32 = 108 + 7 * flight_apart + flight - 186; /// The regroup's clock, to the last word in. pub const regroup_frames = 386 + later; const size = theme.size.mono.context; const adv = ui.advance(size); const pitch = theme.metric.context.row; /// Where it stands: the state column, its rows from `top`; the bytes 12 /// after the address, 30 apart, 12 more after the eighth; the word's field /// eight pairs wide, 48 after the bytes, its words ranged right. pub const at = struct { pub const column = theme.layout.state.x; pub const address = column + 24; pub const bytes = address + 12 * adv + 12; pub const pair = theme.metric.bytes.pitch; pub const middle = theme.metric.bytes.middle; pub const field = bytes + 7 * pair + 24 + 48; pub const field_end = field + 7 * pair + 24; pub const top = 96; /// The tie's bracket, left of the addresses. pub const bracket = address - 12; }; /// Bytes drawn 50% toward the page: what stays of where a word's bytes were. fn dimmed() ui.Color { return ui.mix(theme.color.page, t.primary, 0.5); } fn clamp01(x: f32) f32 { return std.math.clamp(x, 0, 1); } fn glide(x: f32) f32 { return theme.ease(.glide, clamp01(x)); } pub const Words = struct { rec: *const Recording, at: u64, in: anim.Value, regroup: anim.Value, framed: anim.Value, fold: anim.Value, /// 0 to 1: the rows' addresses take the stack's ink (the dump tied to its place). placed: anim.Value, ink: anim.Value, left: anim.Value, chains: anim.Value, /// The word walked (the return address), the three framed and chained, top down. walked: usize, three: [3]usize, /// 0 to 1: the rows glide to the stack panel's (chapter II): the panel's /// left, its first row's top and that row's address; the bytes and the /// chains' hops go in the first half, each address to the slot's /// address, each word to where the slot's chain has it. become: anim.Value, panel: struct { x: f32 = 0, top: f32 = 0, first: u64 = 0 } = .{}, pub fn init(s: *anim.Frame, rec: *const Recording, moment: u64) Words { const picked = pick(rec, moment); return .{ .rec = rec, .at = moment, .in = s.value(-1), .regroup = s.value(-1), .framed = s.value(-1), .fold = s.value(0), .placed = s.value(0), .ink = s.value(-1), .left = s.value(-1), .chains = s.value(-1), .walked = picked.walked, .three = picked.three, .become = s.value(0) }; } /// The return address the newest frame has, and the first word that /// points into the heap (or, with none, the first other address), into /// the stack, and the return address, top down. pub fn pick(rec: *const Recording, moment: u64) struct { walked: usize, three: [3]usize } { const m = rec.moment(moment); const rsp = rec.register(moment, "rsp"); var walked: usize = 0; if (m.regs(rec.tid) catch null) |regs| { var slots: [words]zt.telescope.Slot = undefined; if (zt.telescope.slots(m, ®s, rsp, &slots)) |found| { for (found, 0..) |slot, i| if (slot.role == .return_address) { walked = i; break; }; } else |_| {} } const values = read(rec, moment); var heap: ?usize = null; var stack: ?usize = null; var other: ?usize = null; for (values.words, 0..) |v, i| switch (rows.regionOf(m, v)) { .heap => heap = heap orelse i, .stack => stack = stack orelse i, .none => {}, else => if (i != walked) { other = other orelse i; }, }; // With no heap word in the 128 bytes, the first other address that is not the walked one. var three = [3]usize{ heap orelse other orelse 1, stack orelse 2, walked }; std.mem.sort(usize, &three, {}, std.sort.asc(usize)); return .{ .walked = walked, .three = three }; } pub const Bytes = struct { base: u64, bytes: [8 * words]u8, known: [8 * words]bool, words: [words]u64 }; pub fn read(rec: *const Recording, moment: u64) Bytes { var out: Bytes = .{ .base = rec.register(moment, "rsp"), .bytes = undefined, .known = undefined, .words = undefined }; rec.moment(moment).read(out.base, &out.bytes, &out.known) catch @memset(&out.known, false); for (&out.words, 0..) |*w, i| w.* = std.mem.readInt(u64, out.bytes[i * 8 ..][0..8], .little); return out; } /// Word `i`'s row's top, its bytes' first x, and how much its address shows, at regroup clock `r`. fn where(i: usize, r: f32) struct { y: f32, x: f32, address: f32 } { const row: f32 = @floatFromInt(i / 2); const half: f32 = @floatFromInt(i % 2); const a = glide(r / 18); const b = glide((r - 18) / 12); const c = glide((r - 30) / 18); return .{ .y = at.top + pitch * (row + row * a + half * b), .x = at.bytes + half * (8 * at.pair + at.middle) * (1 - c), .address = if (half == 0) 1 else clamp01((r - 36) / 12), }; } pub fn draw(w: *const Words, f: *sk.Frame, placed: anim.Placed) void { const u: ui.Ui = .{ .f = f, .at = placed }; const in = placed.value(w.in); if (in < 0) return; const was = @import("segments.zig").clipStage(f, placed); defer @import("segments.zig").unclipStage(f, was); const r = placed.value(w.regroup); const fold = placed.value(w.fold); // Folding: the rows glide up into the header (24 f), which becomes the tag (`tag`). const gather = glide(fold / 24); const header_y = at.top - pitch; w.tag(u, fold); if (gather >= 1) return; const v = u; const data = read(w.rec, w.at); const m = w.rec.moment(w.at); // The header (mock 29), with the first row; gone as the dump is tied to its place. // The veil over every row but the walked one, while it is walked (the header too). const veil = clamp01((r - 48) / 18) - clamp01((r - 270 - later) / 18); const header = clamp01(in / 18) * (1 - placed.value(w.placed)) * (1 - veil) * (1 - clamp01((fold - 12) / 8)); if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, at.top - 12, v.print("128 bytes at {x}", .{w.rec.register(w.at, "rsp")}), t.faint); const address_ink = ui.mix(t.faint, theme.color.region.stack, placed.value(w.placed)); const become = placed.value(w.become); const g = glide(become); for (0..words) |i| { const p = where(i, r); const arrive = clamp01((in - rows_apart * @as(f32, @floatFromInt(i / 2))) / 18); if (arrive <= 0) continue; const row = v.faded(arrive * (if (i == w.walked) 1 else 1 - theme.color.veil_alpha * veil) * (1 - gather)); const slot: f32 = @floatFromInt(@as(i64, @bitCast(data.base + 8 * i -% w.panel.first)) >> 3); const y = std.math.lerp(std.math.lerp(p.y, header_y, gather), w.panel.top + pitch * slot, g); const base = theme.baseline(y, pitch, size); // The bytes go first (9 f), then the addresses travel right to the slots' column: never over them. const ax = std.math.lerp(at.address, w.panel.x + theme.metric.slot.address, glide((become - 0.25) / 0.75)); if (p.address > 0) _ = row.faded(p.address).address(ax, base, data.base + 8 * i, .{ .ink = address_ink }); w.drawBytes(row.faded(1 - clamp01(become * 4)), data, i, p.x, base, r, placed); w.drawWord(row, m, data.words[i], i, y, r, placed); } if (r >= 0) w.walk(v, data, r); // The three words framed as read, 30 f apart, each in over 6 f. const framed = placed.value(w.framed); if (framed >= 0) for (w.three, 0..) |i, k| { const shows = clamp01((framed - 30 * @as(f32, @floatFromInt(k))) / 6); var rect = w.wordRect(i, data.words[i], placed); rect.y = std.math.lerp(rect.y, header_y, gather); if (shows > 0) v.faded(1 - gather).read(rect, shows); }; } /// Word `i`'s digits as they stand in the field (ranged right, or at its left). fn wordRect(w: *const Words, i: usize, value: u64, placed: anim.Placed) Rect { // A number that is no address as the stack panel writes it (`0x` in front): see `drawWord`. const n: f32 = if (rows.regionOf(w.rec.moment(w.at), value) == .none) ui.Value.of(value, false).width() / adv else @floatFromInt(ui.digits(value)); const left = glide(placed.value(w.left) / 24); const x = std.math.lerp(at.field_end - n * adv, at.field, left); return .{ .x = x, .y = at.top + pitch * @as(f32, @floatFromInt(i)), .w = n * adv, .h = pitch }; } fn drawBytes(w: *const Words, u: ui.Ui, data: Bytes, i: usize, x: f32, base: f32, r: f32, placed: anim.Placed) void { // Its bytes dim as its word comes in (the run), or are left faint where they flew from. const dim = if (i == w.walked) 0 else w.runIn(i, r); for (0..8) |k| { const bx = x + @as(f32, @floatFromInt(k)) * at.pair; const b = i * 8 + k; if (i == w.walked and r >= 108) { // In flight or landed: a faint copy fades into its place from a third of its flight. const copy = clamp01((r - 108 - 8 - flight_apart * @as(f32, @floatFromInt(k))) / 12); if (copy > 0) u.faded(copy).text(.mono, size, bx, base, u.print("{x:0>2}", .{data.bytes[b]}), dimmed()); continue; } const text = if (data.known[b]) u.print("{x:0>2}", .{data.bytes[b]}) else "??"; u.text(.mono, size, bx, base, text, ui.mix(ui.rgb(t.primary), dimmed(), dim)); } // The walked word's bytes framed with its word as it takes its ink. if (i == w.walked) { const shows = w.walkedFrame(placed); if (shows > 0) u.read(.{ .x = x, .y = base - 7.2 - pitch / 2, .w = 7 * at.pair + 2 * adv, .h = pitch }, shows); } } /// How far the run has brought word `i` in (its word in, its bytes dim): 8 f, rows 6 f apart. fn runIn(w: *const Words, i: usize, r: f32) f32 { const q: f32 = @floatFromInt(if (i > w.walked) i - 1 else i); return clamp01((r - 288 - later - 6 * q) / 8); } fn walkedFrame(w: *const Words, placed: anim.Placed) f32 { const ink = placed.value(w.ink); if (ink < 0) return 0; return clamp01(ink / 6) * (1 - clamp01((ink - 72 - 2 * words - 12) / 18)); } fn drawWord(w: *const Words, u: ui.Ui, m: Recording.Moment, value: u64, i: usize, y: f32, r: f32, placed: anim.Placed) void { const shows = if (i == w.walked) @as(f32, if (r >= 240 + later) 1 else 0) else w.runIn(i, r); if (shows <= 0) return; const v = u.faded(shows); const kind = rows.regionOf(m, value); // `ink`: the walked word first (12 f), the rest at a run, 2 f apart, rows top down. const ink_clock = placed.value(w.ink); const order: f32 = @floatFromInt(if (i == w.walked) 0 else 72 + 2 * (if (i > w.walked) i - 1 else i)); const inked = if (ink_clock < 0) 0 else clamp01((ink_clock - order) / 12); const ink = ui.mix(t.primary, rows.ink(kind), inked); var rect = w.wordRect(i, value, placed); const g = glide(placed.value(w.become)); rect.y = y; rect.x = std.math.lerp(rect.x, w.panel.x + theme.metric.slot.address + 12 * adv + theme.metric.context.arrow_w, g); const base = theme.baseline(y, pitch, size); // `extend`: three chains grow from their word, 36 f apart. const chains = placed.value(w.chains); const k = std.mem.indexOfScalar(usize, &w.three, i); if (chains >= 0 and k != null and kind != .none) { const since = (chains - 36 * @as(f32, @floatFromInt(k.?))) / 60; if (since >= 0 and (kind == .code or kind == .rwx)) { // A code address's chain is its name: it comes in as a hop does (6 f). const end = v.address(rect.x, base, value, .{ .ink = ink, .rwx = kind == .rwx }); var name_buf: [128]u8 = undefined; if (m.string(value, &name_buf) catch null) |name| { // Cut with `…` at the state column's edge, as the stack's rows cut theirs. const sym = ui.symbol(u, name); const fits: usize = @intFromFloat(@max((theme.layout.state.x + theme.layout.state.w - end - 10) / adv, 2)); const shown = if (sym.len > fits) u.print("{s}\u{2026}", .{sym[0 .. fits - 1]}) else sym; v.faded(clamp01(since * 10)).text(.mono, size, end + 10, base, shown, t.primary); } return; } if (since >= 0) { _ = rows.chain(v, rect.x, y, m, value, theme.layout.state.x + theme.layout.state.w, .{ .extend = since, .hops = 1 - clamp01(placed.value(w.become) * 2) }); return; } } if (kind == .none) _ = v.value(rect.x, base, value, false, .{ .ink = ui.rgb(ink) }) else _ = v.address(rect.x, base, value, .{ .ink = ink, .rwx = kind == .rwx }); const frame = if (i == w.walked) w.walkedFrame(placed) else 0; if (frame > 0) v.read(rect, frame); } /// The walked word, from its offsets to its sixteen digits (motion.md, "A word read"). fn walk(w: *const Words, u: ui.Ui, data: Bytes, r: f32) void { if (r < 66 or r >= 240 + later) return; const y = at.top + pitch * @as(f32, @floatFromInt(w.walked)); const base = theme.baseline(y, pitch, size); const value = data.words[w.walked]; // A row near the dump's top (at x2 the camera's frame has a row and a half over the header): // its offsets stand over it, in the header's row (veiled with the rest), `low byte` left of // `+0` and `high byte` right of `+7`; the bytes fly over that row (40 up), one at a time, // each with its offset over it, its label going as it lifts and coming on the other side as // it lands, so that nothing in the air crosses what stands, and no row of memory is printed over. const flip = w.walked < 4; const dir: f32 = if (flip) -1 else 1; // Under the row (over it, flipped), its offsets and labels on the page (the veiled rows there give way). // They go as the gaps close (192), not after: closed, their pairs are 24 apart and they would touch. const labels = clamp01((r - 84) / 12) * (1 - clamp01((r - 192 - later) / 12)); const offsets = clamp01((r - 66) / 12) * (1 - clamp01((r - 192 - later) / 12)); const zeros_mark = clamp01((r - 204 - later) / 12) * (1 - clamp01((r - 228 - later) / 12)); const page_x = at.bytes - 12; const page_w = at.field_end - at.bytes + 24; if (!flip and offsets > 0) u.faded(offsets).fill(.{ .x = page_x, .y = y + pitch, .w = page_w, .h = 2 * pitch + 6 }, theme.color.page); const close = glide((r - 192 - later) / 12); for (0..8) |k| { const kf: f32 = @floatFromInt(k); const s = clamp01((r - 108 - flight_apart * kf) / flight); const from = at.bytes + kf * at.pair; const pair = 7 - kf; const to = std.math.lerp(at.field + pair * at.pair, at.field_end - (8 - pair) * 2 * adv, close); // Up off its place, over, down onto it; flipped, a plateau 40 up, the same for all (one flies at a time). var x: f32 = undefined; var lift: f32 = undefined; var across: f32 = undefined; if (flip) { across = glide((s - 0.1) / 0.8); x = std.math.lerp(from, to, across); // Clear of the offsets standing in the row over it; one in the air at a time, so one height. lift = 40 * @min(theme.ease(.glide, clamp01(s / 0.25)), theme.ease(.glide, clamp01((1 - s) / 0.25))); } else { across = theme.ease(.glide, s); x = std.math.lerp(from, to, across); const high = std.math.clamp((to - from) / 4, theme.time.flight.arc_min, theme.time.flight.arc_max); lift = high * @sin(std.math.pi * s); } // The byte itself: bright and bold in the air (from 108 the walk draws it, not the row). if (r >= 108) { const air = s > 0 and s < 1; const text = u.print("{x:0>2}", .{data.bytes[w.walked * 8 + k]}); // In the air it carries its ground: over the veiled rows it reads alone. if (air) u.fill(.{ .x = x - 3, .y = base - lift - 17, .w = 2 * adv + 6, .h = 20 }, theme.color.page); // Each digit of a pair on its own: a zero in front of the word fades on its own. for (0..2) |d| { const lead = 2 * (7 - k) + d < 16 - ui.digits(value); const fade: f32 = if (lead and r >= 228 + later) 1 - clamp01((r - 228 - later) / 12) else 1; if (fade > 0) u.faded(fade).text(if (air) .mono_bold else .mono, size, x + @as(f32, @floatFromInt(d)) * adv, base - lift, text[d .. d + 1], if (air) t.bright else t.primary); } } // Its offset under it (over it, flipped), going with it (in the air 22 over it: the frame's top is near). const off = offsets * clamp01((r - 66 - 2 * kf) / 12); const off_base = base + dir * (if (flip) std.math.lerp(pitch, 22, clamp01(lift / 40)) else pitch) - lift; if (off > 0 and s > 0 and s < 1) u.faded(off).fill(.{ .x = x - 3, .y = off_base - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); if (off > 0) u.faded(off).text(.mono, size, x, off_base, u.print("+{d}", .{k}), t.dim); // `low byte` from its byte's left, `high byte` to its byte's right: under the bytes, never the addresses. // Flipped: beside its offset, outside the run, the low byte's on the left at rest and on the right // landed (the word reads it last); it goes as its byte lifts and comes as it lands, never crossing its offset. if (k == 0 or k == 7) if (labels > 0) { const label = if (k == 0) "low byte" else "high byte"; const lw = u.width(.sans, theme.size.sans.tag, label); const left = x - lw - adv / 2; const right = x + 2 * adv + adv / 2; const landing = s >= 0.5; const lx = if (!flip) (if (k == 0) x else x + 2 * adv - lw) else if ((k == 0) == landing) right else left; const ly = if (flip) off_base else base + 2 * pitch + 2 - lift; // (`high byte`, right of `+7` at rest, would stand where `+6` lands: it goes as `+6` lifts.) const gone = if (k == 7) clamp01((r - 108 - flight_apart * 6) / flight / 0.2) else clamp01(s / 0.2); const there: f32 = if (!flip) 1 else if (landing) clamp01((s - 0.8) / 0.2) else 1 - gone; if (there > 0) u.faded(labels * there).text(.sans, theme.size.sans.tag, lx, ly, label, t.dim); }; } // The zeros in front, bracketed (motion.md: 204 to 228, here `later`), on a ground only as wide as its label. if (zeros_mark > 0) { const lead: f32 = @floatFromInt(16 - ui.digits(value)); const x0 = at.field_end - 16 * adv; const v = u.faded(zeros_mark); const said = "zeros in front"; v.fill(.{ .x = x0 - 4, .y = y + pitch + 2, .w = v.width(.sans, theme.size.sans.tag, said) + 8, .h = pitch - 2 }, theme.color.page); v.fill(.{ .x = x0, .y = y + pitch - 2, .w = lead * adv, .h = 2 }, t.dim); v.fill(.{ .x = x0, .y = y + pitch - 8, .w = 2, .h = 6 }, t.dim); v.fill(.{ .x = x0 + lead * adv - 2, .y = y + pitch - 8, .w = 2, .h = 6 }, t.dim); v.text(.sans, theme.size.sans.tag, x0, base + pitch + 2, said, t.dim); } } /// The dump folded to its tag on the shelf (mock 49's shelf, y 48): as /// the rows gather into the header, the header becomes the tag (the /// header out 12 to 20, the tag in 16 to 24, its title where the /// header's was), which then goes to the shelf (24 f, `glide`); back, /// the reverse. fn tag(_: *const Words, u: ui.Ui, fold: f32) void { if (fold <= 16) return; const title = "the 128 bytes"; const p = glide((fold - 24) / 24); const w = u.width(.sans_medium, theme.size.sans.tag, title) + 40; const x = std.math.lerp(at.address - 28, theme.canvas.margin_x, p); const y = std.math.lerp(at.top - 30, theme.canvas.stage.y, p); const v = u.faded(clamp01((fold - 16) / 8)).moved(x, y); v.fill(.{ .x = 0, .y = 0, .w = w, .h = theme.metric.context.tag }, theme.color.raised); v.frame(.{ .x = 8, .y = 6, .w = 12, .h = 12 }, t.faint, theme.stroke.rule); v.text(.sans_medium, theme.size.sans.tag, 28, theme.metric.context.tag - 6, title, t.dim); } };