summaryrefslogtreecommitdiff
path: root/anim/src/root.zig
blob: a165d2a4c86b6fc0472fe6a70003a5eb99049b84 (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
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
//! canim: animations of how a program ran, from a ztrace recording, on
//! sketchbook's `anim`. A scene is a short function:
//!
//!     const canim = @import("canim");
//!     const rec = canim.open(recordings.sort);
//!     const at = canim.cursor(s, rec, 0);                // where the picture is
//!     const ctx = canim.context(s, at, .{ .split = canim.layout.split.beside });  // the debugger's whole context
//!     canim.establish(s, .{ ctx.registers, ctx.stack, ctx.source, ctx.disasm, ctx.ties });
//!     at.walk(s, .line, rec.call("sort", 0).enter);      // play the program forward
//!
//! Every component is an `anim` object (`fadeIn`, `move`, ...) that draws
//! the program's state at the cursor, and what the step being taken does,
//! in the order it would be said: the line fires, its effects land a level
//! at a time, the mark moves on (design/motion.md).
const std = @import("std");
const anim = @import("anim");

pub const theme = @import("theme.zig");
pub const layout = theme.layout;
pub const ui = @import("ui.zig");
pub const Rect = theme.Rect;
pub const Recording = @import("Recording.zig");
/// The tracer's reader, for what a scene reads itself (`ztrace.heap.glibc`).
pub const ztrace = @import("ztrace");
const cursors = @import("cursor.zig");
pub const Cursor = cursors.Cursor;
pub const Now = cursors.Now;
pub const Plan = cursors.Plan;
pub const Levels = cursors.Levels;

pub const rows = @import("rows.zig");
pub const Stage = @import("stage.zig").Stage;
pub const source = @import("source.zig");
pub const Source = source.Source;
const contexts = @import("context.zig");
pub const Registers = contexts.Registers;
pub const Stack = contexts.Stack;
pub const Backtrace = contexts.Backtrace;
/// A panel's `Ui` at its box on the stage now (in a dive, on its way out of its window on the map).
pub const panelAt = contexts.at;
/// The registers' tag: what an address's ink says.
pub const contextLegend = contexts.legend;
pub const disasm = @import("disasm.zig");
pub const Disasm = disasm.Disasm;
pub const Descent = @import("descent.zig").Descent;
pub const graph = @import("graph.zig");
pub const calls = @import("calls.zig");
pub const CallTree = calls.Tree;
pub const Nodes = @import("nodes.zig").Nodes;
pub const hexdump = @import("hexdump.zig");
const tying = @import("ties.zig");
/// The relations' tables and the resolver's pure passes (design/README.md, "4. Ties").
pub const relations = @import("relations.zig");
pub const Ties = tying.Ties;
pub const Place = tying.Place;
/// Says where a place is this frame, for a scene's own component the ties should find.
pub const anchor = tying.anchor;
/// Where a place is this frame, in canvas pixels, if a panel said (`ties.find`).
pub const findPlace = tying.find;
pub const Array = @import("array.zig").Array;
pub const Loupe = @import("loupe.zig").Loupe;
pub const minimap = @import("map.zig");
pub const syscalls = @import("syscalls.zig");
pub const descent = @import("descent.zig");
pub const Crossing = syscalls.Crossing;
pub const Timeline = syscalls.Timeline;
pub const objects = @import("objects.zig");
const words = @import("words.zig");
pub const Clock = words.Clock;
pub const Caption = words.Caption;
pub const Label = words.Label;
pub const Title = words.Title;
pub const ChapterLabel = words.ChapterLabel;
/// A `Ui` in the design's units that the camera does not move (`words.fixed`).
pub const fixed = words.fixed;
pub const Veil = words.Veil;
pub const Legend = words.Legend;
/// The column (design/README.md, "column (an experiment)"): beat by beat,
/// the panes a beat is about on the left, its text beside them, the rest
/// folded to their tags on the shelf (`column.zig`).
const columns = @import("column.zig");
pub const Column = columns.Column;
pub const column = columns.column;
/// A column pane's rows: what the column has left.
pub const column_rest = columns.rest;
/// Two runs against each other (design/README.md, `pair`): each side's
/// stage (`pair.split`), the frame as bytes (`pair.Frame`), a stopped
/// run's output (`pair.Report`), the marks across the seam, the clock.
pub const pair = @import("pair.zig");
/// The introduction's blocks (design/motion.md, "A scene: the
/// introduction"): the address space to scale (`segments`), the bytes at
/// the stack's top made words (`regroup`), a text beside its part (`Aside`).
pub const segments = @import("segments.zig");
pub const Segments = segments.Segments;
pub const regroup = @import("regroup.zig");
pub const Words = regroup.Words;
pub const Aside = @import("aside.zig").Aside;
pub const Asides = @import("aside.zig").Asides;
/// The source with its instructions, one panel, each line level with its code (`aligned`).
pub const aligned = @import("aligned.zig");
pub const Aligned = aligned.Aligned;

/// The page behind every scene: `pub const background = canim.background;`.
pub const background: u32 = theme.color.page;

pub const open = Recording.open;
pub const lookAt = ui.lookAt;

/// A cursor on `rec`, at rest at moment `start`.
pub fn cursor(s: *anim.Frame, rec: *Recording, start: u64) Cursor {
    return .init(s, rec, start);
}

/// The design's easing curves, as `play` takes them.
pub const ease = struct {
    pub fn standard(t: f32) f32 {
        return theme.ease(.standard, t);
    }
    pub fn enter(t: f32) f32 {
        return theme.ease(.enter, t);
    }
    pub fn exit(t: f32) f32 {
        return theme.ease(.exit, t);
    }
    pub fn glide(t: f32) f32 {
        return theme.ease(.glide, t);
    }
};

const time = theme.time;

/// Brings `views` (a tuple of them) in, each a little after the one
/// before, in the order given: the source first (overlapping action).
/// Opacity is linear: a fade has no weight.
pub fn enter(s: *anim.Frame, views: anytype) void {
    const start = s.cursor;
    inline for (views, 0..) |o, i| {
        s.cursor = start + @as(f32, @floatFromInt(i)) * time.snap;
        s.play(.{o.fadeIn()}, .{ .seconds = time.cascade, .ease = anim.ease.linear });
    }
}

/// A scene's opening: the clock and the panels come in (`enter`), and
/// then the picture is still long enough to be read, a second and half a
/// second for each panel, before a word is said about it.
pub fn establish(s: *anim.Frame, views: anytype) void {
    const start = s.cursor;
    enter(s, views);
    // The first caption at a second: the picture is read under it.
    s.wait(@max(start + time.establish - s.cursor, 0));
}

/// And takes them away: quicker than they came.
pub fn leave(s: *anim.Frame, views: anytype) void {
    if (views.len == 0) return;
    var all: [views.len]anim.Animation = undefined;
    inline for (views, 0..) |o, i| all[i] = o.fadeOut();
    s.play(all, .{ .seconds = time.camera_clear, .ease = anim.ease.linear });
}

/// The narrator: one caption at a time, and only while nothing else
/// moves. The old one leaves, then nothing, then the new one arrives (two
/// crossfading are an unreadable third); and the stage stays still after
/// it, longer after a scene's first: the eye reads, then is shown.
pub const Narrator = struct {
    current: ?anim.Obj = null,
    /// When the caption on screen has been up long enough to be read.
    read_by: f32 = 0,

    pub fn line(n: *Narrator, s: *anim.Frame, text: []const u8) void {
        const next = add(s, Caption{ .text = text });
        if (n.current) |old| {
            // Not before the one up has been read: what follows waits.
            s.wait(@max(n.read_by - s.cursor, 0));
            s.play(.{old.fadeOut()}, .{ .seconds = time.caption_out, .ease = ease.exit });
            s.wait(time.caption_gap);
        }
        s.play(.{next.fadeIn()}, .{ .seconds = time.caption_in, .ease = ease.enter });
        n.read_by = s.cursor + time.caption(@intCast(std.unicode.utf8CountCodepoints(text) catch text.len));
        s.wait(if (n.current == null) time.caption_lead_first else time.caption_lead);
        n.current = next;
    }

    /// A scene's close: the last picture still, and the last caption read.
    pub fn close(n: *Narrator, s: *anim.Frame) void {
        s.wait(time.before_cut);
        s.wait(@max(n.read_by - s.cursor, 0));
    }
};

/// The camera, directed: a way of reading the context, not a place to be
/// instead of it. It never leaves unannounced: its target is framed
/// bright, everything else on the stage is gone before it moves (the
/// clock and the caption stay), it moves alone, and then the picture is
/// still; and it comes back to the whole frame every time. Call `apply`
/// last in the scene's `frame`.
pub const Camera = struct {
    at: anim.Camera = .{},
    moves: [8]Move = undefined,
    count: usize = 0,

    const Move = struct { from: anim.Camera, to: anim.Camera, p: anim.Value };

    /// Nearer: to design rect `box` at `zoom` (1.5, 2 or 4), with `others`
    /// (a tuple of the views that are not its subject) cleared first.
    pub fn go(c: *Camera, s: *anim.Frame, box: Rect, zoom: f32, others: anytype) void {
        // Anticipation: where it is going, before it goes.
        const frame = add(s, words.Outline{ .box = box });
        const start = s.cursor;
        s.play(.{frame.fadeIn()}, .{ .seconds = time.snap, .ease = anim.ease.linear });
        s.cursor = start + time.quick;
        leave(s, others);
        s.cursor = @max(s.cursor, start + time.camera_before);
        const moving = s.cursor;
        s.play(.{frame.fadeOut()}, .{ .seconds = time.quick, .ease = anim.ease.linear });
        s.cursor = moving;
        c.move(s, ui.framing(box, zoom), time.camera);
        s.wait(time.camera_after);
    }

    /// Back to the whole frame: the move, then `others` come in again, then stillness.
    pub fn back(c: *Camera, s: *anim.Frame, others: anytype) void {
        c.move(s, .{}, time.camera);
        enter(s, others);
        s.wait(time.camera_after);
    }

    fn move(c: *Camera, s: *anim.Frame, to: anim.Camera, seconds: f32) void {
        const p = s.value(0);
        c.moves[c.count] = .{ .from = c.at, .to = to, .p = p };
        c.count += 1;
        c.at = to;
        // Slow in and slow out: the camera has weight.
        s.play(.{p.to(1)}, .{ .seconds = seconds, .ease = ease.glide });
    }

    /// Puts the scene's camera where the moves so far have it at this instant.
    pub fn apply(c: *const Camera, s: *anim.Frame) void {
        var view: anim.Camera = .{};
        for (c.moves[0..c.count]) |m| {
            const p = s.get(m.p);
            if (p > 0) view = ui.between(m.from, m.to, p);
        }
        s.camera().* = view;
    }
};

/// The debugger's whole context, the same in every scene (design/README.md,
/// "5. The frame"): the state column (every register followed as far as it
/// points, the stack with its frames, the backtrace where there is room),
/// the program column (the whole source in a window, the disassembly at
/// the pc), the ties between them, and the clock. A scene adds its lens in
/// the band (`stage`): a lens is never shown instead of the machine.
pub const map = @import("map.zig");

pub const Context = struct {
    stage: *Stage,
    /// The working frame unfolded (`map.Map`): its panels, on a stage of its
    /// own; each pane's column of it is the pane's strip. A lens adds its drawing with `map.add`.
    map: *map.Map,
    clock: anim.Obj,
    source: anim.Obj,
    disasm: anim.Obj,
    registers: anim.Obj,
    stack: anim.Obj,
    backtrace: anim.Obj,
    /// The ties: add it after the lens, with `ties`.
    cursor: Cursor,
    quiet: bool,

    pub const Options = struct {
        /// How the stage is shared (`layout.split`); `Stage.relayout` changes it.
        split: layout.Split = layout.split.beside,
        /// A program that makes system calls: see `Registers.syscalls`.
        syscalls: bool = false,
        /// An instrumented program: see `Registers.quiet`.
        quiet: bool = false,
        /// The `backtrace` lens: the call chain as the band's drawing
        /// (eleven rows as subject, five beside), when how the program came
        /// to be here is the story; the scene adds the drawing's view.
        backtrace: bool = false,
        /// The disassembly as a `descent`: a call followed down opens its
        /// callee's window under the call row, and a system call the
        /// kernel's under the `syscall` (step with `descent.step`).
        descent: bool = false,
        /// On the map the function's graph as the `blocks` lens draws it
        /// (`graph.Blocks`), the map's drawing over the source; the
        /// disassembly beside it linear, its blocks ruled.
        graph: bool = false,
        /// The registers the scene moves, where not its clock's way's
        /// (`movedBy`): a scene in chapters has one set for all of them.
        moves: ?u32 = null,
    };

    /// The ties between the panes, drawn over everything added before.
    pub fn ties(c: Context, s: *anim.Frame) anim.Obj {
        const obj = add(s, Ties{ .cursor = c.cursor, .stage = c.stage, .quiet = c.quiet });
        c.unrolls(s);
        return obj;
    }

    /// Over everything added before: a pane's column unrolled (`map.Unroll`).
    fn unrolls(c: Context, s: *anim.Frame) void {
        const o = add(s, map.Unroll{ .map = c.map });
        s.play(.{o.fadeIn()}, .{ .seconds = 0 });
    }

    /// The ties, and a link the scene plays on a beat of its own (`Beat.play`):
    /// register `name` framed as read, then linked to what it points at, held `hold`.
    pub fn tiesWith(c: Context, s: *anim.Frame, name: []const u8, hold: f32) struct { anim.Obj, *const tying.Beat } {
        const beat = s.new(tying.Beat{ .cursor = c.cursor, .name = name, .hold = hold, .t = s.value(-1) });
        const obj = add(s, Ties{ .cursor = c.cursor, .stage = c.stage, .quiet = c.quiet, .beat = beat });
        c.unrolls(s);
        return .{ obj, beat };
    }

    /// A scene's opening with a lens drawn from bytes (`nodes`, `array`):
    /// as `establish`, and from half a second in the drawing's
    /// `elements` come in, each rising 8 units, 2 f apart in address
    /// order (`ties.rise`), beside their rows' quiet brackets; no lines.
    pub fn establish(c: Context, s: *anim.Frame, views: anytype, elements: usize) void {
        const start = s.cursor;
        s.play(.{c.stage.rise.to(0)}, .{ .seconds = 0 });
        s.cursor = start;
        enter(s, views);
        const done = s.cursor;
        s.cursor = start + time.establish_rise;
        const rising = tying.riseTime(elements);
        s.play(.{c.stage.rise.to(rising)}, .{ .seconds = rising, .ease = anim.ease.linear });
        s.cursor = @max(s.cursor, done);
        // The first caption at a second.
        s.wait(@max(start + time.establish - s.cursor, 0));
    }
};

pub fn context(s: *anim.Frame, cursor_: Cursor, options: Context.Options) Context {
    // The registers the scene moves keep their rows, the rest fold, chosen
    // once from its way; the panel is as tall as its rows, the stack has the rest.
    const moves = options.moves orelse contexts.movedBy(cursor_.rec, cursor_.by, .{ cursor_.first, cursor_.last });
    const registers_rows: f32 = @floatFromInt(contexts.registerRows(moves));
    const stage = Stage.init(s, layout.fit(options.split, registers_rows));
    stage.registers_rows = registers_rows;
    var at = cursor_;
    at.levels.crossings = options.syscalls;
    // The map first: while it fills the frame it is under the panels diving out of it.
    const whole = s.new(map.Map{ .stage = Stage.init(s, map.split(at.rec, options.split.band.h, .{ at.first, at.last })), .frame = stage, .t = s.value(map.diving.land + map.diving.still), .cursor = at });
    whole.obj = s.custom(whole, .{ .x = -640, .y = -360, .scale = ui.scale });
    whole.addIn(s, Source{ .cursor = at, .stage = whole.stage, .descent = options.descent }, .both, .source);
    whole.addIn(s, Source{ .cursor = at, .stage = whole.stage, .descent = options.descent, .part = .source_more }, .both, .source);
    // The graph on the map is the lens's drawing at its size, over the source.
    if (options.graph) whole.add(s, graph.Blocks{ .cursor = at, .stage = whole.stage });
    // The disassembly's strip is its linear column: where the map draws a
    // descent, the rows round the pc are drawn for the strip alone.
    if (options.descent) {
        whole.addIn(s, Descent{ .cursor = at, .stage = whole.stage }, .map, .disasm);
        whole.addIn(s, Disasm{ .cursor = at, .stage = whole.stage, .measures = false }, .strips, .disasm);
    } else whole.addIn(s, Disasm{ .cursor = at, .stage = whole.stage }, .both, .disasm);
    whole.addIn(s, Registers{ .cursor = at, .stage = whole.stage, .syscalls = options.syscalls, .quiet = options.quiet }, .map, .registers);
    whole.addIn(s, Stack{ .cursor = at, .stage = whole.stage, .above = theme.map.stack_above }, .both, .stack);
    // The stack goes on in the rest of the memory's column, from where its own column ends.
    whole.addIn(s, Stack{ .cursor = at, .stage = whole.stage, .above = theme.map.stack_above - @as(i32, @intCast(theme.layout.rowsIn(whole.stage.first.stack.h))), .part = .more }, .both, .stack);
    whole.addIn(s, Backtrace{ .cursor = at, .stage = whole.stage }, .map, .backtrace);
    // The rest of the first two columns: no pane's.
    whole.addIn(s, map.Spare{ .cursor = at, .stage = whole.stage, .map = whole }, .map, .backtrace);
    map.current = whole;
    // (Each frame anew: what a frame's `frame` made lives for that frame.)
    if (map.maps_frame != s.in.frame) {
        map.maps = @splat(null);
        map.maps_frame = s.in.frame;
    }
    for (&map.maps) |*slot| if (slot.* == null) {
        slot.* = whole;
        break;
    };
    return .{
        .stage = stage,
        .map = whole,
        .cursor = at,
        .quiet = options.quiet,
        .source = add(s, Source{ .cursor = at, .stage = stage, .descent = options.descent }),
        .disasm = if (options.descent) add(s, Descent{ .cursor = at, .stage = stage }) else add(s, Disasm{ .cursor = at, .stage = stage }),
        .registers = add(s, Registers{ .cursor = at, .stage = stage, .syscalls = options.syscalls, .quiet = options.quiet, .moves = moves }),
        .stack = add(s, Stack{ .cursor = at, .stage = stage }),
        .backtrace = add(s, Backtrace{ .cursor = at, .stage = stage, .lens = options.backtrace }),
        .clock = add(s, Clock{ .cursor = at, .map = whole, .stage = stage }),
    };
}

/// Any component of this module in the scene: one with a `box` where its
/// box says; one on the stage (it reads its box there each frame) at the origin.
pub fn add(s: *anim.Frame, component: anytype) anim.Obj {
    if (@hasField(@TypeOf(component), "box")) return ui.place(s, component, component.box.x, component.box.y);
    return ui.place(s, component, 0, 0);
}

pub fn callTree(s: *anim.Frame, options: CallTree) anim.Obj {
    return add(s, options);
}
pub fn nodes(s: *anim.Frame, options: Nodes) anim.Obj {
    return add(s, options);
}
pub fn array(s: *anim.Frame, options: Array) anim.Obj {
    return add(s, options);
}
/// The kernel's ground. Make a step that crosses it with `syscalls.step`.
pub fn crossing(s: *anim.Frame, options: Crossing) anim.Obj {
    return add(s, options);
}
pub fn timeline(s: *anim.Frame, options: Timeline) anim.Obj {
    return add(s, options);
}
/// A `loupe`, shut until its `open`: add it after the panels and the lens,
/// a deeper one after the loupe it hangs from, and the ties after them.
pub fn loupe(s: *anim.Frame, options: Loupe) *Loupe {
    var l = options;
    l.opening = s.value(0);
    l.closing = s.value(0);
    const made = s.new(l);
    const o = s.custom(made, .{ .x = -640, .y = -360, .scale = ui.scale });
    s.play(.{o.fadeIn()}, .{ .seconds = 0 });
    return made;
}
pub fn caption(s: *anim.Frame, text: []const u8) anim.Obj {
    return add(s, Caption{ .text = text });
}
pub fn label(s: *anim.Frame, options: Label) anim.Obj {
    return add(s, options);
}
pub fn veil(s: *anim.Frame, around: Rect) anim.Obj {
    return add(s, Veil{ .box = around });
}
pub fn legend(s: *anim.Frame, options: Legend) anim.Obj {
    return add(s, options);
}

test {
    _ = theme;
    _ = ui;
    _ = Recording;
    _ = cursors;
    _ = @import("source.zig");
    _ = @import("stage.zig");
    _ = rows;
    _ = contexts;
    _ = @import("disasm.zig");
    _ = @import("descent.zig");
    _ = graph;
    _ = tying;
    _ = relations;
    _ = @import("hexdump.zig");
    _ = calls;
    _ = @import("nodes.zig");
    _ = @import("array.zig");
    _ = @import("loupe.zig");
    _ = map;
    _ = @import("syscalls.zig");
    _ = objects;
    _ = words;
    _ = columns;
    _ = pair;
    _ = segments;
    _ = regroup;
    _ = @import("aside.zig");
    _ = aligned;
}