summaryrefslogtreecommitdiff
path: root/anim/src/root.zig
blob: 82cf8d30942d38c6efaa98b6c52ea11453460f83 (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
//! 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, .{});             // the debugger's whole context
//!     canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace });
//!     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");
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 Source = @import("source.zig").Source;
const contexts = @import("context.zig");
pub const Registers = contexts.Registers;
pub const Stack = contexts.Stack;
pub const Backtrace = contexts.Backtrace;
pub const Disasm = contexts.Disasm;
pub const Locals = @import("registers.zig").Locals;
pub const calls = @import("calls.zig");
pub const CallTree = calls.Tree;
pub const Memory = @import("memory.zig").Memory;
pub const Nodes = @import("nodes.zig").Nodes;
pub const Heap = @import("heap.zig").Heap;
pub const Hexdump = @import("hexdump.zig").Hexdump;
const tying = @import("ties.zig");
pub const Ties = tying.Ties;
pub const Place = tying.Place;
pub const Array = @import("array.zig").Array;
pub const syscalls = @import("syscalls.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 Veil = words.Veil;
pub const Legend = words.Legend;

/// 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 {
    enter(s, views);
    s.wait(time.establish + time.establish_per_panel * @as(f32, @floatFromInt(views.len - 1)));
}

/// 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,

    pub fn line(n: *Narrator, s: *anim.Frame, text: []const u8) void {
        const next = add(s, Caption{ .text = text });
        if (n.current) |old| {
            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 });
        s.wait(if (n.current == null) time.caption_lead_first else time.caption_lead);
        n.current = next;
    }
};

/// 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: the state
/// column (every register followed as far as it points, the stack as a
/// telescope, the backtrace), and in the program column the source (all
/// of it, in a window) and the disassembly at the pc; and the clock.
/// A scene adds its lens at `split.lens`: a lens is never shown instead
/// of the machine it is drawn from.
pub const Context = struct {
    clock: anim.Obj,
    source: anim.Obj,
    disasm: anim.Obj,
    registers: anim.Obj,
    stack: anim.Obj,
    backtrace: anim.Obj,

    pub const Options = struct {
        /// How the program column is shared (`layout.split`).
        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,
    };
};

pub fn context(s: *anim.Frame, at: Cursor, options: Context.Options) Context {
    const source_at = add(s, Source{ .cursor = at, .box = options.split.source });
    const disasm_at = add(s, Disasm{ .cursor = at, .box = options.split.disasm });
    const registers_at = add(s, Registers{ .cursor = at, .syscalls = options.syscalls, .quiet = options.quiet });
    const stack_at = add(s, Stack{ .cursor = at });
    const backtrace_at = add(s, Backtrace{ .cursor = at });
    return .{ .clock = add(s, Clock{ .cursor = at }), .source = source_at, .disasm = disasm_at, .registers = registers_at, .stack = stack_at, .backtrace = backtrace_at };
}

/// Any component (a struct of this module with a `box`), in the scene
/// where its box says. The functions below are this, by name.
pub fn add(s: *anim.Frame, component: anytype) anim.Obj {
    return ui.place(s, component, component.box.x, component.box.y);
}

pub fn source(s: *anim.Frame, options: Source) anim.Obj {
    return add(s, options);
}
pub fn registers(s: *anim.Frame, options: Registers) anim.Obj {
    return add(s, options);
}
pub fn stack(s: *anim.Frame, options: Stack) anim.Obj {
    return add(s, options);
}
pub fn disasm(s: *anim.Frame, options: Disasm) anim.Obj {
    return add(s, options);
}
pub fn locals(s: *anim.Frame, options: Locals) anim.Obj {
    return add(s, options);
}
pub fn callTree(s: *anim.Frame, options: CallTree) anim.Obj {
    return add(s, options);
}
pub fn memory(s: *anim.Frame, options: Memory) anim.Obj {
    return add(s, options);
}
pub fn nodes(s: *anim.Frame, options: Nodes) anim.Obj {
    return add(s, options);
}
pub fn heap(s: *anim.Frame, options: Heap) anim.Obj {
    return add(s, options);
}
pub fn hexdump(s: *anim.Frame, options: Hexdump) anim.Obj {
    return add(s, options);
}
/// The connections between panes. Add it after every view it is to join.
pub fn ties(s: *anim.Frame, options: Ties) 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);
}
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("registers.zig");
    _ = contexts;
    _ = tying;
    _ = @import("hexdump.zig");
    _ = calls;
    _ = @import("memory.zig");
    _ = @import("nodes.zig");
    _ = @import("heap.zig");
    _ = @import("array.zig");
    _ = @import("syscalls.zig");
    _ = objects;
    _ = words;
}