summaryrefslogtreecommitdiff
path: root/anim/src/ties.zig
blob: d3a9ec760e348f97816a246c27bc528a0a2c98f2 (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
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
//! 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),
        };
    }
};

/// The stack's window this frame: its first word, how many it shows, and
/// 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 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;

/// 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 or ui.mapping) 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;
}

/// Where `place` is this frame, in canvas pixels (left, top, right, bottom), if a panel said.
pub 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; in a crossing, once the
/// 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 {
    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;
    }
    if (now.plan.wave) return before * time.continue_wave;
    return @min(before * cursors.write_apart, time.cascade) + @import("syscalls.zig").crossingDelay(now);
}

/// Seconds since register `i`'s link (and its pin) set off: its strike;
/// in a continue, memory's, when the stack's window is at its new place
/// (a tie arrives at what is on screen, not at a window about to go).
fn linkSince(now: cursors.Now, i: usize) f32 {
    return if (now.plan.wave) now.since(.memory, 0) else now.since(.cpu, strikeDelay(now, i));
}

/// 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 it is where the register points, and only
/// there; for a register the step did not write, the two are one place.
pub fn pinShows(now: cursors.Now, i: usize, target: enum { slot, node }) struct { old: f32, new: f32 } {
    if (now.registerAge(i) != 0) return .{ .old = 1, .new = 1 };
    if (now.resting()) return .{ .old = 0, .new = 1 };
    const since = linkSince(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),
    };
}

/// `establish` for a lens: its element `k` (in address order), `r`
/// seconds into its elements' coming in: each fades in rising 8 units
/// over 12 f, 2 f after the one before (all begun by 12 f after the
/// first), with its row's quiet bracket beside it; no lines. How much of
/// it shows, and how far below its place it is.
pub fn rise(r: f32, k: usize, n: usize) struct { element: f32, below: f32 } {
    const apart = @min(time.stagger, time.quick / @as(f32, @floatFromInt(@max(n, 2) - 1)));
    const p = std.math.clamp((r - @as(f32, @floatFromInt(k)) * apart) / time.quick, 0, 1);
    const eased = theme.ease(.enter, p);
    return .{ .element = p, .below = (1 - eased) * time.caption_rise };
}

/// How long `n` elements take to come in.
pub fn riseTime(n: usize) f32 {
    const apart = @min(time.stagger, time.quick / @as(f32, @floatFromInt(@max(n, 2) - 1)));
    return @as(f32, @floatFromInt(n -| 1)) * apart + time.quick;
}

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;
        defer stack_window = null;
        defer thread_waits = false;
        const now = g.cursor.now(at);
        // Diving or surfacing, the panels are on their way: no ties.
        for (@import("context.zig").zoomed) |z| if (z != null) return;
        // 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 = if (thread_waits) ui.rgb(theme.color.text.primary) else ui.rgb(theme.mark(.current).solid);
        const kind = if (thread_waits) [2]f32{ theme.metric.bracket.quiet[0] * k, theme.metric.bracket.quiet[1] * k } else [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 });
            // A word of the stack outside its window: the link ends at the
            // window's edge, with a stub and how many words on it is.
            var beyond: ?i64 = null;
            const target = node orelse find(.{ .slot_pin = value }) orelse edge: {
                const w = stack_window orelse continue;
                if (value % 8 != 0 or rows.regionOf(now.moment(), value) != .stack) continue;
                const words = @as(i64, @bitCast(value -% w.first)) >> 3;
                if (words >= 0 and words < w.slots) continue;
                if (@abs(words) > 64) continue;
                beyond = if (words < 0) words else words - @as(i64, @intCast(w.slots)) + 1;
                // Its nearest row's pin lane.
                const y = if (words < 0) w.top else w.top + @as(f32, @floatFromInt(w.slots - 1)) * w.row;
                break :edge [4]f32{ w.x, y, w.x + 10 * k, y + w.row };
            };
            const since = linkSince(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;
            // What climbs into the band takes the gutter's left lane; what
            // goes down to a slot, the right.
            const lane = at.xf.apply(.{ if (node != null) theme.metric.tie.link_lane else theme.metric.tie.projection_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 if (beyond) |words| {
                // Off the window: to its nearest row, into the pin lane, out
                // to the panel's rule, where a head points on.
                const mid = (target[1] + target[3]) / 2;
                const rule = if (words < 0) target[1] - 6 * k else target[3] + 6 * k;
                points[2] = .{ lane, mid };
                points[3] = .{ target[0] + 6 * k, mid };
                points[4] = .{ target[0] + 6 * k, rule };
                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 = if (beyond == null) .{ 10 * k, 10 * k } else .{ 9 * k, 12 * k }, .progress = drawn, .from = cursors.standard(back), .radius = theme.metric.tie.radius * k });
            if (beyond) |words| if (drawn >= 1) {
                // How far the target is, faint, 6 past the head.
                const v = raw.faded(1 - std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1));
                const tip = points[4];
                v.text(.mono, theme.size.mono.context, tip[0] + 12 * k, tip[1] + (if (words < 0) @as(f32, 6) else 14) * k, v.print("{d} rows", .{@abs(words)}), theme.color.text.faint);
            };
            // The pin rides the line's head: the register's name beside it.
            if (drawn > 0 and drawn < 1 and beyond == null) {
                const tip = along(points[0..n], drawn);
                raw.text(.mono_bold, theme.size.mono.context, tip[0] + 8 * k, tip[1] - 6 * k, name, theme.color.text.primary);
            }
            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| {
            // The run that begins where the bytes do (an element of an
            // array), else the word they are in (a field of a node).
            const word = if (find(.{ .dump_run = span.addr }) != null) span.addr else span.addr & ~@as(u64, 7);
            // From the dump's run to the part of the drawing made of it; or
            // from a word of the stack to the call it is the way back of.
            const slot = find(.{ .word = span.addr });
            // (A return draws no line: its node's badge is struck with rax's digits.)
            const stacked = kind.role == .write and slot != null and find(.{ .node_address = span.addr }) != null and find(.{ .dump_run = word }) == null;
            const run = if (stacked) slot.? else find(.{ .dump_run = word }) orelse continue;
            if (!stacked) _ = find(.{ .node_part = word }) orelse continue;
            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);
            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;
            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;
            // on the stack, the panel's left padding.
            const bx = if (stacked) run[0] - (theme.metric.slot.address - 5) * k else 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 cx = (over[0] + over[2]) / 2;
            const y = (run[1] + run[3]) / 2;
            if (stacked) {
                // A frame's way back to its call's node: up the gutter's
                // left lane, along the drawing's bottom lane, up to a
                // bracket under the node, serifs up.
                const lane = at.xf.apply(.{ theme.metric.tie.link_lane, 0 })[0];
                const bottom = at.xf.apply(.{ 0, split.band.y + split.band.h - theme.metric.lens.bottom_lane })[1];
                v.route(&.{ .{ bx - 1 * k, y }, .{ lane, y }, .{ lane, bottom }, .{ cx, bottom }, .{ cx, over[3] + 5 * k } }, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .radius = theme.metric.tie.projection_radius * k });
                if (drawn >= 1) {
                    v.fill(.{ .x = over[0], .y = over[3] + 2 * k, .w = over[2] - over[0], .h = 3 * k }, color);
                    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;
            }
            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];
            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);
            }
            return;
        };
    }
};

/// The point `p` of the way along the straight path through `points`.
fn along(points: []const ui.Vec, p: f32) ui.Vec {
    var total: f32 = 0;
    for (points[0 .. points.len - 1], points[1..]) |a, b| total += sk.math.distance(a, b);
    var left = total * p;
    for (points[0 .. points.len - 1], points[1..]) |a, b| {
        const d = sk.math.distance(a, b);
        if (left <= d and d > 0) return sk.math.mix(a, b, left / d);
        left -= d;
    }
    return points[points.len - 1];
}

/// 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());
}