From 7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 14:48:26 -0300 Subject: canim: animations of recordings, as a debugger's whole context with a lens beside it A package of its own (anim/), on sketchbook's anim module and pardes's syntax. A scene opens a recording, takes a cursor into it, and declares blocks that read the moment the cursor is at: the state column (registers each followed as a pointer and inked by where it points, the stack telescope, the backtrace), the program column (the whole source, the disassembly in address order, and the scene's lens: a node-link list over a hexdump of its heap, array cells, a call tree, a syscall crossing), and ties between them. Motion is a step told as a sentence (the line fires, its effects cascade a level at a time, the mark moves on last), timed by what the step contains; walk, hurry and sprint pace a loop. Five scenes from real recordings of fib, a linked list, a sort and syscalls. First drafts, by the agent's own handover: the frame of the design's second revision, the hexdump lens and the ties; no disassembly annotations, no gallery, scenes not yet reviewed against the mocks. --- anim/src/root.zig | 303 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 anim/src/root.zig (limited to 'anim/src/root.zig') 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; +} -- cgit v1.3