summaryrefslogtreecommitdiff
path: root/anim/src/ties.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 20:08:07 -0300
committerGabriel Schneider <[email protected]>2026-11-11 21:45:12 -0300
commit15de88cf82c187635c1989e91bfa639a10304066 (patch)
tree16fa83854258c0c6aec1dff7f70ebabf5fd64c09 /anim/src/ties.zig
parent0ec2376cae2fdfc50e90d930ebc86c7a5b7f5594 (diff)
downloadcomputeranim-15de88cf82c187635c1989e91bfa639a10304066.tar.gz
computeranim-15de88cf82c187635c1989e91bfa639a10304066.zip
canim: a column of text as an experiment; the disassembly tied to the stack
From the user. A scene may set its text in a column beside the panes a beat is about: col.beat names the panes and their rows, where the text is placed (beside, below, above, or on a drawing) and what it is level with; panes the beat leaves out fold to their title bars on a shelf, their changes struck there. Tried as two scenes beside the originals: the call followed down (column) and a bubble on sort's rings (column_sort). annotation = .tied names the word an instruction touched and draws a touch to its stack row; offsets count from the frame's base; rsp's pin travels with its amount before the stack follows; .whole keeps the full chain. carry = .arrow draws a value's way between memory and a register. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/src/ties.zig')
-rw-r--r--anim/src/ties.zig145
1 files changed, 135 insertions, 10 deletions
diff --git a/anim/src/ties.zig b/anim/src/ties.zig
index 58ada36..1b6a6ed 100644
--- a/anim/src/ties.zig
+++ b/anim/src/ties.zig
@@ -25,6 +25,7 @@ const zt = @import("ztrace");
const ui = @import("ui.zig");
const cursors = @import("cursor.zig");
const rows = @import("rows.zig");
+const Recording = @import("Recording.zig");
const Stage = @import("stage.zig").Stage;
const theme = ui.theme;
const time = theme.time;
@@ -55,6 +56,13 @@ pub const Place = union(enum) {
source,
pc,
run: usize,
+ /// A row of the disassembly by its key (an instruction's address, a
+ /// descent's head's `descent.headKey`); the descent's floor, where the
+ /// kernel's window opens; a graph's pill by its block's address: what a
+ /// column's bubble is level with (`column.zig`).
+ row: u64,
+ floor,
+ block: u64,
fn key(p: Place) u64 {
const low = (1 << 56) - 1;
@@ -72,6 +80,9 @@ pub const Place = union(enum) {
.pc => 11 << 56,
.run => |k| 12 << 56 | @as(u64, k),
.dump_pin => |a| 13 << 56 | (a & low),
+ .row => |a| 14 << 56 | (a & low),
+ .floor => 15 << 56,
+ .block => |a| 16 << 56 | (a & low),
};
}
};
@@ -80,6 +91,10 @@ pub const Place = union(enum) {
/// where its pin lane runs (canvas pixels: x, the first row's top, the
/// row's height). A link to a word outside it ends at its edge.
pub var stack_window: ?struct { first: u64, slots: usize, x: f32, top: f32, row: f32 } = null;
+/// The disassembly's row the step's `touch` and `carry` leave from or reach,
+/// this frame (canvas pixels: its right rule's x, the row's top, that x, its
+/// bottom), where it is drawn (`Disasm.insn`).
+pub var touch_row: ?[4]f32 = null;
/// The source's line waits (a `descent`: the pc is in code without source):
/// the thread waits with it, primary and 2 units.
pub var thread_waits = false;
@@ -110,10 +125,15 @@ pub fn find(place: Place) ?[4]f32 {
/// call is back; in a continue, a wave, 2 f after the one above it. Its
/// pin and its link go with it.
pub fn strikeDelay(now: cursors.Now, i: usize) f32 {
+ // Under `tied` rsp and rbp strike as their pins land (`Now.pinLands`), not in the CPU's slot.
+ const pin = [2]?f32{ now.pinLands(0), now.pinLands(1) };
+ if (i == cursors.sp_index) if (pin[0]) |land| return land - now.plan.at[0];
+ if (i == cursors.bp_index) if (pin[1]) |land| return land - now.plan.at[0];
var before: f32 = 0;
for (theme.metric.all_registers[0..16]) |name| {
const k = @import("context.zig").index(name).?;
if (k == i) break;
+ if ((k == cursors.sp_index and pin[0] != null) or (k == cursors.bp_index and pin[1] != null)) continue;
if (now.registerAge(k) == 0) before += 1;
}
if (now.plan.wave) return before * time.continue_wave;
@@ -188,6 +208,7 @@ pub const Ties = struct {
defer said = 0;
defer stack_window = null;
defer thread_waits = false;
+ defer touch_row = null;
const now = g.cursor.now(at);
// Diving or surfacing, the panels are on their way: no ties; nor while the map alone is looked at.
for (@import("context.zig").zoomed) |z| if (z != null) return;
@@ -200,8 +221,107 @@ pub const Ties = struct {
if (g.threaded) thread(raw.faded(@import("context.zig").thread_shows), at, k);
if (g.beat) |b| named(raw, at, now, k, split, b);
if (!now.walking()) return;
- if (!g.quiet) g.link(raw, at, now, k, split);
- g.projection(raw, at, now, k, split);
+ const linked = !g.quiet and g.link(raw, at, now, k, split);
+ const projected = g.projection(raw, at, now, k, split);
+ // Three lines at most: the touch is the first to give way (to an echo), where a step draws a link and a projection.
+ if (!(linked and projected)) g.touch(raw, at, now, k, split);
+ g.carry(raw, at, now, k);
+ }
+
+ /// `touch` (design/README.md, "4. Ties"), `tied`, in a walked step: this
+ /// instruction reads or writes that word. From the disassembly's right
+ /// rule level with the row, into the gutter's middle lane (x 956), up or
+ /// down it to the word's height, onto the stack's rule, a head 7 by 8 on
+ /// it: 2 units in read's colour or write's vermilion, 12 f (18 f past six
+ /// rows), `standard`, from `Plan.touch`; held to the advance and drawn
+ /// back into the row with it (12 f), or, a load carried, as the carry
+ /// leaves the word. Only to a word on show: the window is there first.
+ fn touch(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void {
+ if (now.plan.touch < 0 or now.time < now.plan.touch) return;
+ const row = touch_row orelse return;
+ const tt = cursors.stackTouch(g.cursor.rec, now.stops[1], now.stops[0]) orelse return;
+ const word = find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane_pin = find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane = at.xf.apply(.{ theme.metric.tie.touch_lane, 0 })[0];
+ // Onto the stack's rule nearer the lane: its left in the state column, its right
+ // where it stands under the disassembly (a column's beat), the head pointing back.
+ const left = lane_pin[0] - theme.metric.slot.lane * k;
+ const rule = if (left > lane) left else at.xf.apply(.{ split.stack.x + split.stack.w, 0 })[0];
+ const ya = (row[1] + row[3]) / 2;
+ const yb = (word[1] + word[3]) / 2;
+ const long = @abs(yb - ya) > 6 * theme.metric.context.row * k;
+ const drawn = cursors.standard(std.math.clamp((now.time - now.plan.touch) / @as(f32, if (long) time.tied.touch_long else time.tied.touch), 0, 1));
+ const back_at = if (now.plan.carry >= 0 and !tt.write) now.plan.carry else now.plan.advance;
+ const back = cursors.standard(std.math.clamp((now.time - back_at) / time.quick, 0, 1));
+ if (back >= 1) return;
+ const color = theme.mark(if (tt.write) .write else .read).solid;
+ raw.route(&.{ .{ row[0], ya }, .{ lane, ya }, .{ lane, yb }, .{ rule, yb } }, color, .{ .width = theme.stroke.tie.projection * k, .head = .{ 7 * k, 8 * k }, .progress = @min(drawn, 1 - back), .radius = theme.metric.tie.radius * k });
+ }
+
+ /// `carry` (design/README.md, "4. Ties"; `Levels.carry`), in a walked
+ /// step: this value went from that word into this register, or from this
+ /// register into that word (a load, a store, a push's register, a pop's).
+ /// 2 units in primary, an open chevron 7 by 8 drawn in two strokes: from
+ /// the source's rule level with its row, along the gutter's right lane
+ /// (x 962) between the stack and the registers, onto the destination's
+ /// rule; 18 f (24 f past eight rows), `standard`, from `Plan.carry`, a
+ /// store's register framed as read the 6 f before; drawn back as the
+ /// destination strikes (18 f). With `carry_value` the value's digits ride
+ /// its head on a `raised` chip, landing as the strike.
+ fn carry(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32) void {
+ if (now.plan.carry < 0) return;
+ const rec = g.cursor.rec;
+ const tt = cursors.stackTouch(rec, now.stops[1], now.stops[0]) orelse return;
+ const how = cursors.carried(rec, tt) orelse return;
+ const i = @import("context.zig").index(how.reg) orelse return;
+ const reg = find(.{ .register = i }) orelse return;
+ const panel = find(.registers) orelse return;
+ const word = find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane_pin = find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return;
+ const stack_rule = lane_pin[0] - theme.metric.slot.lane * k;
+ const lane = at.xf.apply(.{ theme.metric.tie.projection_lane, 0 })[0];
+ const y_reg = (reg[1] + reg[3]) / 2;
+ const y_word = (word[1] + word[3]) / 2;
+ const strike = if (how.load) now.plan.at[0] else now.plan.at[1];
+ // A store's register framed as read first (6 f), held while its value goes.
+ if (!how.load) {
+ const inv = at.xf.invert();
+ const a = inv.apply(.{ reg[0], reg[1] });
+ const c = inv.apply(.{ reg[2], reg[3] });
+ const shows = std.math.clamp((now.time - now.plan.carry + time.read.in) / time.read.in, 0, 1) * (1 - std.math.clamp((now.time - now.plan.advance) / time.read.out, 0, 1));
+ (ui.Ui{ .f = raw.f, .at = at }).read(.{ .x = a[0], .y = a[1], .w = c[0] - a[0], .h = c[1] - a[1] }, shows);
+ }
+ if (now.time < now.plan.carry) return;
+ const far = @abs(y_reg - y_word) > 8 * theme.metric.context.row * k;
+ const drawn = cursors.standard(std.math.clamp((now.time - now.plan.carry) / @as(f32, if (far) time.tied.carry_long else time.tied.carry), 0, 1));
+ const back = cursors.standard(std.math.clamp((now.time - strike) / (18.0 / 60.0), 0, 1));
+ if (back >= 1) return;
+ const points: [4]ui.Vec = if (how.load) .{ .{ stack_rule, y_word }, .{ lane, y_word }, .{ lane, y_reg }, .{ panel[0], y_reg } } else .{ .{ panel[0], y_reg }, .{ lane, y_reg }, .{ lane, y_word }, .{ stack_rule, y_word } };
+ const color = theme.color.text.primary;
+ raw.route(&points, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .from = back, .radius = theme.metric.tie.radius * k });
+ // The open chevron at its head, two strokes.
+ const tip = along(&points, drawn);
+ const behind = along(&points, @max(drawn - 0.02, 0));
+ const dir = sk.math.normalize(if (sk.math.distance(tip, behind) > 0.01) tip - behind else points[3] - points[2]);
+ const side = sk.math.scale(sk.math.perp(dir), 4 * k);
+ const tail = tip - sk.math.scale(dir, 7 * k);
+ raw.line(tail + side, tip, color, theme.stroke.tie.projection * k);
+ raw.line(tail - side, tip, color, theme.stroke.tie.projection * k);
+ // `value`: the digits on a raised chip at the head, gone as the strike lands.
+ if (now.plan.carry_value) {
+ const shows = 1 - std.math.clamp((now.time - strike) / time.strike.in, 0, 1);
+ if (shows <= 0) return;
+ const value = if (how.load) (Recording.word(rec.moment(now.stops[0]), tt.addr, @intCast(@min(tt.len, 8))) catch null) orelse return else rec.register(tt.at, how.reg);
+ const v = raw.faded(shows);
+ const text = v.print("{x}", .{value});
+ const size = theme.size.mono.context * k;
+ const w = v.width(.mono, size, text) + 12 * k;
+ const h = theme.metric.context.row * k;
+ // Beside the head, on the lane's outer side: never over the rules.
+ const box: ui.Rect = .{ .x = lane - w - 6 * k, .y = tip[1] - h / 2, .w = w, .h = h };
+ v.fill(box, theme.color.raised);
+ v.text(.mono_bold, size, box.x + 6 * k, theme.baseline(box.y, h, size), text, theme.color.text.bright);
+ }
}
/// The gold thread: the current line and its instructions, one mark.
@@ -225,20 +345,23 @@ pub const Ties = struct {
/// The step's link: the first register it struck that now holds the
/// address of a pinned thing (a stack slot, a node, a view's row). 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 {
+ fn link(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) bool {
const rec = g.cursor.rec;
- const regs = (now.moment().regs(rec.tid) catch null) orelse return;
+ const regs = (now.moment().regs(rec.tid) catch null) orelse return false;
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;
+ // `tied`: rbp's move is its pin's flight in the stack's lane, not a link.
+ if (i == cursors.bp_index and now.pinGone(1) != null) continue;
const value = regs.named(name) orelse continue;
const since = linkSince(now, i);
const l = time.link;
const node = find(.{ .node_pin = value }) != null;
const drawn = cursors.standard(std.math.clamp((since - l.after) / linkTime(if (node) .node else .slot), 0, 1));
const back = std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1);
- if (linkTo(raw, at, now, k, split, name, value, drawn, back)) return;
+ if (linkTo(raw, at, now, k, split, name, value, drawn, back)) return true;
}
+ return false;
}
/// A link from register `name` to what it points at (`value`): a node's
@@ -340,7 +463,7 @@ pub const Ties = struct {
/// 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 {
+ fn projection(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) bool {
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 },
@@ -360,11 +483,12 @@ pub const Ties = struct {
const node_addr = if (stacked) span.addr else nodeOf(word) orelse continue;
const over = find(.{ .node_address = node_addr }) orelse continue;
const p = time.project;
- const since = now.since(.memory, 0);
+ // Under `tied`, once what made them has shown (a call's push, rsp's pin landed: `Plan.project`).
+ const since = if (now.plan.project >= 0) now.time - now.plan.project else now.since(.memory, 0);
const bracket = std.math.clamp(since / p.bracket, 0, 1);
const drawn = cursors.standard(std.math.clamp((since - p.bracket) / @as(f32, if (stacked) p.far else 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;
+ if (bracket <= 0 or out <= 0) return true;
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 };
@@ -386,7 +510,7 @@ pub const Ties = struct {
v.fill(.{ .x = over[0], .y = over[3] - 3 * k, .w = 3 * k, .h = 8 * k }, color);
v.fill(.{ .x = over[2] - 3 * k, .y = over[3] - 3 * k, .w = 3 * k, .h = 8 * k }, color);
}
- return;
+ return true;
}
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];
@@ -397,8 +521,9 @@ pub const Ties = struct {
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);
}
- return;
+ return true;
};
+ return false;
}
};