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
|
//! 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").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 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");
pub const Ties = tying.Ties;
pub const Place = tying.Place;
pub const Array = @import("array.zig").Array;
pub const Loupe = @import("loupe.zig").Loupe;
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 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 {
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; drawn small as the minimap. 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,
};
/// The ties between the panes, drawn over everything added before.
pub fn ties(c: Context, s: *anim.Frame) anim.Obj {
return add(s, Ties{ .cursor = c.cursor, .stage = c.stage, .quiet = c.quiet });
}
/// 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) });
return .{ add(s, Ties{ .cursor = c.cursor, .stage = c.stage, .quiet = c.quiet, .beat = beat }), 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 {
const stage = Stage.init(s, options.split);
var at = cursor_;
at.levels.crossings = options.syscalls;
// The map first: while it fills the frame or falls to the minimap 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 > 0, .{ 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.add(s, Source{ .cursor = at, .stage = whole.stage, .descent = options.descent });
whole.add(s, Source{ .cursor = at, .stage = whole.stage, .descent = options.descent, .part = .source_more });
if (options.descent) whole.add(s, Descent{ .cursor = at, .stage = whole.stage }) else whole.add(s, Disasm{ .cursor = at, .stage = whole.stage });
whole.add(s, Registers{ .cursor = at, .stage = whole.stage, .syscalls = options.syscalls, .quiet = options.quiet });
whole.add(s, Stack{ .cursor = at, .stage = whole.stage, .above = theme.map.stack_above });
// The stack goes on in the rest of the memory's column, from where its own column ends.
whole.add(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 });
whole.add(s, Backtrace{ .cursor = at, .stage = whole.stage });
whole.add(s, map.Spare{ .cursor = at, .stage = whole.stage, .map = whole });
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 }),
.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 }),
};
}
/// 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");
_ = tying;
_ = @import("hexdump.zig");
_ = calls;
_ = @import("nodes.zig");
_ = @import("array.zig");
_ = @import("loupe.zig");
_ = map;
_ = @import("syscalls.zig");
_ = objects;
_ = words;
}
|