//! 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: //! //! - `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. //! //! 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 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 (its first hop), by its place in `Regs.names`. register: usize, /// The registers panel: a link leaves from its edge. registers, /// A stack slot's row, by its address. word: u64, /// 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, 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 << 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: [512]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; } /// 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, 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); // 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; 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); } /// 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 (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; 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 = 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 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()); }