summaryrefslogtreecommitdiff
path: root/anim/src/ties.zig
blob: d18b996ebbfc87b0e3d6c1fa42e4679264517f93 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
//! 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());
}