//! 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); }