//! 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; }; /// The map (design/README.md, "The map and the minimap"): the working /// frame unfolded on a stage of 3840 by 2160 at the context's type size, /// four columns of 880; the working frame's windows outlined on it (2 in /// `dim`, 4 out). The minimap: the map at a twentieth in the caption /// band's right end, under the clock's, whose count moves left of it. pub const map = struct { pub const width = 3840; pub const height = 2160; pub const stage: Rect = .{ .x = 112, .y = 96, .w = 3616, .h = 1688 }; pub const columns = [4]f32{ 112, 1024, 1936, 2848 }; pub const column = 880; pub const outline = 2; pub const outline_out = 4; /// The stack's column: from this many words above rsp (the 128 bytes the recording keeps under it). pub const stack_above = 16; pub const disasm_rows = 69; pub const memory_rows = 32; }; pub const minimap = struct { pub const box: Rect = .{ .x = 1664, .y = 912, .w = 192, .h = 108 }; pub const scale = 1.0 / 20.0; /// The clock's count, ranged right here. pub const count_end = 1648; }; /// 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 }; } /// The stage (design/README.md, "5. The frame"): the lens band across the /// top, and under it two columns. The program column (left): the source /// over the disassembly, what was written over what runs. The state column /// (right): the registers over the stack, what they act on. The split is /// the one thing about the layout a scene chooses. pub const layout = struct { /// Two columns of 880, at x 64 and 976; the gutter between them belongs to the ties. pub const program = cols(0, 6, 0, canvas.stage.h); pub const state = cols(6, 6, 0, canvas.stage.h); /// Where every panel is in one split. The band is the lens, two /// panels: `band`, its drawing, over the program column, and `view`, /// the pane the drawing is a view of (a dump, the backtrace), over the /// state column. They and `backtrace` have no height where the split /// has none. pub const Split = struct { band: Rect, view: Rect, source: Rect, disasm: Rect, registers: Rect, stack: Rect, backtrace: Rect, /// `bytes` rows of the lens's dump. dump_rows: u32, }; pub const split = struct { /// The machine alone: fourteen lines over seventeen instructions; /// the registers, eight words and four frames of backtrace. pub const none: Split = blk: { const registers = rows(state, 0, 17); const stack = below(registers, 8); break :blk .{ .band = .{ .x = program.x, .y = canvas.stage.y, .w = program.w, .h = 0 }, .view = .{ .x = state.x, .y = canvas.stage.y, .w = state.w, .h = 0 }, .source = rows(program, 0, 14), .disasm = below(rows(program, 0, 14), 17), .registers = registers, .stack = stack, .backtrace = below(stack, 4), .dump_rows = 0 }; }; /// The machine is the subject and the lens beside it: a drawing /// and its view of 152 (a dump of five); eight lines over /// seventeen instructions; the registers over eight words. pub const beside: Split = shared(152, 152, 8, 17, 8, 5); /// The idea is the subject: the drawing 296 high and a size up, /// its view 200 (a dump of seven); ten lines over nine /// instructions; the registers over six words, a small frame whole. pub const subject: Split = shared(296, 200, 10, 9, 6, 7); fn shared(drawing_h: f32, view_h: f32, source_rows: f32, disasm_rows: f32, slots: f32, dump_rows: u32) Split { const band: Rect = .{ .x = program.x, .y = canvas.stage.y, .w = program.w, .h = drawing_h }; const view: Rect = .{ .x = state.x, .y = canvas.stage.y, .w = state.w, .h = view_h }; const source: Rect = .{ .x = program.x, .y = band.y + band.h + canvas.row_gap, .w = program.w, .h = panelH(source_rows) }; const registers: Rect = .{ .x = state.x, .y = view.y + view.h + canvas.row_gap, .w = state.w, .h = panelH(17) }; return .{ .band = band, .view = view, .source = source, .disasm = below(source, disasm_rows), .registers = registers, .stack = below(registers, slots), .backtrace = .{ .x = state.x, .y = canvas.stage.y + canvas.stage.h, .w = state.w, .h = 0 }, .dump_rows = dump_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; } /// How many rows a panel `h` high holds. pub fn rowsIn(h: f32) usize { return @intFromFloat(@max(@floor((h - metric.context.tag - 2 * metric.context.pad) / metric.context.row), 0)); } 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 }; /// A node's pointer half. pub const well: u24 = 0x101a48; /// The current row's band: bright a tenth of the way over the page, /// opaque. Gold is kept for the plaque, the pc's marker, rip's name, /// the thread and the trail (design/README.md, `mark`). pub const wash: u24 = 0x212644; /// A loupe's surface and its tag: lifted off the page, the one /// elevation in the frame; and its shadow, the one shadow there is. pub const lift: u24 = 0x121c52; pub const lift_tag: u24 = 0x22317a; pub const shade: u24 = 0x02061a; /// A strike's paper: vermilion 70% over the page, its digits bold and /// bright. The arm, the turned corner and a projection stay `mark(.write).solid`. pub const struck: u24 = 0xb54f42; /// Drawn over everything that is not the subject, to dim it: for a /// beat, and (deeper) under the camera. pub const veil: u24 = page; pub const veil_alpha: f32 = 0.50; pub const veil_alpha_camera: 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, /// This register now points at that: a line 3 wide in the ink of the /// region pointed into, ending in the target's pin. link, /// 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 a white wash across the row. plaque, /// A softened fill with bright bold letters, cooling to nothing and a turned corner. fill, /// A frame, with its ember inside. frame, /// A line along the ties' channels, corners filleted, head filled, and a pin at its end. line, /// 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 = color.wash, .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 }, // Its colour is the region's it points into (`color.region`); this is heap's. .link => .{ .solid = color.region.heap, .ember = color.region.heap, .on_solid = t.ink, .form = .line }, .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, .link, .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 /// Mono is for what the machine holds: JetBrains Mono NL (OFL; NL, because /// the plain family's ligatures turn `->` into a sign that is not in the /// source). Sans is for what is said about it: the Go fonts (Bigelow & /// Holmes; BSD-3-Clause). `ui.Ui.text` sets a mono face by its size. pub const Face = struct { family: []const u8, file: []const u8 }; pub const font = struct { /// Mono at 30 and over. pub const mono: Face = .{ .family = "JetBrains Mono NL", .file = "JetBrainsMonoNL-Regular.ttf" }; /// All mono under 30: thin strokes on a dark ground die first in a stream. pub const mono_medium: Face = .{ .family = "JetBrains Mono NL Medium", .file = "JetBrainsMonoNL-Medium.ttf" }; /// Keywords, mnemonics, a struck value, plaques, pins. pub const mono_bold: Face = .{ .family = "JetBrains Mono NL", .file = "JetBrainsMonoNL-Bold.ttf" }; /// Comments. pub const mono_italic: Face = .{ .family = "JetBrains Mono NL", .file = "JetBrainsMonoNL-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: the mono face advances 0.6 em, so a /// character is a whole number of units (12, 15, 18, 21, 27, 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; /// Code inside a caption. pub const value = 35; /// A value in flight; a subject lens's values. 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 mono character at a mono size: JetBrains Mono advances 0.6 /// em, a whole number of units at every size here (20: 12). Hex is /// unbroken, lower case, no `0x` on an address: a digit is an advance. pub fn monoAdvance(mono_size: u16) u16 { return mono_size * 3 / 5; } /// 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; /// The ties: the thread and a link 3, a projection 2. pub const tie = struct { pub const thread = 3; pub const link = 3; pub const projection = 2; }; }; // ------------------------------------------------------------ components pub const metric = struct { /// A panel of a card (the title, the legend): the first pass's sizes. pub const panel = struct { pub const pad_x = 20; }; /// The context: every panel of it is rows of 24 under a tag of 24 /// (`tag`, design/README.md), 4 of padding above and below the rows, /// 12 at the sides. pub const context = struct { pub const row = 24; pub const tag = 24; pub const pad = 4; pub const side = 12; /// `reg`: a register's name 12 in, its chain from 72. pub const chain_x = 72; /// `arrow`: 30 wide, a 2-unit shaft, a head 8 by 10. pub const arrow_w = 30; pub const arrow_head = [2]f32{ 8, 10 }; /// `address` `lead`: the digits every row of a column shares, this /// far toward the page; `byte` `pad`: a word's bytes above its /// highest non-zero one, this far. pub const lead_alpha = 0.6; pub const pad_alpha = 0.45; /// `held`: a turned corner, a vermilion right triangle this long on /// its sides at the value's top left (4 left of its digits, 2 down). pub const corner = 9; /// `read`: a 2-unit frame, 6 out at the sides. pub const read_frame = 2; /// `struck`: solid 5 wider each side; its edges pulse out 3. pub const strike_out = 5; pub const pulse_outset = 3; /// A string is never cut shorter than this. pub const string_min = 6; /// `line`: the number ranged right in three characters, the text from 64, 67 characters. pub const line_number_end = 46; pub const line_text = 64; pub const source_chars = 67; }; /// `insn`: columns, from the panel's left edge. pub const insn = struct { pub const mark = 2; pub const jump_lane = 31; pub const address = 40; pub const line = 134; pub const mnemonic = 180; pub const operands = 264; pub const annotation = 564; }; /// `bytes`: a hexdump row, from its panel's left edge (the band's right /// half): its `arc` lanes, the quiet bracket at 24, the address at 34, /// the bytes 12 after it and at 132 at least. pub const bytes = struct { pub const bracket = 24; pub const address = 34; pub const first = 132; /// Two digits in 24 units on a pitch of 30, 12 more after the eighth. pub const pitch = 30; pub const middle = 12; pub const reading = 640; }; /// `slot`: two `arc` lanes, a lane for `row` pins from 16 to 112, the offset from rsp /// ranged right to 172, the address from 184 and its chain after it, /// room to 136 from the right edge (which belongs to the `call` spans, /// 14 in), a role ranged right where the room ends. pub const slot = struct { pub const lane = 16; pub const lane_end = 112; pub const offset = 172; pub const address = 184; pub const room = 136; pub const span = 14; }; /// `reg` rip: the flags at the right end, eight names on a pitch of 42, /// a set one on a chip 32 by 20. pub const flags = struct { pub const pitch = 42; pub const chip = [2]f32{ 32, 20 }; }; /// `pin`. `row`: the names, 5, a head 9 by 12. `under`: a stub 3 wide, /// the mono size and 10 long, a head 10 by 10, the names 9 either side. pub const pin = struct { pub const row_head = [2]f32{ 9, 12 }; pub const row_gap = 5; pub const stub = 3; pub const under_head = [2]f32{ 10, 10 }; pub const under_names = 9; }; /// `bracket`: a stroke and a serif at each end. `quiet` 2 and 5; `tie` 3 and 6 (the thread's 7). pub const bracket = struct { pub const quiet = [2]f32{ 2, 5 }; pub const tie = [2]f32{ 3, 6 }; pub const thread = [2]f32{ 3, 7 }; }; /// `plaque`, gold only: the row high, this wide. pub const plaque = struct { pub const rip = 54; pub const line = 50; pub const pc = 24; }; /// `nodes`: boxes 116 by 44, 28 apart beside the context; 124 by 72, /// 22 apart as the subject. The pointer half is 48 wide, its square 10. pub const node = struct { pub const beside = [3]f32{ 116, 44, 28 }; pub const subject = [3]f32{ 124, 72, 22 }; pub const pointer_w = 48; pub const origin = 10; pub const arrow_head = [2]f32{ 12, 10 }; }; /// `calls`, full size: a disc 48 across, levels 46 apart, the root's /// centre 48 under the tag; the result's square of 30 on the shoulder, /// 12 right of the centre and 42 up; the caller's box 64 by 28. pub const calls = struct { pub const radius = 24; pub const level = 46; pub const root = 48; pub const badge = 30; pub const badge_at = [2]f32{ 12, 42 }; pub const caller = [2]f32{ 64, 28 }; }; /// `arc`: a pointer to a row of its own panel, along a lane at the /// panel's left edge (4, 10, 16 in a dump or a loupe; 4, 10 on the /// stack), 2 wide, corners of 4; out of its row at 21, into the /// target's at 22 with a head 7 by 8; going up it leaves its row 9 down /// and arrives 15 down (going down, 15 and 9). Standing, its ink 60% /// toward the page. pub const arc = struct { pub const lanes = [3]f32{ 4, 10, 16 }; pub const stack_lanes = 2; pub const out = 21; pub const in = 22; pub const head = [2]f32{ 7, 8 }; pub const high = 9; pub const low = 15; pub const width = 2; pub const radius = 4; pub const standing = 0.6; }; /// `loupe`: 880 wide, five rows round its target in the working frame; /// it hangs from its pointer, its left edge 92 left of the pointer's /// digits, its tag's top on the foot of the pointer's row; its shadow /// 12 right and 16 down (20 and 26 for one opened from a loupe); its /// stem a bracket 4 high under the pointer's digits. pub const loupe = struct { pub const width = 880; pub const rows = 5; pub const hang = 92; pub const shadow = [2][2]f32{ .{ 12, 16 }, .{ 20, 26 } }; pub const stem = 4; }; /// A lens's lanes: projections 4 under its tag, links 8 above its bottom edge. pub const lens = struct { pub const top_lane = 4; pub const bottom_lane = 8; }; /// The ties' channels: the thread in the left margin, the gutter's two /// lanes (a link comes up the left, a projection down the right). pub const tie = struct { pub const thread_x = 54; pub const link_lane = 950; pub const projection_lane = 962; pub const radius = 8; pub const projection_radius = 6; }; /// `held` on a lens's cell: the turned corner at its top left. pub const corner_cell = 12; /// A lens's cell, as the first pass drew them. pub const pointer_frame_outset = 6; pub const elision_h = 24; pub const cell = [2]f32{ 96, 84 }; pub const hero_cell = [2]f32{ 168, 132 }; pub const flight_card = [2]f32{ 100, 60 }; 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; }; /// The registers' rows, in pwndbg's order: sixteen, then rip (with 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" }; /// 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; /// `held`'s turned corner fades in over the cool's last 6 f. pub const corner = 0.10; 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; }; /// A `continue`'s registers strike in a wave, this far apart in /// pwndbg's order (the fill in over `strike.in`, no arm, no pulse). pub const continue_wave = 2.0 / 60.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. /// `link`: 6 f after the register's strike its old pin fades /// (`pin_out`), and the line draws to the target, head first (`in`, /// `in_far` over 400 units); the pin lands with the head and settles; /// at the advance the line draws back into the pin (`out`). pub const link = struct { pub const after = 6.0 / 60.0; pub const pin_out = 0.20; pub const in = 0.40; pub const in_far = 0.60; pub const settle = 0.20; pub const out = 0.30; }; /// `project`: on a run's mark, a bracket takes its row, then the line /// draws to the part of the drawing the bytes are; that part reacts /// only when it arrives. Out with the advance. pub const project = struct { pub const bracket = 0.10; pub const draw = 0.30; /// Over 600 units: a frame's way back to its call's node. pub const far = 0.50; pub const out = 0.30; }; /// `arc`: a pointer rewritten: from 6 f after the strike the old arc /// fades (`fade`) as the new draws (`draw`), at full ink; it quiets /// with the cool (`quiet`); a lane change glides (`lane`). pub const arc = struct { pub const after = 0.10; pub const draw = 0.20; pub const fade = 0.20; pub const quiet = 0.40; pub const lane = 0.20; }; /// `open`, a loupe: its pointer framed as read (`read`); the stem /// draws and the loupe rises with it (`stem`; it fades in over `rise` /// from 8 units lower, its shadow grows over `shadow`); its target's /// bright frame lands `frame` after. `close`: the stem draws back and /// the loupe sinks, fading as it falls 8 units, over `close`. pub const loupe = struct { pub const read = 0.10; pub const stem = 0.30; pub const rise = 0.20; pub const shadow = 0.30; pub const frame = 0.10; pub const close = 0.20; /// From its first frame to its target's frame landed: read, stem, a frame's wait and the frame. pub const open = 0.60; }; /// `travel`, for a pin: it sets off `after` the strike that moved it; /// in a drawing it takes `node` to the next node or cell, `nodes` to /// one farther; in the stack's lane `row` to the next row and /// `step_per_row` a further row, `row_max` at most. One that comes /// fades in (`in`, rising 8), one that goes fades out (`out`); a name /// joining or leaving a pin cross-fades (`names`). pub const pin = struct { pub const after = 0.30; pub const node = 0.50; pub const nodes = 0.60; pub const row = 0.40; pub const step_per_row = 2.0 / 60.0; pub const row_max = 0.60; pub const in = 0.20; pub const out = 0.20; pub const names = 0.20; }; /// A return in the calls tree: its frame leaves the backtrace as the /// idea strikes, and the result on the node's shoulder this long after. pub const badge_after = 0.20; /// `establish`, for a lens: its elements come in from this far into the opening. pub const establish_rise = 0.50; /// `relayout`: a change of split; the drawing fades out before the /// move (`relayout_fade`) and in after it. pub const relayout = 0.80; pub const relayout_fade = 0.20; /// 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; /// A scene's opening: its first caption this long after the panels /// begin to come in (and after a lens has risen from its bytes). pub const establish = 1.00; /// 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 // (the current row's wash is the quietest: 1.2 on 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) >= @as(f64, if (r == .current) 1.2 else 1.4)); } } // The strokes that carry meaning on their own. for ([_]Role{ .current, .write, .read, .link, .allocated }) |r| try expect(contrast(mark(r).solid, color.page) >= 6.5); try expect(contrast(color.text.ink, mark(.write).solid) >= 6.5); // A strike's bright digits on its softened paper. try expect(contrast(color.text.bright, color.struck) >= 4.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 }) |sz| try expect(sz % 5 == 0); try expect(monoAdvance(m.context) == 12 and m.context >= size.min_read); try expect(monoAdvance(m.data) == 18); // A byte's two digits fit its 24 units, on a pitch of 30. try expect(2 * monoAdvance(m.context) == 24 and metric.bytes.pitch == 30); try expect(m.data >= size.min_read and size.sans.label >= size.min_read and size.sans.micro >= size.min_any); } test "the splits fill the stage, panels 12 apart" { 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); const bottom = canvas.stage.y + canvas.stage.h; const sp = layout.split; // design/README.md, "5. The frame". try expect(sp.none.source.h == 368 and sp.none.disasm.y == 428 and sp.none.disasm.y + sp.none.disasm.h == 868); try expect(sp.none.registers.h == 440 and sp.none.stack.y == 500 and sp.none.backtrace.y == 736 and sp.none.backtrace.y + sp.none.backtrace.h == 864); try expect(sp.beside.band.h == 152 and sp.beside.view.h == 152 and sp.beside.source.y == 212 and sp.beside.disasm.y == 448 and sp.beside.disasm.y + sp.beside.disasm.h == bottom); try expect(sp.beside.registers.y == 212 and sp.beside.stack.y == 664 and sp.beside.stack.y + sp.beside.stack.h == bottom); try expect(sp.subject.band.h == 296 and sp.subject.view.h == 200 and sp.subject.source.y == 356 and sp.subject.disasm.y == 640 and sp.subject.disasm.y + sp.subject.disasm.h == bottom); try expect(sp.subject.registers.y == 260 and sp.subject.stack.y == 712 and sp.subject.stack.y + sp.subject.stack.h == bottom); try expect(layout.rowsIn(sp.beside.disasm.h) == 17 and layout.rowsIn(sp.subject.disasm.h) == 9 and layout.rowsIn(sp.subject.stack.h) == 6 and layout.rowsIn(sp.subject.view.h) == 7); // The band's two panels are the columns' width, the gutter between them the ties'. try expect(sp.subject.band.x == layout.program.x and sp.subject.band.w == 880 and sp.subject.view.x == layout.state.x); } 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.corner, t.strike.out, t.loupe.read, t.loupe.stem, t.loupe.rise, t.loupe.shadow, t.loupe.frame, t.loupe.close, t.loupe.open, t.arc.after, t.arc.draw, t.arc.fade, t.arc.quiet, t.arc.lane, t.read.out, t.current_jump, t.flight.lift, t.flight.near, t.flight.second, t.veil, t.link.after, t.link.pin_out, t.link.in, t.link.in_far, t.link.settle, t.link.out, t.project.bracket, t.project.draw, t.project.out, t.establish_rise, t.relayout, t.relayout_fade, t.continue_wave, t.badge_after, t.pin.after, t.pin.node, t.pin.nodes, t.pin.row, t.pin.step_per_row, t.pin.row_max, t.pin.in, t.pin.out, t.pin.names, 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); }