summaryrefslogtreecommitdiff
path: root/anim/src/regroup.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 23:46:02 -0300
committerGabriel Schneider <[email protected]>2026-11-12 01:40:04 -0300
commit60e07feef401d9044db3a1c925cb9d1f6d20dac9 (patch)
tree98957ba8425193f686c8e8692cd10a10f27dbf4b /anim/src/regroup.zig
parent9c0696447dbc5cf37e56aee562c7ebba4f4d4e6b (diff)
downloadcomputeranim-60e07feef401d9044db3a1c925cb9d1f6d20dac9.tar.gz
computeranim-60e07feef401d9044db3a1c925cb9d1f6d20dac9.zip
canim: relations as one data-oriented subsystem; aim; the ASan pair; the introduction's chapters
From the user. Relations between panes are one subsystem: per-frame tables of places and values in struct-of-arrays, owned by the frame; the kinds one table of data; a resolver of pure passes (join, filter, priority, cut) unit-tested on hand-written tables. Ported kinds draw byte-identical frames; a synthetic map of 4000 places and 6000 values resolves in 0.56 ms against the old table's 5.7. aim, a word holding a code address tied to its row, is the first new kind, off unless a scene turns it on. The ASan pair: one overflow built plain and with ASan, recorded by instruction; the frame as bytes eight a row; the plain run goes on alone in the column, its return address aimed at main's row until the letters reach it; the fault at ret. The introduction's three chapters are built and tested, not yet exported. Annotations, rows and scrolls that changed in one frame now fade; captions stand twelve seconds at most. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/src/regroup.zig')
-rw-r--r--anim/src/regroup.zig348
1 files changed, 348 insertions, 0 deletions
diff --git a/anim/src/regroup.zig b/anim/src/regroup.zig
new file mode 100644
index 0000000..431abd8
--- /dev/null
+++ b/anim/src/regroup.zig
@@ -0,0 +1,348 @@
+//! 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, &regs, 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);
+ }
+};