diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 16:05:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 16:43:58 -0300 |
| commit | 165bb6c1344b98de7bef1d3c2b72147b4a40797a (patch) | |
| tree | 0e70e6222700063f604f78673f6ab3a5bfb9242d /anim/src/ties.zig | |
| parent | 66a2a7cf733f6abc1f79561c52d901ce67019fb1 (diff) | |
| download | computeranim-165bb6c1344b98de7bef1d3c2b72147b4a40797a.tar.gz computeranim-165bb6c1344b98de7bef1d3c2b72147b4a40797a.zip | |
canim: the renderer speaks the design language
The blocks, their states and the tokens carry the catalogue's names:
atoms in ui, chain/reg/slot in rows, insn with its line column, jump lane
and annotations (read, write, taken or not, a call with its arguments, a
return, a syscall) in disasm, bytes and hexdump with field paper and the
reading column, the three splits and relayout in stage, the ties (thread,
link and pin, projection, echo). A lens is a band over the whole context,
its drawing left and its bytes right. Frames' spans on the stack, each
instruction's line and a callee's parameter count come from the tracer.
A gallery scene draws every block; the test compares six of its pages
with pictures kept in test/gallery, drawn from a recording kept there
too. The scenes are ported; the motion checks report no pop and no
metronome in any of them.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'anim/src/ties.zig')
| -rw-r--r-- | anim/src/ties.zig | 283 |
1 files changed, 210 insertions, 73 deletions
diff --git a/anim/src/ties.zig b/anim/src/ties.zig index 426a667..d18b996 100644 --- a/anim/src/ties.zig +++ b/anim/src/ties.zig @@ -1,57 +1,81 @@ -//! 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: +//! Ties (design/README.md, "4. Ties"): the panes are one machine at +//! different levels, and a tie says which thing in one pane a thing in +//! another is. Panels publish the `place`s of their things as they draw +//! (`anchor`); `Ties`, added after them, draws between places, along the +//! channels only, never across a letter or another tie: //! -//! - 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. +//! - `thread` (standing): the source's current line is these +//! instructions. Gold, 3: a bracket on the line, one on each run of its +//! instructions in the disassembly, a line down the left margin. +//! - `link` (for the step that set it): this register now points at +//! that. In the ink of the region pointed into, 3 wide, up the gutter's +//! left lane, head on the target; it ends in the target's `pin` and +//! leaves it behind (`pinShows` times the pin for its owner). +//! - `projection` (for the step): these bytes are that part of the +//! drawing. In the mark's colour, 2 wide: a bracket on the dump's row, +//! a line down the gutter's right lane and along the lens's top lane, +//! a bracket over the node's address. +//! - `echo`: the same mark at the same instant in two panels; no line. //! -//! A tie arrives, stays and leaves in the theme's time (`time.link`). +//! Budget: one thread; for a step one link and one projection. 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 rows = @import("rows.zig"); +const Stage = @import("stage.zig").Stage; 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`. + /// A register's value (its first hop), by its place in `Regs.names`. register: usize, - /// The word of memory at this address, wherever it is shown. + /// The registers panel: a link leaves from its edge. + registers, + /// A stack slot's row, by its address. word: u64, - /// The object at this address, as an idea. + /// The pin lane of a stack slot, by its address. + slot_pin: u64, + /// A drawn node, by its address; its address over it; the pin under it. node: u64, - /// The source's current line; the disassembly's. + node_address: u64, + node_pin: u64, + /// A part of a node (its value, its pointer half), by the address of the field it is drawn from. + node_part: u64, + /// A run of bytes in the lens's dump, by its address. + dump_run: u64, + /// The source's current line; the disassembly's pc row; each run of + /// the current line's instructions in the disassembly. source, pc, + run: usize, fn key(p: Place) u64 { + const low = (1 << 56) - 1; 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, + .register => |i| 1 << 56 | @as(u64, i), + .registers => 2 << 56, + .word => |a| 3 << 56 | (a & low), + .slot_pin => |a| 4 << 56 | (a & low), + .node => |a| 5 << 56 | (a & low), + .node_address => |a| 6 << 56 | (a & low), + .node_pin => |a| 7 << 56 | (a & low), + .node_part => |a| 8 << 56 | (a & low), + .dump_run => |a| 9 << 56 | (a & low), + .source => 10 << 56, + .pc => 11 << 56, + .run => |k| 12 << 56 | @as(u64, k), }; } }; /// 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 table: [512]struct { key: u64, box: [4]f32 } = undefined; var said: usize = 0; /// `r` (in `u`'s units) is where `place` is, this frame. @@ -68,72 +92,185 @@ fn find(place: Place) ?[4]f32 { return null; } +/// When register `i` strikes in this step: the registers one step wrote +/// strike 6 f apart, in the registers' order; from the fourth on with the +/// third, within the CPU's slot of the cascade. +pub fn strikeDelay(now: cursors.Now, i: usize) f32 { + var before: f32 = 0; + for (theme.metric.all_registers[0..16]) |name| { + const k = @import("context.zig").index(name).?; + if (k == i) break; + if (now.registerAge(k) == 0) before += 1; + } + return @min(before * cursors.write_apart, time.cascade); +} + +/// How long a link draws: to a slot near by, or across to the lens. +pub fn linkTime(target: enum { slot, node }) f32 { + return if (target == .slot) time.link.in else time.link.in_far; +} + +/// How much a pin of register `i` shows at the place it pointed at +/// before this step (`old`) and at the one it points at now (`new`): +/// 6 f after its strike the old pin fades (12 f); the new lands with +/// its link's head and settles (12 f). At a run or a sprint it moves +/// with its level; at rest, and for a register the step did not write, +/// both are 1. +pub fn pinShows(now: cursors.Now, i: usize, target: enum { slot, node }) struct { old: f32, new: f32 } { + if (now.resting() or now.registerAge(i) != 0) return .{ .old = 1, .new = 1 }; + const since = now.since(.cpu, strikeDelay(now, i)); + if (!now.walking()) return if (since >= 0) .{ .old = 0, .new = 1 } else .{ .old = 1, .new = 0 }; + const l = time.link; + const arrives = l.after + linkTime(if (target == .slot) .slot else .node); + return .{ + .old = 1 - std.math.clamp((since - l.after) / l.pin_out, 0, 1), + .new = std.math.clamp((since - arrives) / l.settle, 0, 1), + }; +} + 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 }}, + stage: *const Stage, + box: Rect = .{ .x = 0, .y = 0, .w = theme.canvas.width, .h = theme.canvas.height }, + /// The thread: whether the scene draws it (a scene with no source has none). + threaded: bool = true, + /// No links: the registers are not marked (`Registers.quiet`). + quiet: bool = false, 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. + // In canvas pixels, `k` of them a unit: places 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]; + const split = g.stage.now(at); + if (g.threaded) thread(raw, at, k); + if (!now.walking()) return; + if (!g.quiet) g.link(raw, at, now, k, split); + g.projection(raw, at, now, k, split); + } - 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 }); + /// The gold thread: the current line and its instructions, one mark. + fn thread(raw: ui.Ui, at: anim.Placed, k: f32) void { + const line = find(.source) orelse return; + const x = at.xf.apply(.{ theme.metric.tie.thread_x, 0 })[0]; + const gold = theme.mark(.current).solid; + const kind = [2]f32{ theme.metric.bracket.thread[0] * k, theme.metric.bracket.thread[1] * k }; + raw.bracket(x, line[1] + 2 * k, line[3] - 2 * k, gold, kind, 1, false); + var bottom = line[3] - 2 * k; + var top = line[1] + 2 * k; + var n: usize = 0; + while (find(.{ .run = n })) |run| : (n += 1) { + raw.bracket(x, run[1] + 2 * k, run[3] - 2 * k, gold, kind, 1, false); + bottom = @max(bottom, run[3] - 2 * k); + top = @min(top, run[1] + 2 * k); } - 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); + if (n > 0) raw.fill(.{ .x = x - kind[0] / 2, .y = top, .w = kind[0], .h = bottom - top }, gold); + } + + /// The step's link: the first register it struck that now holds the + /// address of a pinned thing (a stack slot, a node). rip and rsp are + /// where execution and the stack are, and have none. + fn link(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void { + const rec = g.cursor.rec; 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 edge = find(.registers) orelse return; + for (theme.metric.all_registers[0..16]) |name| { + const i = @import("context.zig").index(name).?; + if (now.registerAge(i) != 0 or std.mem.eql(u8, name, "rsp")) 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 from = find(.{ .register = i }) orelse continue; + const node = find(.{ .node_pin = value }); + const target = node orelse find(.{ .slot_pin = value }) orelse continue; + const since = now.since(.cpu, strikeDelay(now, i)); + const l = time.link; + const drawn = cursors.standard(std.math.clamp((since - l.after) / linkTime(if (node != null) .node else .slot), 0, 1)); + const back = std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1); + if (drawn <= 0 or back >= 1) return; + const color = rows.ink(rows.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; + const lane = at.xf.apply(.{ theme.metric.tie.link_lane, 0 })[0]; + var points: [5]ui.Vec = undefined; + var n: usize = 0; + points[0] = .{ edge[0] + 2 * k, y }; + points[1] = .{ lane, y }; + if (node) |pin| { + // Up the gutter, along the lens's bottom lane, up into the pin under the node. + const bottom = at.xf.apply(.{ 0, split.band.y + split.band.h - theme.metric.lens.bottom_lane })[1]; + const cx = (pin[0] + pin[2]) / 2; + points[2] = .{ lane, bottom }; + points[3] = .{ cx, bottom }; + points[4] = .{ cx, pin[1] }; + n = 5; + } else { + // Along the gutter to the slot's row, and into its pin lane. + const mid = (target[1] + target[3]) / 2; + points[2] = .{ lane, mid }; + points[3] = .{ target[0] - 2 * k, mid }; + n = 4; + } + raw.route(points[0..n], color, .{ .width = theme.stroke.tie.link * k, .head = .{ 10 * k, 10 * k }, .progress = drawn, .from = cursors.standard(back), .radius = theme.metric.tie.radius * k }); + return; } } + + /// The step's projection: the first run of bytes it read or wrote in + /// the lens's dump that a part of the drawing is made of. + fn projection(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void { + const rec = g.cursor.rec; + const kinds = [2]struct { spans: []const @import("Recording.zig").Span, role: theme.Role }{ + .{ .spans = rec.written(now.stops[1], now.stops[0]), .role = .write }, + .{ .spans = rec.read(now.stops[1], now.stops[0]), .role = .read }, + }; + for (kinds) |kind| for (kind.spans) |span| { + const word = span.addr & ~@as(u64, 7); + const run = find(.{ .dump_run = word }) orelse continue; + const part = find(.{ .node_part = word }) orelse continue; + const node_addr = nodeOf(word) orelse continue; + const over = find(.{ .node_address = node_addr }) orelse continue; + const p = time.project; + const since = now.since(.memory, 0); + const bracket = std.math.clamp(since / p.bracket, 0, 1); + const drawn = cursors.standard(std.math.clamp((since - p.bracket) / p.draw, 0, 1)); + const out = 1 - std.math.clamp((now.time - now.plan.advance) / p.out, 0, 1); + if (bracket <= 0 or out <= 0) return; + const color = theme.mark(kind.role).solid; + const v = raw.faded(out); + const tie = [2]f32{ theme.metric.bracket.tie[0] * k, theme.metric.bracket.tie[1] * k }; + // The bracket takes the row: x 7 of the dump, the row's height. + const bx = run[0] - (rows.byteX(@intCast(word % 16)) - 4 - theme.metric.bytes.bracket) * k; + v.faded(bracket).bracket(bx, run[1] + 2 * k, run[3] - 2 * k, color, tie, 1, false); + const lane = at.xf.apply(.{ theme.metric.tie.projection_lane, 0 })[0]; + const top = at.xf.apply(.{ 0, split.band.y + theme.metric.context.tag + theme.metric.lens.top_lane })[1]; + const cx = (over[0] + over[2]) / 2; + const y = (run[1] + run[3]) / 2; + v.route(&.{ .{ bx - 1 * k, y }, .{ lane, y }, .{ lane, top }, .{ cx, top }, .{ cx, over[1] - 4 * k } }, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .radius = theme.metric.tie.projection_radius * k }); + // Over the node's address: a bracket, serifs down. + if (drawn >= 1) { + v.fill(.{ .x = over[0], .y = over[1] - 5 * k, .w = over[2] - over[0], .h = 3 * k }, color); + v.fill(.{ .x = over[0], .y = over[1] - 5 * k, .w = 3 * k, .h = 8 * k }, color); + v.fill(.{ .x = over[2] - 3 * k, .y = over[1] - 5 * k, .w = 3 * k, .h = 8 * k }, color); + } + _ = part; + return; + }; + } }; +/// The node a field's address belongs to: the drawn node at or below it, within a record. +fn nodeOf(addr: u64) ?u64 { + var best: ?u64 = null; + for (table[0..said]) |entry| { + if (entry.key >> 56 != 6) continue; + const a = entry.key & ((1 << 56) - 1); + if (a <= addr and addr - a < 64 and (best == null or a > best.?)) best = a; + } + return best; +} + 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()); + try std.testing.expect((Place{ .run = 0 }).key() != (Place{ .run = 1 }).key()); } |
