summaryrefslogtreecommitdiff
path: root/anim/src/calls.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/calls.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/calls.zig')
-rw-r--r--anim/src/calls.zig160
1 files changed, 160 insertions, 0 deletions
diff --git a/anim/src/calls.zig b/anim/src/calls.zig
new file mode 100644
index 0000000..af0893d
--- /dev/null
+++ b/anim/src/calls.zig
@@ -0,0 +1,160 @@
+//! Calls as an idea, a lens on the stack: the tree of every call of one
+//! function, which grows as the program runs (the frames themselves are
+//! `context.Backtrace` and the stack's words). It reads the recording's
+//! index of calls and returns, with what each was given and gave back,
+//! and is the last level a step reaches: a node appears after the
+//! registers that carried its argument have struck.
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const ui = @import("ui.zig");
+const cursors = @import("cursor.zig");
+const Cursor = cursors.Cursor;
+const Recording = @import("Recording.zig");
+const theme = ui.theme;
+const time = theme.time;
+const Rect = ui.Rect;
+const t = theme.color.text;
+
+/// A return's follow-through: its frame leaves the backtrace as the idea
+/// strikes, and the tree's badge is struck this long after.
+const badge_after = 0.20;
+
+pub const Tree = struct {
+ cursor: Cursor,
+ box: Rect,
+ /// The function whose calls are the tree.
+ function: []const u8,
+ focus: bool = false,
+
+ pub fn draw(k: *const Tree, f: *sk.Frame, at: anim.Placed) void {
+ const u: ui.Ui = .{ .f = f, .at = at };
+ const now = k.cursor.now(at);
+ const rec = k.cursor.rec;
+ const m = struct {
+ const radius = 18;
+ const level = 44;
+ const badge = 24;
+ };
+ const body = u.panel(k.box.w, k.box.h, u.print("calls of {s}", .{k.function}), .{ .focus = k.focus, .note = "each call a node \u{00b7} its result on the shoulder \u{00b7} the frames are the stack's" });
+ const nodes = layout(f.scratch, rec, k.function) catch return;
+ if (nodes.len == 0) return;
+ var leaves: f32 = 0;
+ for (nodes) |n| leaves = @max(leaves, n.x + 1);
+ const pitch = @min(4.5 * m.radius, (body.w - 2 * theme.metric.panel.pad_x - 2 * m.radius) / @max(leaves - 1, 1));
+ const left = (body.w - (leaves - 1) * pitch) / 2;
+ const top = body.y + m.radius + 12;
+ var deepest_level: f32 = 1;
+ for (nodes) |n| deepest_level = @max(deepest_level, @as(f32, @floatFromInt(n.level)));
+ const level_h = @min(m.level, (body.h - 2 * m.radius - 24) / deepest_level);
+ // A call: its edge draws from the caller's node, then the node
+ // fades in, gold, and the caller's goes from gold to a waiting
+ // ring. A return: the badge is struck a little after the card's
+ // result, and the node goes from gold to done.
+ const since = now.since(.idea, 0);
+ const returned = now.walking() and rec.depths[now.stops[0]] < rec.depths[now.stops[1]];
+ const moment = if (now.plan.gait == .sprint or since >= (if (returned) @as(f32, badge_after) else 0)) now.stops[0] else now.stops[1];
+ const edge = cursors.standard(now.moving(.idea, time.quick, time.quick));
+ const appears = now.moving(.idea, 0, time.snap);
+
+ // Edges under nodes: the waiting path in vellum.
+ for (nodes) |n| {
+ const parent = n.parent orelse continue;
+ if (n.call.enter > now.stops[0]) continue;
+ const from = ui.Vec{ left + nodes[parent].x * pitch, top + @as(f32, @floatFromInt(nodes[parent].level)) * level_h };
+ var to = ui.Vec{ left + n.x * pitch, top + @as(f32, @floatFromInt(n.level)) * level_h };
+ if (n.call.enter > now.stops[1]) to = sk.math.mix(from, to, edge);
+ const live = n.call.active(moment);
+ u.line(from, to, if (live or n.call.enter > moment) ui.rgb(t.primary) else ui.rgb(theme.color.rule), if (live or n.call.enter > moment) theme.stroke.arrow else theme.stroke.line);
+ }
+ const deepest = deepestActive(nodes, moment);
+ for (nodes, 0..) |n, i| {
+ if (n.call.enter > moment) continue;
+ const c = ui.Vec{ left + n.x * pitch, top + @as(f32, @floatFromInt(n.level)) * level_h };
+ const v = if (n.call.enter > now.stops[1]) u.faded(appears) else u;
+ if (deepest == i) {
+ v.disc(c, m.radius, ui.rgb(theme.mark(.current).solid), null, 0);
+ } else if (n.call.active(moment)) {
+ v.disc(c, m.radius - theme.stroke.arrow / 2, ui.rgb(theme.color.page), ui.rgb(t.primary), theme.stroke.arrow);
+ } else v.disc(c, m.radius, ui.rgb(theme.color.raised), null, 0);
+ }
+ // Then the words, so shapes and text each go in one run.
+ const size = theme.size.mono.context;
+ for (nodes, 0..) |n, i| {
+ if (n.call.enter > moment) continue;
+ const cx = left + n.x * pitch;
+ const cy = top + @as(f32, @floatFromInt(n.level)) * level_h;
+ const active = n.call.active(moment);
+ const words = if (n.call.arg) |arg| u.print("{d}", .{@as(i64, @bitCast(arg))}) else "?";
+ const cell: Rect = .{ .x = cx - m.radius, .y = cy - m.radius, .w = 2 * m.radius, .h = 2 * m.radius };
+ const v = if (n.call.enter > now.stops[1]) u.faded(appears) else u;
+ if (deepest == i) {
+ v.label(.mono_bold, size, cell, .center, words, theme.mark(.current).on_solid);
+ } else v.label(.mono, size, cell, .center, words, if (active) t.primary else t.dim);
+ if (active) continue;
+ // Done: what it returned, on its shoulder; struck as it lands.
+ const badge: Rect = .{ .x = cx + 10, .y = cy - m.radius - 12, .w = m.badge, .h = m.badge };
+ const heat: ui.Heat = if (n.call.exit.? > now.stops[1]) now.heat(0, null, since - badge_after) else .none;
+ const ink = u.written(badge, heat, theme.color.page);
+ if (heat.level < 1) u.frame(badge, t.faint, theme.stroke.rule);
+ u.label(ink.face, size, badge, .center, u.print("{d}", .{@as(i64, @bitCast(n.call.result))}), if (heat.level >= 1) ink.ink else ui.rgb(t.primary));
+ }
+ }
+};
+
+pub const Node = struct {
+ call: Recording.Call,
+ parent: ?usize,
+ level: u32,
+ /// In leaf slots: a leaf has a whole number, a parent sits over the
+ /// middle of its children.
+ x: f32,
+};
+
+fn deepestActive(nodes: []const Node, moment: u64) ?usize {
+ var best: ?usize = null;
+ for (nodes, 0..) |n, i| {
+ if (n.call.active(moment) and (best == null or n.level >= nodes[best.?].level)) best = i;
+ }
+ return best;
+}
+
+/// Every call of `function`, placed as a tidy tree of the whole run, so a
+/// node is where it will always be from the moment it appears.
+pub fn layout(arena: std.mem.Allocator, rec: *const Recording, function: []const u8) ![]Node {
+ var nodes: std.ArrayList(Node) = .empty;
+ // Calls come in the order they were made: a parent before its children.
+ var index: std.AutoHashMapUnmanaged(u32, usize) = .empty;
+ for (rec.calls, 0..) |call, i| {
+ if (!std.mem.eql(u8, rec.name(call.function), function)) continue;
+ const parent: ?usize = if (call.parent) |p| index.get(p) else null;
+ try index.put(arena, @intCast(i), nodes.items.len);
+ try nodes.append(arena, .{ .call = call, .parent = parent, .level = if (parent) |p| nodes.items[p].level + 1 else 0, .x = -1 });
+ }
+ // Leaves left to right in call order; then each parent over its children,
+ // deepest first (children come after their parent, so backwards).
+ const lo = try arena.alloc(f32, nodes.items.len);
+ const hi = try arena.alloc(f32, nodes.items.len);
+ @memset(lo, std.math.inf(f32));
+ @memset(hi, -std.math.inf(f32));
+ var next_leaf: f32 = 0;
+ for (nodes.items, 0..) |*n, i| {
+ const leaf = for (nodes.items[i + 1 ..]) |other| {
+ if (other.parent == i) break false;
+ } else true;
+ if (!leaf) continue;
+ n.x = next_leaf;
+ next_leaf += 1;
+ }
+ var i = nodes.items.len;
+ while (i > 0) {
+ i -= 1;
+ const n = &nodes.items[i];
+ if (n.x < 0) n.x = (lo[i] + hi[i]) / 2;
+ if (n.parent) |p| {
+ lo[p] = @min(lo[p], n.x);
+ hi[p] = @max(hi[p], n.x);
+ }
+ }
+ return nodes.items;
+}