summaryrefslogtreecommitdiff
path: root/anim/src/array.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/array.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/array.zig')
-rw-r--r--anim/src/array.zig189
1 files changed, 189 insertions, 0 deletions
diff --git a/anim/src/array.zig b/anim/src/array.zig
new file mode 100644
index 0000000..5d6b471
--- /dev/null
+++ b/anim/src/array.zig
@@ -0,0 +1,189 @@
+//! An array as cells: a variable the recording describes as `T name[N]`,
+//! each element a cell with its index, the index variables that point into
+//! it as tags, the cells a step compared framed as read, and a value a
+//! step copied from one cell to another flying there on an arc, to land as
+//! a write (a swap is two flights, one over and one under, the second a
+//! little behind the first).
+//! This is the idea drawn from memory: it changes a beat after the bytes do.
+//! Reads `Moment.variables`, `Moment.read`, and the index of reads and writes.
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const ui = @import("ui.zig");
+const cursors = @import("cursor.zig");
+const Recording = @import("Recording.zig");
+const objects = @import("objects.zig");
+const theme = ui.theme;
+const time = theme.time;
+const Rect = ui.Rect;
+const t = theme.color.text;
+const fl = time.flight;
+
+/// How long a value flies, by how far: duration follows distance.
+fn flightTime(units: f32) f32 {
+ return if (units <= 200) fl.near else if (units <= 400) fl.mid else fl.far;
+}
+
+pub const Array = struct {
+ cursor: cursors.Cursor,
+ box: Rect,
+ /// The array's name in the program.
+ variable: []const u8,
+ /// Variables that index it, shown as tags in the cell they point at.
+ indices: []const []const u8 = &.{},
+ focus: bool = false,
+
+ /// The timetable of a step that swaps two neighbouring cells (give it
+ /// to `Cursor.step`): the line fires, the first value lifts and
+ /// flies, the second a little behind it; each lands with a strike;
+ /// then the hold, and the mark moves on. 2.1 s.
+ pub const swap: cursors.Plan = blk: {
+ const lands = time.fire + fl.lift + fl.near;
+ const advance = lands + fl.second + time.read_value;
+ break :blk .{ .at = .{ time.cascade, time.cascade, lands }, .advance = advance, .travel = time.step, .total = advance + time.step + time.rest };
+ };
+
+ pub fn draw(g: *const Array, f: *sk.Frame, at: anim.Placed) void {
+ const u: ui.Ui = .{ .f = f, .at = at };
+ const now = g.cursor.now(at);
+ const rec = g.cursor.rec;
+ const moment = now.shown(.idea);
+ const v = rec.variable(f.scratch, moment, g.variable) orelse {
+ _ = u.panel(g.box.w, g.box.h, g.variable, .{ .focus = g.focus });
+ return;
+ };
+ const kind = rec.typeOf(f.scratch, v.type);
+ // Its declaration, and where it is: the address the context's pointers to it end in.
+ const body = u.panel(g.box.w, g.box.h, g.variable, .{ .focus = g.focus, .note = u.print("{s} at \u{2026}{x:0>4}", .{ objects.declare(f.scratch, rec, v), v.addr & 0xffff }) });
+ // An array of numbers; anything else is read as 4-byte ones.
+ const elem: u64 = if (kind != null and kind.? == .array) kind.?.array.elem.size() orelse 4 else 4;
+ const signed = kind == null or kind.? != .array or kind.?.array.elem.* != .scalar or kind.?.array.elem.scalar.kind == .int;
+ const count: usize = @intCast(@min(v.size / elem, 32));
+ if (count == 0) return;
+
+ const room = body.w - 2 * theme.metric.panel.pad_x;
+ const hero = @as(f32, @floatFromInt(count)) * theme.metric.hero_cell[0] <= room;
+ // Beside the context there is less room: the cells are as wide as fit.
+ const compact = !hero and @as(f32, @floatFromInt(count)) * theme.metric.cell[0] > room;
+ const cell: [2]f32 = if (hero) theme.metric.hero_cell else if (compact) .{ @floor(room / @as(f32, @floatFromInt(count))), theme.metric.cell[1] } else theme.metric.cell;
+ const size: f32 = if (hero) theme.size.mono.hero else if (compact) theme.size.mono.data else theme.size.mono.value;
+ const left = (body.w - @as(f32, @floatFromInt(count)) * cell[0]) / 2;
+ const top = body.y + (body.h - cell[1]) / 2 - @as(f32, if (compact) 30 else 0);
+ const walking = now.walking();
+
+ // What moved: a cell written with what another cell held, which this step read.
+ const Flight = struct { from: usize, to: usize };
+ var flights: std.ArrayList(Flight) = .empty;
+ const values = f.scratch.alloc(?i64, count) catch return;
+ const old = f.scratch.alloc(?i64, count) catch return;
+ for (values, old, 0..) |*value, *was, i| {
+ value.* = number(now.moment(), v.addr + i * elem, elem, signed);
+ was.* = number(now.before(), v.addr + i * elem, elem, signed);
+ }
+ if (now.plan.gait != .sprint and !now.resting()) for (0..count) |to| {
+ if (now.writeAge(v.addr + to * elem, elem) != 0 or values[to] == null) continue;
+ for (0..count) |from| {
+ if (from != to and old[from] == values[to] and now.wasRead(v.addr + from * elem, elem)) {
+ flights.append(f.scratch, .{ .from = from, .to = to }) catch {};
+ break;
+ }
+ }
+ };
+
+ for (0..count) |i| {
+ const r: Rect = .{ .x = left + @as(f32, @floatFromInt(i)) * cell[0], .y = top, .w = cell[0] - 2, .h = cell[1] };
+ const addr = v.addr + i * elem;
+ // The cell a value is flying to is struck when it lands: the second a little after the first.
+ const flown: ?usize = for (flights.items, 0..) |flight, k| {
+ if (flight.to == i) break k;
+ } else null;
+ const delay = if (flown) |k| @as(f32, @floatFromInt(k)) * fl.second else 0;
+ const pending = !now.landed(.idea, delay) and now.writeAge(addr, elem) == 0;
+ var heat = now.written(addr, elem, .idea, delay);
+ // The value on its way is the anticipation: no frame as well.
+ if (flown != null) heat.arm = 0;
+ const ink = u.written(r, heat, theme.color.raised);
+ // Staging: the compare is seen (framed as read) before anything moves.
+ if (now.wasRead(addr, elem) and now.writeAge(addr, elem) != 0) u.readMark(r, now.reading(.idea, 0));
+ u.text(.mono, if (compact) theme.size.mono.context else theme.size.mono.small, r.x + @as(f32, if (compact) 6 else 14), r.y + @as(f32, if (compact) 24 else 34), u.print("{d}", .{i}), if (ink.face == .mono_bold) ink.ink else ui.rgb(t.faint));
+ // Until its new value lands a cell keeps the old one, faint once
+ // the new is in the air: a copy does not erase.
+ const shown = if (pending) old[i] else values[i];
+ const digits: Rect = .{ .x = r.x, .y = r.y + 18, .w = r.w, .h = r.h - 18 };
+ const leaving = pending and flown != null and (!walking or now.since(.idea, delay) >= -(flightTime(cell[0]) + fl.lift));
+ if (shown) |n| u.label(ink.face, size, digits, .center, u.print("{d}", .{n}), if (leaving) ui.rgb(t.faint) else ink.ink) else u.unknown(digits);
+ }
+
+ // Index variables: tags that slide from cell to cell as the idea strikes.
+ for (g.indices, 0..) |name, nth| {
+ const iv = rec.variable(f.scratch, now.moment(), name) orelse continue;
+ const here = number(now.moment(), iv.addr, @min(iv.size, 8), true) orelse continue;
+ var x = left + (@as(f32, @floatFromInt(here)) + 1) * cell[0];
+ if (number(now.before(), iv.addr, @min(iv.size, 8), true)) |was| {
+ x = std.math.lerp(left + (@as(f32, @floatFromInt(was)) + 1) * cell[0], x, cursors.standard(now.moving(.idea, 0, time.move)));
+ }
+ if (here < 0 or here >= count) continue;
+ // Under the tags of the indices before it that are in the same cell.
+ var slot: f32 = 0;
+ for (g.indices[0..nth]) |other| {
+ const ov = rec.variable(f.scratch, moment, other) orelse continue;
+ if (number(moment, ov.addr, @min(ov.size, 8), true) == here) slot += 1;
+ }
+ const w = u.width(.mono_bold, theme.size.mono.small, name) + 16;
+ // In a narrow cell the tags hang under it, not in it.
+ const tag: Rect = if (compact) .{ .x = x - cell[0] / 2 - w / 2, .y = top + cell[1] + 8 + slot * 38, .w = w, .h = 34 } else .{ .x = x - 2 - 10 - w, .y = top + 10 + slot * 38, .w = w, .h = 34 };
+ u.fill(tag, t.ink);
+ u.label(.mono_bold, theme.size.mono.small, tag, .center, name, t.primary);
+ }
+
+ // Values in flight, over everything: one over, the next under.
+ for (flights.items, 0..) |flight, k| {
+ const from = ui.Vec{ left + (@as(f32, @floatFromInt(flight.from)) + 0.5) * cell[0], top + cell[1] / 2 + 9 };
+ const to = ui.Vec{ left + (@as(f32, @floatFromInt(flight.to)) + 0.5) * cell[0], top + cell[1] / 2 + 9 };
+ const far = @abs(to[0] - from[0]);
+ const seconds = flightTime(far);
+ // Seconds until it lands. Anticipation: it lifts out of its
+ // cell before it goes, and is back to size as it comes down.
+ const left_to_go = -now.since(.idea, @as(f32, @floatFromInt(k)) * fl.second);
+ if (left_to_go <= 0) continue;
+ var along: f32 = undefined;
+ var lifted: f32 = undefined;
+ if (walking) {
+ if (left_to_go > seconds + fl.lift) continue;
+ along = 1 - std.math.clamp(left_to_go / seconds, 0, 1);
+ lifted = @min(std.math.clamp((seconds + fl.lift - left_to_go) / fl.lift, 0, 1), std.math.clamp(left_to_go / fl.lift, 0, 1));
+ } else {
+ // At a run: the same arc, eased, in the step's first frames.
+ along = now.moving(.idea, 0, 0);
+ lifted = 0;
+ if (along >= 1) continue;
+ }
+ // Arcs: an idea moves on a curve, slow out of one cell and into the other, quickest over the top.
+ const eased = cursors.glide(along);
+ const rise = std.math.clamp(fl.arc * far, fl.arc_min, fl.arc_max) + cell[1] / 2;
+ const way: f32 = if (k % 2 == 0) -1 else 1;
+ const c = sk.math.mix(from, to, eased) + ui.Vec{ 0, way * rise * @sin(std.math.pi * eased) };
+ const grown = std.math.lerp(1, fl.lift_scale, lifted);
+ const w = (if (compact) cell[0] + 4 else @max(theme.metric.flight_card[0], cell[0] * 0.6)) * grown;
+ const h = (if (compact) theme.metric.flight_card[1] - 8 else theme.metric.flight_card[1]) * grown;
+ const card: Rect = .{ .x = c[0] - w / 2, .y = c[1] - h / 2, .w = w, .h = h };
+ u.fill(card, theme.color.page);
+ u.frame(card, t.bright, theme.stroke.line);
+ if (values[flight.to]) |n| u.label(.mono_bold, if (compact) theme.size.mono.value else theme.size.mono.flight, card, .center, u.print("{d}", .{n}), t.bright);
+ }
+ }
+};
+
+/// `bytes` at `addr` as a number, null where never recorded.
+fn number(moment: Recording.Moment, addr: u64, bytes: u64, signed: bool) ?i64 {
+ const n: usize = @intCast(@min(bytes, 8));
+ const raw = (Recording.word(moment, addr, n) catch return null) orelse return null;
+ if (!signed) return @bitCast(raw);
+ const shift: u6 = @intCast(64 - 8 * n);
+ return @as(i64, @bitCast(raw << shift)) >> shift;
+}
+
+test "a swap of neighbours is 2.1 seconds" {
+ try std.testing.expectApproxEqAbs(@as(f32, 2.1), Array.swap.total, 1e-3);
+ try std.testing.expect(flightTime(168) == fl.near and flightTime(336) == fl.mid and flightTime(900) == fl.far);
+}