summaryrefslogtreecommitdiff
path: root/anim/src/ties.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 14:48:26 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:14:31 -0300
commit7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch)
treea6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/src/ties.zig
parented46c51fe127377eb1fde8dee83da984e0f61860 (diff)
downloadcomputeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz
computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip
canim: animations of recordings, as a debugger's whole context with a lens beside it
A package of its own (anim/), on sketchbook's anim module and pardes's syntax. A scene opens a recording, takes a cursor into it, and declares blocks that read the moment the cursor is at: the state column (registers each followed as a pointer and inked by where it points, the stack telescope, the backtrace), the program column (the whole source, the disassembly in address order, and the scene's lens: a node-link list over a hexdump of its heap, array cells, a call tree, a syscall crossing), and ties between them. Motion is a step told as a sentence (the line fires, its effects cascade a level at a time, the mark moves on last), timed by what the step contains; walk, hurry and sprint pace a loop. Five scenes from real recordings of fib, a linked list, a sort and syscalls. First drafts, by the agent's own handover: the frame of the design's second revision, the hexdump lens and the ties; no disassembly annotations, no gallery, scenes not yet reviewed against the mocks.
Diffstat (limited to 'anim/src/ties.zig')
-rw-r--r--anim/src/ties.zig139
1 files changed, 139 insertions, 0 deletions
diff --git a/anim/src/ties.zig b/anim/src/ties.zig
new file mode 100644
index 0000000..426a667
--- /dev/null
+++ b/anim/src/ties.zig
@@ -0,0 +1,139 @@
+//! Ties: one pane is a view of another, and a line between them says so.
+//! Any component can say where a thing of its own is on screen (`anchor`:
+//! a register's row, a word of memory, a node, the source's current line,
+//! the pc's row), and `Ties`, added last, draws the connections between
+//! places in different panels, routed along the gutters and never across
+//! a panel's text:
+//!
+//! - standing ties, declared by the scene (the source line and the
+//! instruction it is at: the gold thread);
+//! - the step's link: from the register a step has just struck to the
+//! row or node whose address it now holds, in the ink of where it
+//! points. It draws after the strike and goes as the marks advance;
+//! - a word a step wrote and the node it is part of: the bytes are the
+//! cause, the idea drawn from them the effect.
+//!
+//! A tie arrives, stays and leaves in the theme's time (`time.link`).
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const zt = @import("ztrace");
+const ui = @import("ui.zig");
+const cursors = @import("cursor.zig");
+const contexts = @import("context.zig");
+const Recording = @import("Recording.zig");
+const theme = ui.theme;
+const time = theme.time;
+const Rect = ui.Rect;
+
+/// A thing with a place on screen.
+pub const Place = union(enum) {
+ /// A register's value, by its place in `Regs.names`.
+ register: usize,
+ /// The word of memory at this address, wherever it is shown.
+ word: u64,
+ /// The object at this address, as an idea.
+ node: u64,
+ /// The source's current line; the disassembly's.
+ source,
+ pc,
+
+ fn key(p: Place) u64 {
+ return switch (p) {
+ .register => |i| 1 << 60 | @as(u64, i),
+ .word => |a| 2 << 60 | (a & (1 << 60) - 1),
+ .node => |a| 3 << 60 | (a & (1 << 60) - 1),
+ .source => 4 << 60,
+ .pc => 5 << 60,
+ };
+ }
+};
+
+/// What this frame's components have said so far, in canvas pixels: left, top, right, bottom.
+/// shortcut: one table for the process, emptied by `Ties.draw`; a scene with two players at once wants it on the frame.
+var table: [256]struct { key: u64, box: [4]f32 } = undefined;
+var said: usize = 0;
+
+/// `r` (in `u`'s units) is where `place` is, this frame.
+pub fn anchor(u: ui.Ui, place: Place, r: Rect) void {
+ if (said == table.len) return;
+ const a = u.at.xf.apply(.{ r.x, r.y });
+ const b = u.at.xf.apply(.{ r.x + r.w, r.y + r.h });
+ table[said] = .{ .key = place.key(), .box = .{ a[0], a[1], b[0], b[1] } };
+ said += 1;
+}
+
+fn find(place: Place) ?[4]f32 {
+ for (table[0..said]) |entry| if (entry.key == place.key()) return entry.box;
+ return null;
+}
+
+pub const Ties = struct {
+ cursor: cursors.Cursor,
+ box: Rect = theme.canvas.stage,
+ /// Ties that stand for the whole scene.
+ standing: []const [2]Place = &.{.{ .source, .pc }},
+
+ pub fn draw(g: *const Ties, f: *sk.Frame, at: anim.Placed) void {
+ defer said = 0;
+ const now = g.cursor.now(at);
+ const rec = g.cursor.rec;
+ // In canvas pixels, `k` of them a unit: anchors come from panels anywhere.
+ var raw: ui.Ui = .{ .f = f, .at = at };
+ raw.at.xf = .identity;
+ const k = at.scale;
+ // The gutter between the two columns, and the margin left of the program's.
+ const gutter = at.xf.apply(.{ theme.layout.state.x - 16 - g.box.x, 0 })[0];
+ const margin = at.xf.apply(.{ -12, 0 })[0];
+
+ for (g.standing) |tie| {
+ const a = find(tie[0]) orelse continue;
+ const b = find(tie[1]) orelse continue;
+ // The gold thread: two views of where execution is, joined down the margin.
+ const lane = @min(margin, @min(a[0], b[0]) - 6 * k);
+ raw.arrow(&.{ .{ a[0], (a[1] + a[3]) / 2 }, .{ lane, (a[1] + a[3]) / 2 }, .{ lane, (b[1] + b[3]) / 2 }, .{ b[0], (b[1] + b[3]) / 2 } }, theme.mark(.current).solid, .{ .width = theme.stroke.rule * k, .head = null });
+ }
+ if (!now.walking()) return;
+ // The step's link: the first register it struck that now holds
+ // the address of something on screen. It draws once the strike
+ // is in, and goes as the marks advance.
+ const leaves = 1 - std.math.clamp((now.time - now.plan.advance) / time.link.out, 0, 1);
+ const regs = (now.moment().regs(rec.tid) catch null) orelse return;
+ for (zt.Regs.names, 0..) |name, index| {
+ if (now.registerAge(index) != 0 or std.mem.eql(u8, name, "rip") or std.mem.eql(u8, name, "rsp") or std.mem.eql(u8, name, "rbp")) continue;
+ const value = regs.named(name) orelse continue;
+ const from = find(.{ .register = index }) orelse continue;
+ const to = find(.{ .node = value }) orelse find(.{ .word = value & ~@as(u64, 7) }) orelse continue;
+ const drawn = cursors.standard(std.math.clamp((now.since(.cpu, 0) - time.strike.in) / time.link.in, 0, 1));
+ const color = contexts.ink(contexts.regionOf(now.moment(), value));
+ const y = (from[1] + from[3]) / 2;
+ const to_y = (to[1] + to[3]) / 2;
+ // Out of the panel's edge, along the gutter, to the side of what it lands on.
+ const edge = find(.{ .register = 1 << 20 }) orelse from;
+ const lands_at = if (to[2] < gutter) to[2] + 2 * k else to[0] - 2 * k;
+ raw.faded(leaves).arrow(&.{ .{ edge[0], y }, .{ gutter, y }, .{ gutter, to_y }, .{ lands_at, to_y } }, color, .{ .width = theme.stroke.line * k, .head = .{ 12 * k, 10 * k }, .progress = drawn });
+ // What it lands on answers with a frame.
+ if (drawn >= 1) raw.faded(leaves).frame(.{ .x = to[0] - 2 * k, .y = to[1] - 2 * k, .w = to[2] - to[0] + 4 * k, .h = to[3] - to[1] + 4 * k }, color, theme.stroke.rule * k);
+ break;
+ }
+ // A word written and the node it is part of: the bytes, then the idea.
+ for (rec.written(now.stops[1], now.stops[0])) |span| {
+ const word = find(.{ .word = span.addr & ~@as(u64, 7) }) orelse continue;
+ const node = for (table[0..said]) |entry| {
+ // The node whose bytes hold the word: nodes are sixteen bytes here.
+ if (entry.key >> 60 == 3 and (span.addr & (1 << 60) - 1) -% (entry.key & (1 << 60) - 1) < 16) break entry.box;
+ } else continue;
+ const drawn = cursors.standard(std.math.clamp(now.since(.memory, 0) / time.cascade, 0, 1));
+ const x = (word[0] + word[2]) / 2;
+ const node_x = (node[0] + node[2]) / 2;
+ const between = (node[3] + word[1]) / 2 + 18 * k;
+ raw.faded(leaves).arrow(&.{ .{ x, word[1] }, .{ x, between }, .{ node_x, between }, .{ node_x, node[3] + 2 * k } }, theme.mark(.write).solid, .{ .width = theme.stroke.line * k, .head = .{ 12 * k, 10 * k }, .progress = drawn });
+ break;
+ }
+ }
+};
+
+test "places have keys of their own" {
+ try std.testing.expect((Place{ .word = 0x1000 }).key() != (Place{ .node = 0x1000 }).key());
+ try std.testing.expect((Place{ .source = {} }).key() != (Place{ .pc = {} }).key());
+}