//! 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"); 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; /// The registers' tag: what an address's ink says. pub const contextLegend = contexts.legend; pub const Disasm = @import("disasm.zig").Disasm; 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 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 { 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 Context = struct { stage: *Stage, 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 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 }); } /// 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; return .{ .stage = stage, .cursor = at, .quiet = options.quiet, .source = add(s, Source{ .cursor = at, .stage = stage }), .disasm = 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 }), }; } /// 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); } 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"); _ = tying; _ = @import("hexdump.zig"); _ = calls; _ = @import("nodes.zig"); _ = @import("array.zig"); _ = @import("syscalls.zig"); _ = objects; _ = words; }