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/theme.zig | 911 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 911 insertions(+) create mode 100644 anim/src/theme.zig (limited to 'anim/src/theme.zig') 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); +} -- cgit v1.3