summaryrefslogtreecommitdiff
path: root/anim/src/theme.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 14:48:26 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:14:31 -0300
commit7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch)
treea6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/src/theme.zig
parented46c51fe127377eb1fde8dee83da984e0f61860 (diff)
downloadcomputeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz
computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip
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.
Diffstat (limited to 'anim/src/theme.zig')
-rw-r--r--anim/src/theme.zig911
1 files changed, 911 insertions, 0 deletions
diff --git a/anim/src/theme.zig b/anim/src/theme.zig
new file mode 100644
index 0000000..9b18e59
--- /dev/null
+++ b/anim/src/theme.zig
@@ -0,0 +1,911 @@
+//! canim's look, as numbers: grounds and inks, the marks that mean something,
+//! type sizes, component metrics, and how long things take.
+//! `design/README.md` gives the reasons; `design/mock/` shows them drawn.
+//!
+//! Units are logical: the canvas is 1920 by 1080 of them whatever the export
+//! size, so a 4K master draws each as two pixels and nothing here changes.
+//! Colours are 0xRRGGBB and opaque. Nothing is tinted by alpha: an accent's
+//! quiet form is its own colour (its ember), because gold blended over lapis
+//! goes grey. The one translucent thing is `color.veil`.
+
+const std = @import("std");
+
+pub const Rect = struct { x: f32, y: f32, w: f32, h: f32 };
+
+// ---------------------------------------------------------------- canvas
+
+pub const canvas = struct {
+ pub const width = 1920;
+ pub const height = 1080;
+ /// Only the page, and the kernel's ground, come nearer an edge than this.
+ pub const margin_x = 64;
+ pub const margin_y = 48;
+ /// Twelve columns of 120 with gutters of 32 fill the 1792 between the margins.
+ pub const columns = 12;
+ pub const column = 120;
+ pub const gutter = 32;
+ /// Between panels one above another in a column.
+ pub const row_gap = 12;
+ /// The module: cells, rows, tags and code lines are multiples of 12.
+ pub const unit = 12;
+
+ /// Where the context and the lens go: 35 rows of 24. (Revision 2: the
+ /// running head is gone, and its rows went to the stage.)
+ pub const stage: Rect = .{ .x = 64, .y = 48, .w = 1792, .h = 840 };
+ /// The clock: a rule the width of the stage over the caption, gold
+ /// along it as far as the recording has run, the count under its right end.
+ pub const clock_y = 900;
+ /// Where the narrator's sentence goes. No data is ever drawn below y = 888:
+ /// the player's controls and its subtitles cover this band.
+ pub const caption: Rect = .{ .x = 64, .y = 912, .w = 1792, .h = 120 };
+ /// Baselines: a one-line caption, then the two lines of a two-line one.
+ pub const caption_baseline = [3]f32{ 990, 964, 1018 };
+ /// A caption line is no wider: about 64 characters at `size.caption`.
+ pub const caption_max_width = 1400;
+};
+
+/// Left edge of column `i` (0 to 11).
+pub fn colX(i: u8) f32 {
+ return @floatFromInt(@as(u32, canvas.margin_x) + @as(u32, i) * (canvas.column + canvas.gutter));
+}
+
+/// Width of `n` columns with the gutters between them.
+pub fn span(n: u8) f32 {
+ return @floatFromInt(@as(u32, n) * canvas.column + (@as(u32, n) - 1) * canvas.gutter);
+}
+
+/// `n` columns starting at column `first`, `y` below the stage's top, `h` tall.
+pub fn cols(first: u8, n: u8, y: f32, h: f32) Rect {
+ return .{ .x = colX(first), .y = canvas.stage.y + y, .w = span(n), .h = h };
+}
+
+/// How views share the stage. The order in each is the order of abstraction:
+/// source is leftmost, then the CPU, then memory; a lower level is never left
+/// of or above a higher one, and the kernel is always underneath.
+pub const layout = struct {
+ /// Two columns of 880. The program column: the lens, the source, the
+ /// disassembly, top to bottom (the idea, its text, its instructions).
+ /// The state column: what they act on, the same in every frame of
+ /// every scene.
+ pub const program = cols(0, 6, 0, canvas.stage.h);
+ pub const state = cols(6, 6, 0, canvas.stage.h);
+
+ /// The state column: every register (sixteen, rip, the flags), eight
+ /// words of stack, three frames of backtrace.
+ pub const registers = rows(state, 0, 18);
+ pub const stack = below(registers, 8);
+ pub const backtrace = below(stack, 3);
+
+ /// How the program column is shared: the one thing about the layout a
+ /// scene chooses. `lens` has no height where there is none.
+ pub const Split = struct { lens: Rect, source: Rect, disasm: Rect };
+ pub const split = struct {
+ /// The machine alone: the source over the disassembly, eight
+ /// instructions above the pc and eight below.
+ pub const none: Split = .{ .lens = .{ .x = program.x, .y = program.y, .w = program.w, .h = 0 }, .source = rows(program, 0, 14), .disasm = below(rows(program, 0, 14), 17) };
+ /// The default: the machine is the subject, the lens beside it.
+ /// (The user's direction after the design's revision: more of the
+ /// disassembly, so the source's window is shorter than the design's.)
+ pub const beside: Split = shared(312, 8, 10);
+ /// The idea is the subject: the lens a size up.
+ pub const subject: Split = shared(432, 5, 8);
+
+ fn shared(lens_h: f32, source_rows: f32, disasm_rows: f32) Split {
+ const lens: Rect = .{ .x = program.x, .y = program.y, .w = program.w, .h = lens_h };
+ const source: Rect = .{ .x = program.x, .y = lens.y + lens.h + canvas.row_gap, .w = program.w, .h = panelH(source_rows) };
+ return .{ .lens = lens, .source = source, .disasm = below(source, disasm_rows) };
+ }
+ };
+
+ /// A panel of `n` rows: a tag, the padding, the rows.
+ pub fn panelH(n: f32) f32 {
+ return metric.context.tag + 2 * metric.context.pad + n * metric.context.row;
+ }
+
+ fn rows(column: Rect, y: f32, n: f32) Rect {
+ return .{ .x = column.x, .y = column.y + y, .w = column.w, .h = panelH(n) };
+ }
+
+ fn below(r: Rect, n: f32) Rect {
+ return .{ .x = r.x, .y = r.y + r.h + canvas.row_gap, .w = r.w, .h = panelH(n) };
+ }
+};
+
+
+// ---------------------------------------------------------------- colour
+
+pub const color = struct {
+ /// The page: lapis, deep. Panels' bodies are the page too.
+ pub const page: u24 = 0x0a1030;
+ /// Tags, cells, cards, node bodies: anything that is a thing on the page.
+ pub const raised: u24 = 0x16245f;
+ /// Rules round panels, hollow cells, wedges, dividers, and the fill of
+ /// bookkeeping (allocator headers, pages merely present). 2 units wide as a
+ /// line; never the only carrier of anything, it is the first thing a
+ /// low-bitrate stream loses.
+ pub const rule: u24 = 0x3a4a8a;
+ /// The kernel's ground: vellum. Solid vellum means kernel at every scale
+ /// (the slab, a block on the timeline, a row of the page map) and nothing else.
+ pub const kernel: u24 = 0xeee6d2;
+
+ pub const text = struct {
+ /// Titles, and a value in flight.
+ pub const bright: u24 = 0xfff8e8;
+ /// Anything to be read. 14.9:1 on the page, 11.6:1 on `raised`.
+ pub const primary: u24 = 0xeee6d2;
+ /// Names, notes, things said about the data. 7.8:1 and 6.1:1.
+ pub const dim: u24 = 0x9aa6d9;
+ /// Furniture: leading zeros, the unchanging end of an address, line
+ /// numbers, column heads. 4.5:1 and 3.5:1; never the only carrier.
+ pub const faint: u24 = 0x6a7ab8;
+ /// Letters on a solid accent.
+ pub const ink: u24 = 0x050a24;
+ };
+
+ /// On the kernel's ground the page's colour is the ink, accents stay solid
+ /// inside a 2 unit ink frame, and there are no embers.
+ pub const on_kernel = struct {
+ pub const ink: u24 = 0x0a1030;
+ pub const dim: u24 = 0x4a5488;
+ pub const rule: u24 = 0xb9ad8e;
+ /// A byte the kernel changed a moment ago (the ember's stand-in).
+ pub const held: u24 = 0xf3b9a0;
+ };
+
+ /// Source code. Hue on letters is syntax and nothing else, and it is quiet:
+ /// keywords are also bold, comments also italic. The four are pardes's
+ /// classes (`kw`, `str` and `num`, `comment`); its `bg`, `fg` and `lineno`
+ /// are `page`, `text.primary` and `text.faint`.
+ pub const code = struct {
+ pub const plain: u24 = 0xeee6d2;
+ pub const keyword: u24 = 0xc0dcff;
+ pub const literal: u24 = 0xb5e8c8;
+ pub const comment: u24 = 0x9aa6d9;
+ };
+
+ /// A pointer is coloured by the memory it points into, as pwndbg colours
+ /// it: the stack yellow, the heap blue, code red, writable data purple;
+ /// a constant, and a number that is no pointer, plain. Memory that is
+ /// both writable and executable is code's colour, underlined.
+ /// (The debugger's whole context on screen: the user's direction, ahead
+ /// of the design's revision for it, which wins where it differs.)
+ pub const region = struct {
+ pub const stack: u24 = 0xf2d675;
+ pub const heap: u24 = 0x86b6ff;
+ pub const code_: u24 = 0xff8f9a;
+ pub const data: u24 = 0xd59cf5;
+ pub const rodata: u24 = 0xeee6d2;
+ pub const number: u24 = 0xeee6d2;
+ };
+ /// A string a pointer leads to, in quotes.
+ pub const string: u24 = 0xb5e8c8;
+
+ /// Where execution was: the last three places, newest first, gold cooling.
+ pub const trail = [3]u24{ 0xae9350, 0x746235, 0x463b20 };
+
+ /// Pigments: which object, thread or variable this is, the same in every
+ /// view. Dark bodies under `text.primary` (4.5:1 or better), so the bright
+ /// marks still read on top of them. Use them in this order, at most four in
+ /// a scene; only the first two are safe apart for every viewer, so each
+ /// also carries its name.
+ pub const pigment = [6]u24{
+ 0x8a5e0c, // ochre
+ 0x17707c, // teal
+ 0xa03060, // madder
+ 0x1c7450, // malachite
+ 0x6a3fb0, // violet
+ 0x2f5fc4, // azurite
+ };
+
+ /// Drawn over everything that is not the subject, to dim it.
+ pub const veil: u24 = page;
+ pub const veil_alpha: f32 = 0.65;
+};
+
+/// What a mark means. The same everywhere: a byte, a register, a source line,
+/// a tree node, a page, a block of time.
+pub const Role = enum {
+ /// Where execution is: the line, the instruction, rip, the newest frame.
+ current,
+ /// Written by this step; in its ember, changed within the last few.
+ write,
+ /// Read by this step.
+ read,
+ /// Holds an address, and the arrow to it.
+ pointer,
+ /// Handed out by an allocator.
+ allocated,
+ /// Handed back. No colour: its bytes are still there, and nobody owns them.
+ freed,
+ /// A signal, a failed call. Write's colour in a hazard band, always named.
+ fault,
+ /// What the narration is about now: framed, and the rest veiled.
+ attention,
+ /// A value on its way from one place to another.
+ flow,
+ /// Bytes the recording never observed.
+ unknown,
+ /// The other side of the system call boundary.
+ kernel,
+};
+
+/// How a role is drawn. No two roles share a form, so none is told by hue alone.
+pub const Form = enum {
+ /// A solid plaque on the thing's label and its ember across the row.
+ plaque,
+ /// A solid fill with ink letters, cooling to its ember and a solid bar along the bottom.
+ fill,
+ /// A frame, with its ember inside.
+ frame,
+ /// A frame round the bytes and an arrow from it, elbows filleted, head filled.
+ arrow,
+ /// Its ember inside a solid frame.
+ block,
+ /// Nothing inside a dashed frame; hatched where there is room.
+ hollow,
+ /// Diagonal bands of `solid` and ink round an ink plaque that names it.
+ hazard,
+ /// A bright frame, and the veil over everything else.
+ spotlight,
+ /// A thin arrow that is gone a second after it lands.
+ thin_arrow,
+ /// Two small squares where the digits would be.
+ dots,
+ /// The ground itself.
+ ground,
+};
+
+pub const Mark = struct {
+ /// Full strength: a strike's fill, a plaque, a stroke.
+ solid: u24,
+ /// The quiet form: a fill under `text.primary`. `solid` again where a role has none.
+ ember: u24,
+ /// Letters on `solid`.
+ on_solid: u24,
+ form: Form,
+};
+
+pub fn mark(role: Role) Mark {
+ const t = color.text;
+ return switch (role) {
+ .current => .{ .solid = 0xe8c46a, .ember = 0x4a3d1c, .on_solid = t.ink, .form = .plaque },
+ .write => .{ .solid = 0xff6a4a, .ember = 0x5a2218, .on_solid = t.ink, .form = .fill },
+ .read => .{ .solid = 0x6fd6e6, .ember = 0x1c4652, .on_solid = t.ink, .form = .frame },
+ .pointer => .{ .solid = 0xd59cf5, .ember = 0x45305a, .on_solid = t.ink, .form = .arrow },
+ .allocated => .{ .solid = 0x7fdc9a, .ember = 0x1f4a33, .on_solid = t.ink, .form = .block },
+ // The dashed frame, and the hatch.
+ .freed => .{ .solid = t.dim, .ember = color.rule, .on_solid = t.ink, .form = .hollow },
+ // The band, and the plaque inside it, lettered in `text.bright`.
+ .fault => .{ .solid = 0xff6a4a, .ember = t.ink, .on_solid = t.ink, .form = .hazard },
+ .attention => .{ .solid = t.bright, .ember = t.bright, .on_solid = t.ink, .form = .spotlight },
+ .flow => .{ .solid = t.primary, .ember = t.primary, .on_solid = t.ink, .form = .thin_arrow },
+ .unknown => .{ .solid = t.faint, .ember = t.faint, .on_solid = t.ink, .form = .dots },
+ .kernel => .{ .solid = color.kernel, .ember = color.kernel, .on_solid = color.on_kernel.ink, .form = .ground },
+ };
+}
+
+pub const roles = [_]Role{ .current, .write, .read, .pointer, .allocated, .freed, .fault, .attention, .flow, .unknown, .kernel };
+
+/// WCAG relative luminance of 0xRRGGBB.
+pub fn luminance(rgb: u24) f64 {
+ var sum: f64 = 0;
+ const weight = [3]f64{ 0.2126, 0.7152, 0.0722 };
+ for (weight, 0..) |w, i| {
+ const shift: u5 = @intCast(16 - 8 * i);
+ const c = @as(f64, @floatFromInt((rgb >> shift) & 0xff)) / 255.0;
+ sum += w * (if (c <= 0.04045) c / 12.92 else std.math.pow(f64, (c + 0.055) / 1.055, 2.4));
+ }
+ return sum;
+}
+
+/// WCAG contrast of two colours, 1 to 21.
+pub fn contrast(a: u24, b: u24) f64 {
+ const x = luminance(a);
+ const y = luminance(b);
+ return (@max(x, y) + 0.05) / (@min(x, y) + 0.05);
+}
+
+// ------------------------------------------------------------------ type
+
+/// The Go fonts (Bigelow & Holmes; BSD-3-Clause, the Go licence), from
+/// golang.org/x/image/font/gofont/ttfs or the `ttf-go` package. Mono is for
+/// what the machine holds, sans for what is said about it.
+pub const Face = struct { family: []const u8, file: []const u8 };
+pub const font = struct {
+ /// Data and code. The renderer's built-in face.
+ pub const mono: Face = .{ .family = "Go Mono", .file = "Go-Mono.ttf" };
+ /// Keywords, a struck value, the letters on a plaque.
+ pub const mono_bold: Face = .{ .family = "Go Mono", .file = "Go-Mono-Bold.ttf" };
+ /// Comments.
+ pub const mono_italic: Face = .{ .family = "Go Mono", .file = "Go-Mono-Italic.ttf" };
+ /// Captions, notes.
+ pub const sans: Face = .{ .family = "Go", .file = "Go-Regular.ttf" };
+ /// Tags, labels, the running head.
+ pub const sans_medium: Face = .{ .family = "Go Medium", .file = "Go-Medium.ttf" };
+ /// Titles.
+ pub const sans_bold: Face = .{ .family = "Go", .file = "Go-Bold.ttf" };
+};
+
+pub const size = struct {
+ /// Mono sizes are multiples of 5: Go Mono advances 0.6 em, so a character
+ /// is a whole number of units (15, 18, 21, 27, 36), a hex pair is 36, and
+ /// the layout is the same arithmetic at 1080p and at 4K.
+ pub const mono = struct {
+ /// The debugger's context, where a lot is on screen at once:
+ /// chains of pointers, the disassembly, the stack.
+ pub const context = 20;
+ /// Address gutters, types, small tags. Furniture.
+ pub const small = 25;
+ /// Bytes, words, registers, code. The smallest size for anything the
+ /// narration depends on; nothing mono that must be read is smaller.
+ pub const data = 30;
+ /// Values in nodes and chunks.
+ pub const value = 35;
+ /// A value in flight.
+ pub const flight = 45;
+ /// Values in hero cells, a system call's name.
+ pub const hero = 60;
+ };
+ pub const sans = struct {
+ /// Notes in a tag, glosses, the level rail. Furniture: lost at 480p, and that is allowed.
+ pub const micro = 18;
+ /// A panel's title.
+ pub const tag = 20;
+ /// A sentence beside a row: a gloss the narration also says aloud.
+ pub const note = 24;
+ /// Tags, names beside rows, the running head, legend names. The
+ /// smallest sans for anything that identifies something.
+ pub const label = 28;
+ pub const kicker = 30;
+ /// The narrator's sentence; code inside it is mono at 35.
+ pub const caption = 40;
+ pub const caption_leading = 54;
+ pub const subtitle = 44;
+ pub const title = 116;
+ pub const title_leading = 128;
+ };
+ /// Nothing that must be read is smaller, in either face.
+ pub const min_read = 20;
+ /// Nothing at all is smaller.
+ pub const min_any = 18;
+};
+
+/// Width of one Go Mono character at a mono size.
+pub fn monoAdvance(mono_size: u16) u16 {
+ return mono_size * 3 / 5;
+}
+
+/// Hex is set in groups of four digits, half a character apart, lower case,
+/// no `0x`. A register is 16 digits, an address 12 (or its last 8 in a narrow
+/// panel whose tag gives the rest); leading zeros are `text.faint`, and in an
+/// address gutter only the last group is `text.primary`.
+pub fn hexWidth(digits: u16, mono_size: u16) u16 {
+ const adv = monoAdvance(mono_size);
+ return digits * adv + (digits / 4 - 1) * ((adv + 1) / 2);
+}
+
+/// Baseline that centres capitals and digits of `text_size` in a box at `y`, `h` tall.
+pub fn baseline(y: f32, h: f32, text_size: f32) f32 {
+ return y + h / 2 + 0.36 * text_size;
+}
+
+// --------------------------------------------------------------- strokes
+
+pub const stroke = struct {
+ /// Rules, hollow cells, the gap between cells. The thinnest line there is.
+ pub const rule = 2;
+ /// Frames (read, allocated, freed, attention), flows, brackets.
+ /// The thinnest line that carries meaning.
+ pub const line = 3;
+ /// Pointer arrows and pointer frames, tree and graph edges.
+ pub const arrow = 4;
+ /// The bar under a cooled change, a crossing into the kernel.
+ pub const heavy = 6;
+ /// A pointer's head: a filled triangle, length and width.
+ pub const head = [2]f32{ 18, 16 };
+ pub const flow_head = [2]f32{ 16, 14 };
+ pub const crossing_head = [2]f32{ 24, 24 };
+ /// Arrows turn square corners with this fillet.
+ pub const elbow_radius = 12;
+ /// Arrows sharing a lane sit this far apart, the longest outermost.
+ pub const lane_pitch = 22;
+ /// Freed outlines and links on their way out: on, off.
+ pub const dash = [2]f32{ 12, 8 };
+ /// The hatch in a freed block: band width and pitch, at 45 degrees.
+ pub const hatch = [2]f32{ 5, 20 };
+ /// A fault's band: each colour's width, at 45 degrees.
+ pub const hazard = 12;
+ /// Elision marks and the dots of an unknown byte: squares this big.
+ pub const dot = 6;
+};
+
+// ------------------------------------------------------------ components
+
+pub const metric = struct {
+ /// A panel is an acme window: a tag with a square box, a rule, a body.
+ pub const panel = struct {
+ pub const tag_h = 48;
+ /// The box: filled `current` in the panel the narration is in, hollow elsewhere.
+ pub const box = 20;
+ pub const box_inset = 14;
+ pub const title_x = 48;
+ pub const title_baseline = 34;
+ pub const pad_x = 20;
+ pub const pad_y = 16;
+ };
+
+ /// One byte: two hex digits in a 46 square on a 48 pitch.
+ pub const byte = struct {
+ pub const pitch = 48;
+ pub const side = 46;
+ /// A character over its byte, for strings: this tall.
+ pub const text_h = 84;
+ };
+ /// Memory rows, bytes or words: 60 apart, which leaves room for a pointer's frame.
+ pub const row_pitch = 60;
+ /// A word is drawn on the footprint of its bytes (8 of them: 382 wide), so
+ /// bytes and their number can change into each other in place.
+ pub const pointer_frame_outset = 6;
+ /// The bar along the bottom of a cooled change.
+ pub const ember_bar = 6;
+ /// Bytes not shown: three dots and a note, this tall.
+ pub const elision_h = 24;
+ /// Left of an address gutter: register and variable marks that point at the row.
+ pub const mark_lane = 88;
+ /// Between gutter and bytes: where pointer arrows run.
+ pub const arrow_lane = 52;
+
+ /// Registers, and any table of names and values.
+ pub const table = struct {
+ pub const row_h = 48;
+ pub const name_x = 18;
+ /// The value cell overhangs its digits by this on each side.
+ pub const value_pad = 10;
+ pub const flag = [2]f32{ 60, 36 };
+ pub const flag_gap = 12;
+ };
+ /// Shown unless a scene says otherwise, in this order: where it is, the
+ /// result, the arguments, the frame. Any other register appears when a
+ /// step touches it and leaves once its ember has gone.
+ pub const default_registers = [_][]const u8{ "rip", "rax", "rdi", "rsi", "rdx", "rcx", "rsp", "rbp" };
+ pub const default_flags = [_][]const u8{ "CF", "ZF", "SF", "OF" };
+ /// The registers' rows, in pwndbg's order: sixteen, rip, the flags.
+ pub const all_registers = [_][]const u8{ "rax", "rbx", "rcx", "rdx", "rsi", "rdi", "rbp", "rsp", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15", "rip", "flags" };
+
+ /// The context: every panel of it is rows of 24 under a tag of 24.
+ pub const context = struct {
+ pub const row = 24;
+ pub const tag = 24;
+ /// Above and below the rows; at a panel's sides.
+ pub const pad = 6;
+ pub const side = 12;
+ /// A register's name: five characters. Its value starts here.
+ pub const name_w = 60;
+ pub const chain_x = 72;
+ /// Both arrows of a chain: a 2-unit shaft, a head 8 by 10.
+ pub const arrow_w = 30;
+ pub const arrow_head = [2]f32{ 8, 10 };
+ /// Between groups of four hex digits: half an advance.
+ pub const group_gap = 6;
+ /// Changed a moment ago: a tick at the value's left.
+ pub const tick = 4;
+ pub const read_frame = 2;
+ pub const pulse_outset = 3;
+ pub const string_min = 6;
+ pub const source_chars = 67;
+ };
+
+ pub const code = struct {
+ pub const line_h = 48;
+ /// Line numbers: three digits and this, then the code.
+ pub const gutter_pad = 16;
+ pub const text_gap = 20;
+ /// Characters a panel of n columns holds at `size.mono.data`: write the
+ /// C for a video to fit the panel it will be shown in.
+ pub const chars_in_5_columns = 34;
+ pub const chars_in_6_columns = 42;
+ pub const chars_in_7_columns = 51;
+ /// The trail bar at the left edge, and the instruction marker in an unfolded line.
+ pub const trail_bar = 6;
+ pub const unfold_indent = 36;
+ pub const instruction_bar = 8;
+ };
+
+ /// Call stack cards, newest on top.
+ pub const card = struct {
+ pub const h = 56;
+ pub const gap = 12;
+ pub const spine = 12;
+ };
+ /// A linked-list node: value, then a pointer compartment.
+ pub const node = struct {
+ pub const w = 180;
+ pub const h = 72;
+ pub const pointer_w = 72;
+ /// The square in the pointer compartment that its arrow leaves from.
+ pub const origin = 14;
+ };
+ /// Tree and graph nodes: circles; the tree's levels this far apart.
+ pub const tree = struct {
+ pub const radius = 24;
+ pub const radius_solo = 36;
+ pub const level = 54;
+ pub const badge = 28;
+ };
+ /// Array cells: in a panel among others, and as the subject.
+ pub const cell = [2]f32{ 96, 84 };
+ pub const hero_cell = [2]f32{ 168, 132 };
+ /// A value in flight: its card.
+ pub const flight_card = [2]f32{ 100, 60 };
+
+ /// The heap, to scale.
+ pub const heap = struct {
+ pub const units_per_byte = 4;
+ pub const strip_h = 88;
+ pub const strip_h_stacked = 56;
+ };
+ /// The page map: one square a page.
+ pub const page = struct {
+ pub const pitch = 24;
+ pub const side = 22;
+ pub const row_pitch = 42;
+ };
+ /// The system call strip: time spent in the kernel hangs below the line.
+ pub const timeline = struct {
+ pub const baseline = 3;
+ pub const block_h = 44;
+ pub const min_block = 12;
+ pub const min_gap = 16;
+ pub const now = 4;
+ };
+ pub const legend = struct {
+ pub const sample_w = 94;
+ pub const text_x = 110;
+ pub const row_h = 96;
+ };
+ /// A plaque: a name in a box (hollow for a value, filled for a place).
+ pub const plaque = struct {
+ pub const h = 40;
+ pub const pad = 12;
+ };
+
+ /// No panel shows more rows of data than this; past it, elide or zoom.
+ pub const max_rows = 10;
+ /// No scene tracks more objects by pigment.
+ pub const max_pigments = 4;
+};
+
+// ---------------------------------------------------------------- motion
+
+pub const Ease = enum {
+ /// Time itself: the progress line, a counter, the playhead; and opacity.
+ linear,
+ /// Things that answer the program: the mark, cards, tags, arrows
+ /// growing, rows making room. Quickest a quarter of the way in.
+ standard,
+ /// A fade that arrives rising.
+ enter,
+ /// A fade that leaves.
+ exit,
+ /// Things with weight: a value in flight, the camera, a layout, a
+ /// colour cooling. Quickest at the middle.
+ glide,
+};
+
+/// Control points x1, y1, x2, y2 of the curve from (0, 0) to (1, 1).
+pub fn bezier(e: Ease) [4]f32 {
+ return switch (e) {
+ .linear => .{ 0, 0, 1, 1 },
+ .standard => .{ 0.3, 0, 0.2, 1 },
+ .enter => .{ 0, 0, 0.2, 1 },
+ .exit => .{ 0.4, 0, 1, 1 },
+ .glide => .{ 0.45, 0, 0.55, 1 },
+ };
+}
+
+/// Progress at time `t`, both 0 to 1. Fits vecanim's `.ease` (`fn (f32) f32`)
+/// once the curve is bound: `fn standard(t: f32) f32 { return theme.ease(.standard, t); }`.
+pub fn ease(e: Ease, t: f32) f32 {
+ if (t <= 0) return 0;
+ if (t >= 1) return 1;
+ const p = bezier(e);
+ var lo: f32 = 0;
+ var hi: f32 = 1;
+ var s: f32 = t;
+ for (0..24) |_| {
+ s = (lo + hi) / 2;
+ if (cubic(p[0], p[2], s) < t) lo = s else hi = s;
+ }
+ return cubic(p[1], p[3], s);
+}
+
+fn cubic(a: f32, b: f32, s: f32) f32 {
+ const r = 1 - s;
+ return 3 * r * r * s * a + 3 * r * s * s * b + s * s * s;
+}
+
+/// The one overshoot there is: a struck cell's edges go out this many
+/// units on every side and come back, `t` from 0 to 1 over
+/// `time.strike.pulse`. An outset, not a scale: the same on a byte and on a
+/// register, and the digits do not move.
+pub fn pulse(t: f32) f32 {
+ return 4 * @sin(std.math.pi * std.math.clamp(t, 0, 1));
+}
+
+/// Seconds. Export at 60 frames a second; every figure is a whole number of frames.
+pub const time = struct {
+ pub const fps = 60;
+
+ /// A colour changing where nothing moves.
+ pub const snap = 0.10;
+ /// Leaving; a small change of state.
+ pub const quick = 0.20;
+ /// The current mark moving to the next row; `step_per_row` more for
+ /// each further row, `step_max` at most. Further than
+ /// `current_jump_rows`, or into or out of a call, it jumps.
+ pub const step = 0.20;
+ pub const step_per_row = 2.0 / 60.0;
+ pub const step_max = 0.40;
+ /// Something moving within a panel, up to 400 units.
+ pub const move = 0.40;
+ /// Something moving between panels, or further.
+ pub const travel = 0.60;
+ /// Panels changing layout.
+ pub const layout = 0.80;
+ /// A camera move up to twice or down to half the scale; a larger one.
+ pub const camera = 1.20;
+ pub const camera_far = 1.60;
+
+ /// A step is a sentence. Fire: the mark's plaque pulses on the line
+ /// about to run, and nothing else moves.
+ pub const fire = 0.20;
+ /// Then its effects, a level at a time, this far apart: the registers,
+ /// memory, the idea drawn from them.
+ pub const cascade = 0.30;
+ /// Then they are read: this long after the last strike, `read_more`
+ /// for each further value, `read_most` in all.
+ pub const read_value = 0.60;
+ pub const read_more = 0.20;
+ pub const read_most = 1.40;
+ /// Then the mark advances (`step`), and the next line is read.
+ pub const rest = 0.40;
+
+ /// A write: armed (a frame round the cell, the old value still in
+ /// it), struck (the fill fades in, with a pulse of its edges), held
+ /// solid until the mark leaves the line, cooled to its ember and bar,
+ /// kept while the thing has changed within `ember_steps` steps (or
+ /// `ember_seconds` where time runs free), then gone.
+ pub const strike = struct {
+ pub const arm = 0.20;
+ pub const in = 0.10;
+ pub const pulse = 0.20;
+ pub const hold = 0.50;
+ pub const cool = 0.40;
+ pub const ember_steps = 3;
+ pub const ember_seconds = 4.0;
+ pub const out = 0.60;
+ };
+ /// A read: framed for the step, never pulsed.
+ pub const read = struct {
+ pub const in = 0.10;
+ pub const min_hold = 0.50;
+ pub const out = 0.30;
+ };
+ /// The current marker slides to a neighbour and jumps (out, then in) further than this many rows.
+ pub const current_jump_rows = 8;
+ pub const current_jump = 0.10;
+ /// A pointer changing target: the head travels; the old path stays dashed, then goes.
+ pub const redirect = struct {
+ pub const head = 0.40;
+ pub const ghost_hold = 0.80;
+ pub const ghost_out = 0.30;
+ /// What the arrow lands on is framed bright, this long.
+ pub const landing = 0.20;
+ };
+ /// A value moving: lift, fly an arc, land with a strike. The place it left keeps its digits, faint.
+ pub const flight = struct {
+ pub const lift = 0.10;
+ pub const lift_scale = 1.12;
+ /// How long it flies, by how far: to 200 units, to 400, beyond.
+ pub const near = 0.50;
+ pub const mid = 0.60;
+ pub const far = 0.80;
+ /// Of two that fly together, the second sets off this much later.
+ pub const second = 0.10;
+ /// The arc's height as a share of the distance, and its limits in units.
+ pub const arc = 0.25;
+ pub const arc_min = 34;
+ pub const arc_max = 120;
+ /// A flow's arrow outlives the landing by this.
+ pub const linger = 1.0;
+ };
+ /// The veil that dims everything but the subject.
+ pub const veil = 0.30;
+ /// A telescope extends: the links after one that changed are followed
+ /// again one at a time, this far apart.
+ pub const unroll = 4.0 / 60.0;
+ /// A tie between two panes: this long to draw (after what it leaves
+ /// from has struck), and to go, as the marks advance.
+ pub const link = struct {
+ pub const in = 0.40;
+ pub const out = 0.30;
+ };
+ /// A source line opening into its instructions, and closing.
+ pub const unfold = 0.40;
+ /// A wedge drawing from a thing to its enlargement.
+ pub const wedge = 0.30;
+ /// A caption leaves, then nothing, then the next arrives rising this
+ /// many units; never typed out, never crossfaded. The stage stays
+ /// still `caption_lead` after it (`caption_lead_first` after a scene's
+ /// first): the eye reads, then is shown.
+ pub const caption_out = 0.20;
+ pub const caption_gap = 0.10;
+ pub const caption_in = 0.30;
+ pub const caption_rise = 8;
+ pub const caption_lead = 1.00;
+ pub const caption_lead_first = 2.00;
+
+ /// Things arriving together start this far apart, in reading order, and
+ /// the last starts no later than `stagger_max` after the first.
+ pub const stagger = 2.0 / 60.0;
+ pub const stagger_max = 0.30;
+ /// The same as a lag ratio for vecanim's `.lag`, for `n` things over `seconds`.
+ pub fn lag(n: u32, seconds: f32) f32 {
+ if (n < 2) return 0;
+ const total: f32 = @min(stagger * @as(f32, @floatFromInt(n - 1)), stagger_max);
+ return total / (seconds * @as(f32, @floatFromInt(n - 1)));
+ }
+
+ /// Pacing. A beat is the unit of stillness.
+ pub const beat = 0.50;
+ /// What a step that writes one value comes to. Not a pace: a walked
+ /// step is as long as its content (`cursor.reading`).
+ pub const walk = 1.50;
+ /// Once the pattern is known: the mark and structures eased, values
+ /// as embers. `run_max_steps` at most; beyond that, sprint.
+ pub const run = 0.30;
+ pub const run_max_steps = 24;
+ /// What moves at a run (the mark, a card, an arrow) takes this long.
+ pub const run_ease = 8.0 / 60.0;
+ /// A hurried step with this long or more is still a whole sentence,
+ /// said faster; with less, it is a run.
+ pub const walk_least = 0.70;
+ /// A return's follow-through: its card is struck with the result,
+ /// leaves, and the cards under it move up, before the hold begins.
+ pub const returning = 0.90;
+ /// At this a step or faster, single changes are not drawn: structures
+ /// grow, embers, and a counter.
+ pub const sprint = 4.0 / 60.0;
+ /// A phrase (a trip round a loop, a call and its return) ends with a rest.
+ pub const phrase_rest = 0.50;
+ pub const phrase_rest_running = 0.20;
+ /// A change of pace is never a switch: each step of it is this much
+ /// of the one before.
+ pub const ramp = 0.6;
+ /// Stillness at a scene's opening, for the picture to be read:
+ /// `establish` and `establish_per_panel` for each panel.
+ pub const establish = 1.00;
+ pub const establish_per_panel = 0.50;
+ /// Stillness after the stage is rearranged, and on the last picture.
+ pub const settle = 0.80;
+ pub const before_cut = 2.00;
+ /// A camera move: its target framed (`camera_before`), the rest of
+ /// the stage cleared (`camera_clear`), the move, then still
+ /// (`camera_after`). Never longer than `camera_dwell_max` nearer
+ /// without a change.
+ pub const camera_before = 0.40;
+ pub const camera_clear = 0.30;
+ pub const camera_after = 0.60;
+ pub const camera_dwell_max = 2.00;
+
+ /// How long a caption of `chars` characters stays up, at least.
+ pub fn caption(chars: u32) f32 {
+ return 1.5 + 0.06 * @as(f32, @floatFromInt(chars));
+ }
+};
+
+/// The camera only ever shows the frame, a panel, or a few cells; it never turns.
+pub const camera = struct {
+ pub const scales = [4]f32{ 1, 1.5, 2, 4 };
+ /// Units a second, at most, at scale 1.
+ pub const max_speed = 1200;
+};
+
+/// At once: one thing moves because the program did something, and at most
+/// two more move because of it. The camera and the layout move alone.
+pub const max_moving = 3;
+
+// ----------------------------------------------------------------- tests
+
+const expect = std.testing.expect;
+
+test "text reads on its grounds" {
+ const t = color.text;
+ try expect(contrast(t.primary, color.page) >= 11);
+ try expect(contrast(t.primary, color.raised) >= 11);
+ try expect(contrast(t.dim, color.page) >= 7);
+ try expect(contrast(t.dim, color.raised) >= 6);
+ try expect(contrast(t.faint, color.page) >= 4.5);
+ try expect(contrast(t.faint, color.raised) >= 3.5);
+ try expect(contrast(color.on_kernel.ink, color.kernel) >= 11);
+ try expect(contrast(color.on_kernel.dim, color.kernel) >= 5.5);
+ for ([_]u24{ color.code.plain, color.code.keyword, color.code.literal, color.code.comment }) |c|
+ try expect(contrast(c, color.page) >= 7);
+ for (color.pigment) |p| try expect(contrast(t.primary, p) >= 4.5);
+}
+
+test "every mark stands off the page, and letters read on it" {
+ for (roles) |r| {
+ const m = mark(r);
+ try expect(contrast(m.solid, color.page) >= 4.5);
+ try expect(contrast(m.on_solid, m.solid) >= 4.5);
+ // A role with a quiet form: text reads on it, and it is not the page.
+ if (m.ember != m.solid and r != .freed and r != .fault) {
+ try expect(contrast(color.text.primary, m.ember) >= 7);
+ try expect(contrast(m.ember, color.page) >= 1.4);
+ }
+ }
+ // The strokes that carry meaning on their own.
+ for ([_]Role{ .current, .write, .read, .pointer, .allocated }) |r|
+ try expect(contrast(mark(r).solid, color.page) >= 6.5);
+ try expect(contrast(color.text.ink, mark(.write).solid) >= 6.5);
+}
+
+test "no two roles are drawn the same way" {
+ for (roles, 0..) |a, i| for (roles[i + 1 ..]) |b| try expect(mark(a).form != mark(b).form);
+}
+
+test "mono advances are whole units" {
+ const m = size.mono;
+ for ([_]u16{ m.context, m.small, m.data, m.value, m.flight, m.hero }) |s| try expect(s % 5 == 0);
+ try expect(monoAdvance(m.context) == 12 and m.context >= size.min_read);
+ try expect(monoAdvance(m.data) == 18);
+ try expect(hexWidth(16, m.data) == 315);
+ try expect(hexWidth(12, m.small) == 196);
+ // A byte's two digits fit its cell; a register's sixteen fit a word's footprint.
+ try expect(2 * monoAdvance(m.data) <= metric.byte.side - 8);
+ try expect(hexWidth(16, m.data) <= 8 * metric.byte.pitch - 2 - 24);
+ try expect(m.data >= size.min_read and size.sans.label >= size.min_read and size.sans.micro >= size.min_any);
+}
+
+test "layouts fill the stage" {
+ try expect(colX(11) + canvas.column == canvas.width - canvas.margin_x);
+ try expect(span(12) == canvas.stage.w);
+ try expect(layout.program.w == 880 and layout.state.x == 976);
+ // The state column: 468, 228 and 108, twelve apart.
+ try expect(layout.registers.h == 468 and layout.stack.h == 228 and layout.backtrace.h == 108);
+ try expect(layout.backtrace.y + layout.backtrace.h <= canvas.stage.y + canvas.stage.h);
+ for ([_]layout.Split{ layout.split.none, layout.split.beside, layout.split.subject }) |split| {
+ try expect(split.disasm.y + split.disasm.h <= canvas.stage.y + canvas.stage.h);
+ try expect(split.source.y >= split.lens.y + split.lens.h);
+ }
+ try expect(layout.split.beside.source.h == 228 and layout.split.beside.disasm.h == 276);
+}
+
+test "easing runs from 0 to 1 without turning back" {
+ for ([_]Ease{ .linear, .standard, .enter, .exit, .glide }) |e| {
+ try expect(ease(e, 0) == 0 and ease(e, 1) == 1);
+ var last: f32 = 0;
+ for (1..61) |i| {
+ const v = ease(e, @as(f32, @floatFromInt(i)) / 60);
+ try expect(v >= last - 1e-4 and v <= 1 + 1e-4);
+ last = v;
+ }
+ }
+ try expect(@abs(ease(.linear, 0.3) - 0.3) < 1e-3);
+ // `standard` is ahead of time and `glide` is symmetrical.
+ try expect(ease(.standard, 0.5) > 0.6);
+ try expect(@abs(ease(.glide, 0.5) - 0.5) < 1e-3);
+ try expect(pulse(0.5) > 3.9 and pulse(0) == 0);
+}
+
+test "durations are whole frames" {
+ const t = time;
+ for ([_]f32{ t.snap, t.quick, t.step, t.step_per_row, t.step_max, t.move, t.travel, t.layout, t.camera, t.camera_far, t.fire, t.cascade, t.read_value, t.read_more, t.rest, t.strike.arm, t.strike.in, t.strike.pulse, t.strike.hold, t.strike.cool, t.strike.out, t.read.out, t.current_jump, t.flight.lift, t.flight.near, t.flight.second, t.veil, t.unfold, t.wedge, t.caption_in, t.caption_out, t.caption_gap, t.walk, t.run, t.sprint, t.phrase_rest, t.before_cut }) |d| {
+ const frames = d * t.fps;
+ try expect(@abs(frames - @round(frames)) < 1e-3);
+ }
+ try expect(t.lag(1, 0.4) == 0);
+ try expect(@abs(t.lag(8, 0.4) * 0.4 * 7 - 7 * t.stagger) < 1e-4);
+ try expect(@abs(t.lag(40, 0.4) * 0.4 * 39 - t.stagger_max) < 1e-4);
+}