//! 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, 12 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 on nested arcs to its word's field, 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 out (6 f), the dump's tag to the shelf (18 f, `glide`); back. //! - `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; 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, 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; for (values.words, 0..) |v, i| switch (rows.regionOf(m, v)) { .heap => heap = heap orelse i, .stack => stack = stack orelse i, else => {}, }; var three = [3]usize{ heap orelse 0, stack orelse 1, 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), }; } /// The word's text: its hex without the zeros in front. fn digits(u: ui.Ui, v: u64) []const u8 { return u.print("{x}", .{v}); } 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); const shown = 1 - clamp01(fold / 6); w.tag(u, fold); if (shown <= 0) return; const v = u.faded(shown); 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. const header = clamp01(in / 18) * (1 - placed.value(w.placed)); if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, at.top - 12, "128 bytes, from where rsp points", t.faint); // The veil over every row but the walked one, while it is walked. const veil = clamp01((r - 48) / 18) - clamp01((r - 270) / 18); 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 - 12 * @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)); const slot: f32 = @floatFromInt(@as(i64, @bitCast(data.base + 8 * i -% w.panel.first)) >> 3); const y = std.math.lerp(p.y, w.panel.top + pitch * slot, g); const base = theme.baseline(y, pitch, size); const ax = std.math.lerp(at.address, w.panel.x + theme.metric.slot.address, g); 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 * 2)), 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); if (shows > 0) v.read(w.wordRect(i, data.words[i], placed), 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 { const n: f32 = @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 - 120 - 6 * @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 - 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) 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| v.faded(clamp01(since * 10)).text(.mono, size, end + 10, base, ui.symbol(u, name), 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.text(.mono, size, rect.x, base, digits(u, value), 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) return; const y = at.top + pitch * @as(f32, @floatFromInt(w.walked)); const base = theme.baseline(y, pitch, size); const value = data.words[w.walked]; // Under the row, its offsets and labels on the page (the veiled rows under them 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) / 12)); const offsets = clamp01((r - 66) / 12) * (1 - clamp01((r - 192) / 12)); const zeros_mark = clamp01((r - 204) / 12) * (1 - clamp01((r - 228) / 12)); const under = @max(offsets, zeros_mark); if (under > 0) u.faded(under).fill(.{ .x = at.bytes - 12, .y = y + pitch, .w = at.field_end - at.bytes + 24, .h = 2 * pitch + 6 }, theme.color.page); const close = glide((r - 192) / 12); for (0..8) |k| { const kf: f32 = @floatFromInt(k); const s = clamp01((r - 108 - 6 * kf) / 36); 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); const long = to - from; const high = std.math.clamp(long / 4, theme.time.flight.arc_min, theme.time.flight.arc_max); const x = std.math.lerp(from, to, theme.ease(.glide, s)); const 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 - 18, .w = 2 * adv + 6, .h = 24 }, 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) 1 - clamp01((r - 228) / 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, going with it. const off = offsets * clamp01((r - 66 - 2 * kf) / 12); if (off > 0 and s > 0 and s < 1) u.faded(off).fill(.{ .x = x - 3, .y = base + pitch - lift - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); if (off > 0) u.faded(off).text(.mono, size, x, base + pitch - lift, 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. 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); u.faded(labels).text(.sans, theme.size.sans.tag, if (k == 0) x else x + 2 * adv - lw, base + 2 * pitch + 2 - lift, label, t.dim); }; } // The zeros in front, bracketed (motion.md: 204 to 228). 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); 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, "zeros in front", t.dim); } } /// The dump folded to its tag on the shelf (mock 49's shelf, y 48): the /// rows out over 6 f, the tag from over the rows to the shelf (18 f, `glide`). fn tag(_: *const Words, u: ui.Ui, fold: f32) void { if (fold <= 0) return; const title = "the stack's 128 bytes"; const p = glide((fold - 6) / 18); const w = u.width(.sans_medium, theme.size.sans.tag, title) + 40; const x = std.math.lerp(at.address - 8, theme.canvas.margin_x, p); const y = std.math.lerp(at.top - 30, theme.canvas.stage.y, p); const v = u.faded(clamp01(fold / 6)).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); } };