summaryrefslogtreecommitdiff
path: root/anim/src/root.zig
diff options
context:
space:
mode:
Diffstat (limited to 'anim/src/root.zig')
-rw-r--r--anim/src/root.zig303
1 files changed, 303 insertions, 0 deletions
diff --git a/anim/src/root.zig b/anim/src/root.zig
new file mode 100644
index 0000000..82cf8d3
--- /dev/null
+++ b/anim/src/root.zig
@@ -0,0 +1,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;
+}