# canim: the look How a canim frame is laid out, coloured and set. How it moves is in [`motion.md`](motion.md). The numbers are tokens in `anim/src/theme.zig`; the changes this revision asks of them are [listed below](#token-changes). Eleven frames drawn with these rules are in [`mock/`](mock). **Revision 2.** The first pass put one idea on screen in a few sparse panels. The premise now is a debugger's: *show the whole context, always*, as pwndbg does, and put the scene's idea beside it as a lens on the same state. Sections marked **(rev 2)** are new or changed; what was withdrawn is in the table that follows. The idea, in six rules: 1. **Lapis page, vellum ink.** 0x4200.cafe's own palette: a deep blue page, cream text, gold for where execution is, vermilion for what just changed. 2. **Ink says what a thing is; paper says what happened to it.** **(rev 2)** The colour of a value's digits is where it points (stack, heap, code, data), a keyword, a string. A fill, a frame, a tick or a plaque behind or beside it is an event: written, read, current. The two never share a channel. 3. **Every mark has its own form.** Written is filled, read is framed, changed is ticked, freed is hollow and dashed, unknown is two dots. 4. **Solid vellum is the kernel**, at every scale, and nothing else. 5. **Panels are acme windows.** A tag with a square box, a 2-unit rule, a body. Square corners, no shadows, no gradients, no glow. 6. **The whole context, always, and the lens beside it.** **(rev 2)** Every register followed as far as it points, the instructions at the pc, the stack, the backtrace and the source are in the same place in every frame. A list, a tree, an array is a lens on that state: never shown instead of it, and visibly tied to the words it is made of. The machine is set in JetBrains Mono; the narrator in Go. ![the context](mock/09-context.png) ## What changed | | First pass | Revision 2 | | --- | --- | --- | | On screen | one to four panels chosen by the scene | the whole context in every frame, and one lens | | Layouts | `solo`, `duo`, `trio`, `quad`, `trio_hero`, `far`, `crossing` | one frame with three splits; only title cards are anything else | | Running head, level rail | a band at the top | gone: the rows went to the stage; the frame itself is the rail | | Mono | Go Mono, 30 for anything read | JetBrains Mono NL, 20 in the context | | Hard floor | mono 30, sans 28 | mono 20, sans 18; see [what a phone loses](#type) | | Hue on digits | syntax only | region: where an address points | | `pointer` role (orchid) | a frame and an arrow for every pointer | gone: a pointer is inked by its region; orchid is now `data` | | Arrows to targets | always drawn | drawn in a lens, and for the one pointer a step follows | | Changed a moment ago | ember fill and a bar | in the context, a tick at the value's left; ember and bar in a lens's cells | | Registers | eight by default | all sixteen, rip, flags, each with its telescope | | Stack | cards, or a byte grid | a telescope of eight words, and the backtrace under it | | Source | the lines that fit a panel | the whole file, scrolling to keep the line in view | | Levels | different layouts, a camera between them | places in one picture; the camera is for reading | | Camera scales | 1, 2, 4 | 1, 1.5, 2, 4 | ## The frame (rev 2) 1920 by 1080 logical units; a 4K master is two pixels a unit. Master at 2160p60: at this density the extra resolution is not a nicety. | Band | y | What | | --- | --- | --- | | margin | 0 to 48 | page | | stage | 48 to 888 | the context and the lens: 35 rows of 24 | | clock | 898 to 902 | a rule the width of the stage; gold along it as far as the recording has run; `moment 72 of 95` under its right end | | caption | 912 to 1032 | one or two lines of narration | | margin | 1032 to 1080 | page | Side margins are 64. Two columns of 880 with 32 between them; panels in a column are 12 apart. A panel is a tag of 24, 6 of padding, rows of 24, 6 of padding: 36 + 24 a row. **The state column** (right, x 976 to 1856) is the same in every frame of every scene: | Panel | Rows | Height | y | | --- | --- | --- | --- | | registers | 18: sixteen, rip, flags | 468 | 48 to 516 | | stack | 8 words from rsp | 228 | 528 to 756 | | backtrace | 3 frames, then a count | 108 | 768 to 876 | **The program column** (left, x 64 to 944) holds the lens, the source and the disassembly, top to bottom: the idea, its text, its instructions. It has three splits, and the split is the only thing about the layout a scene chooses: | Split | Lens | Source | Disassembly | When | | --- | --- | --- | --- | --- | | no lens | | 21 lines, 540 | 10 rows, 276 | the machine alone | | lens beside | 312 | 12 lines, 324 | 6 rows, 180 | the default: the machine is the subject ([mock 9](mock/09-context.png)) | | lens as subject | 432 | 8 lines, 228 | 5 rows, 156 | the idea is the subject ([mock 11](mock/11-context-lens.png)) | As the subject the lens is also a size up: mono 25 on rows of 30, values at 35. Moving between the last two is a layout change (0.8 s): the source gives up four lines and the disassembly one row. Of the frame's area: | | No lens | Lens beside | Lens as subject | | --- | --- | --- | --- | | state column | 35% | 35% | 35% | | source and disassembly | 35% | 21% | 16% | | **context in all** | **70%** | **57%** | **51%** | | **lens** | | **13%** | **18%** | | caption band | 10% | 10% | 10% | The lens never has more than a fifth of the frame, and that is the cost of the premise. When an idea needs to be large it gets the camera (below), for a few seconds, and the frame comes back. **Place is meaning.** Down the program column abstraction falls: idea, C, instructions. The state column is what they act on. The lens is top left, where the eye starts, and next to the registers that point into it. The kernel is still vellum and still underneath: its rows hang under the `syscall` instruction in the disassembly, and a crossing is a lens. **No data below y = 888.** The player's controls and subtitles cover the caption band. ## Colour | | Hex | On page | On `raised` | Use | | --- | --- | --- | --- | --- | | page | `0a1030` | | | the ground; panel bodies too | | raised | `16245f` | 1.3 | | tags, cells, plaques, node bodies | | rule | `3a4a8a` | 2.2 | 1.7 | rules, hollow cells, wedges; fill of bookkeeping | | text, bright | `fff8e8` | 17.6 | 13.7 | titles, a value in flight, a landing frame | | text, primary | `eee6d2` | 14.9 | 11.6 | numbers that are not addresses, names of code, plain code | | text, dim | `9aa6d9` | 7.8 | 6.1 | register names, notes | | text, faint | `6a7ab8` | 4.5 | 3.5 | arrows in a chain, offsets, line numbers, a decimal beside its hex | | ink | `050a24` | | | letters on a solid accent | ### Regions: the ink of an address (rev 2) As pwndbg colours them, and as its users read them without thinking: | Points into | Ink | On page | Also | | --- | --- | --- | --- | | stack | yellow `f2d675` | 13.0 | | | heap | blue `86b6ff` | 9.0 | | | code | red `ff8f9a` | 8.5 | always followed by its name | | data, writable | purple `d59cf5` | 8.8 | | | writable and executable | its region's ink | | a 2-unit underline | | read-only data | primary `eee6d2` | 14.9 | plain, as pwndbg leaves it | | nothing: not a pointer | primary | | see [what a value shows as](#what-a-value-shows-as-rev-2) | | a string | `b5e8c8` | 13.6 | in quotes | The legend is always on screen, as pwndbg's is: the six words, each in its ink, in the registers' tag. These are tints, lighter and less saturated than the marks, so a frame of them is quiet. Every one reads at 4.6 or better on every ground it can sit on, the embers included. ### Marks: what happened | Role | Solid | Ember | In the context (mono 20) | In a lens's cell | | --- | --- | --- | --- | --- | | current | gold `e8c46a` | `4a3d1c` | solid plaque on the label, ember across the row | the same | | write | vermilion `ff6a4a` | `5a2218` | solid behind the value, digits bold in ink | solid fill, pulse | | changed (held) | vermilion | | a tick, 4 wide, at the value's left, for three steps | ember and a 6-unit bar | | read | `6fd6e6` | `1c4652` | a 2-unit frame, no fill | a 3-unit frame, ember inside | | allocated | `7fdc9a` | `1f4a33` | | ember block in a solid frame | | freed | no colour | | | hollow, dashed, hatched | | fault | vermilion | | hazard bands round an ink plaque naming it | the same | | attention, landing | bright | | a 2-unit bright frame | a 3-unit bright frame; a veil on the rest | | link, flow | the target's region ink; primary | | a 3-unit arrow, for one step | a 3-unit arrow | | unknown | faint | | two 6-unit squares | the same | | kernel | vellum `eee6d2` | | the ground | the ground | **How the two never fight.** - A region is letters; a mark is never letters. During a strike the digits are bold ink on solid vermilion: for 0.6 s "written now" is all that value says. As the fill goes the digits come back in their region's ink. - A held change does not sit under the digits it marks. It is a tick in the gap to their left, the `*` pwndbg puts before a changed register. The underline is left free to mean writable-and-executable. - A read is a frame, outside the digits, and brings no fill. - The current row is the one place region ink sits on a coloured ground: code red on the gold ember, at 4.9. - In a lens's cells (mono 25 and up, a box of their own) the ember stays: there is room for it and the digits on it are measured (4.6 to 8.7). **The `pointer` role is gone.** Being a pointer is not a colour any more: every address is inked by where it points. Its orchid is `data`. Its forms survive as the *link*: an arrow, and a frame round the bytes that make one pointer, in the ink of the region pointed into, drawn in two places only: inside a lens (a list's arrows), and for the single pointer a step follows or rewrites. **Pigments** still say *which object*, across views: ochre `8a5e0c`, teal `17707c`, madder `a03060`, malachite `1c7450`, violet `6a3fb0`, azurite `2f5fc4`; at most four, each with its name. In the context they are a lens's way of naming an object and its rows, and never a ground under region ink. **Code** (pardes's four classes): plain `eee6d2`; keyword `c0dcff`, bold; string and number `b5e8c8` (was `c8f0d8`: too close to plain at 20); comment `9aa6d9`, italic. In the disassembly a mnemonic is a keyword. **Colour vision.** Blue ground against gold and vermilion is the axis every common deficiency keeps. Region ink *is* hue alone, as it is in pwndbg, and heap, data and code have the same luminance; a deuteranope cannot tell heap from data by colour. What is left for them: code always has its name after it, a string its quotes, stack is far lighter than the rest, and an address's own top digits say where it is. That is weaker than everything else here and it is the price of the convention. **After 4:2:0.** Mock 10 through x264: at 1080p (CRF 30) and at 720p (CRF 28) every chain reads and every region keeps its colour. At 480p the digits can no longer be trusted (`0` and `8` fall together); ticks, the strike, the region colours, the gold rows and the caption survive. ## Type **(rev 2)** One mono family for code, registers, hex and memory, so the whole context sits on one grid; Go stays for everything said about it. | Face | File | For | | --- | --- | --- | | JetBrains Mono NL Medium | `JetBrainsMonoNL-Medium.ttf` | everything mono at 20 and 25 | | JetBrains Mono NL Regular | `JetBrainsMonoNL-Regular.ttf` | mono at 30 and larger | | JetBrains Mono NL Bold | `JetBrainsMonoNL-Bold.ttf` | keywords, mnemonics, a struck value, plaque letters | | JetBrains Mono NL Italic | `JetBrainsMonoNL-Italic.ttf` | comments | | Go | `Go-Regular.ttf` | captions, notes | | Go Medium | `Go-Medium.ttf` | tags, labels | | Go Bold | `Go-Bold.ttf` | titles | JetBrains Mono: OFL 1.1, `/usr/share/fonts/TTF/` (`ttf-jetbrains-mono` 2.304). Go: BSD-3-Clause, `/usr/share/fonts/go/`. - **NL, not the plain family.** The plain one has ligatures: `->`, `!=` and `>=` become single signs that are not in the source. NL is the same design without them. (If the renderer can turn `calt` off, either will do.) - **Medium at 20 and 25.** Light letters on a dark ground lose their thin strokes first in a stream; at 720p Medium keeps its weight and Regular does not. - **Why not Go Mono too**: one family means a hex digit, a keyword and a register name are the same width and weight, and the user asked for JetBrains Mono where code is. Why Go stays: captions are the layer a phone still reads, Go was the most legible of eight faces at 480 wide, and the change of voice between machine and narrator is worth a second family. Its advance is 0.6 em, as Go Mono's was, so the rule holds: **mono sizes are multiples of 5** and a character is a whole number of units, at 1080p and at 4K. | Mono | Advance | Rows of | For | | --- | --- | --- | --- | | **20** | 12 | 24 | the context: every panel of it | | 25 | 15 | 30 | a lens that is the subject; a lens's values | | 30 | 18 | 36 or 48 | what the camera at x1.5 makes of the context | | 35 | 21 | | values in a lens that is the subject; code inside a caption | | 45 | 27 | | a value in flight | | 60 | 36 | | a title card's numbers | | Sans | For | | --- | --- | | 18 | notes in a tag, a note at the end of a row | | 20 | a panel's title | | 24 | a note beside a lens | | 40 on 54 | the caption | | 44, 116 on 128 | a title card | **The hard floor is mono 20 and sans 18.** Nothing is smaller, anywhere. **What a phone loses.** Said plainly: at mono 20 the context is a picture for a desk. On a phone held sideways an x-height is 0.8 mm, and at 480p no hex digit can be trusted. A phone viewer keeps the caption (40), the layout, the gold rows, the strike and its link, the region colours as colour, a lens that is the subject, and whatever the camera brings to 30. So one rule protects them: **nothing the narration depends on is only at 20.** The value it names is also in the caption, in mono 35, or the camera goes to it. **Hex.** - Lower case, in groups of four from the right, half a character apart. - An address is as long as it is: `28b4 1090`, `7ffe 970f 17b0`, `100 1926`. No leading zeros, no `0x`: its ink says it is an address. - A number that is not an address has `0x` once it has two digits, so that `10` is never sixteen: see below. - Decimal for what the source calls a number; both where a register may be either. ## The context (rev 2) Five panels, in the state they are in when `ztrace show FILE N` prints them. Mocks [9](mock/09-context.png) and [10](mock/10-context-step.png) are moments 71 and 72 of a recording of `targets/list`. ### Panel A tag one row high on `raised`: a 12-unit box 8 in (gold where the narration is, a faint hollow elsewhere); the title, Go Medium 20; a note, Go 18, ranged right. A 2-unit rule round the body; the body is the page. ### Registers Eighteen rows, in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8 to r15, rip, flags. A name (dim) in a column of five characters; its value at 72 from the panel's edge; then its chain. - rip: gold plaque on the name, gold ember across the row, the address in code's ink and its name after it: `100 1926 reverse+22`. rip is never "written". - flags: the value, then the eight names. A set flag is upper case, bold, bright, on a `raised` chip; a clear one lower case and faint (pwndbg's `[ cf PF af zf sf IF df of ]`, without the brackets). One that changed has the tick. - Rows never reorder and none is hidden. ### The telescope One row a chain, read left to right: *this, which points to that, which holds this.* - **An address**: its digits in its region's ink. - **Points to**: an arrow 30 wide, a 2-unit shaft and a head 8 by 10, faint. pwndbg's `—▸`. - **Holds**: the same arrow pointing back. pwndbg's `◂—`. What follows it is not an address. - **The end**: a number, a string, or nothing after a code address but its name, 10 units on, in primary: `100 18b0 main+80`. Where there is no symbol, the module: `libc+27781`. - **A string**: in quotes, in string ink, with C's escapes. Cut to the room left with `…` and no closing quote; never to fewer than six characters. - **Depth** is the recording's (three by default: four addresses from a register, five in a stack row counting the row's own). A chain that was still a pointer where the recording stopped ends in an arrow and three dots. So does one that runs out of row: the string is cut first, then the chain ends early. Nothing is taken from the middle. - **A chain that changes.** Only the link that changed is struck. If it is the first, the register was written, and the links after it are followed again one at a time, 4 frames apart: the telescope extends. If it is a later one, memory changed under a pointer that did not, and the tick sits before that link alone. - **Its target, when the target is on screen.** No standing lines: thirty chains would be a net. Four things tie them instead: 1. the ink: blue is in the heap, yellow in the stack panel below; 2. the digits: the same address is the row's own in the stack, the node's in the lens; 3. plaques: a register's name sits *at what it points to*, in the stack's lane (`rsp`, `rbp`) and on a lens's nodes and rows (`rdi`, `rax`): "who points here", up to three, then a count; 4. one link, for the step in hand: from the row of the register just struck, through the gutter, to the row or node it now holds, in the region's ink, 3 units wide. It draws after the strike and goes with the advance. ([Mock 10](mock/10-context-step.png).) ### What a value shows as (rev 2) The tracer classifies; this is how each class is set. | It is | Because | Shown | | --- | --- | --- | | a pointer | it lies in a mapping | its address in the region's ink, and its chain | | a code address | the mapping is executable | address, then `name+offset` in primary | | a string | a pointer to printable bytes and a NUL | `"..."` in string ink | | a digit | not a pointer, under 10 | `4` | | a small number | not a pointer, 10 to 0xffff | `0x21` and its decimal after it, faint: `0x21 33` | | a large number | not a pointer, larger | hex in fours with `0x`, primary | | a small negative | within 4096 of 2^64 | `-1` | | a file descriptor | a syscall's signature, or a variable's name and type, says so | the number, and faint what it was opened on: `3 "note"` | | flags | eflags; an argument a signature calls flags | names: `O_RDONLY|O_CLOEXEC`; for eflags all eight, as above | | a boolean | the debug info types it so | `true`, `false` | | a character | the debug info types it so; a byte in a text view | its hex and the character: `0x41 'A'` | | unknown | never observed | two dots | Decimal goes beside hex when a value is a small number and nothing says which it is (registers, stack words, heap words). When the type is known the type decides: an `int` is decimal alone, a pointer hex alone. In a system call's rows a size or a count is decimal first. ### Disassembly A row an instruction: the address in code's ink, its offset in the function faint (`+22`, to match rip and the backtrace), the mnemonic as a keyword, the operands plain, a jump's target in code's ink. The function's name is the tag's note. - The pc's row: gold plaque with a marker, gold ember across. - Two rows above it are the instructions just run, with trail bars; the pc is never the top row. - **Under the pc, a row that says what its operand is**: `rdi + 8 =` and a telescope from the address computed. Before the step it is where to look; during it, its first link is framed as read or struck as written. - A `syscall`: under it, on vellum, the call decoded, a row an argument, by the argument's own name (`fd`, `buf`, `count`). ### Stack Eight words from rsp, low addresses on top. A lane for the plaques of the registers that point at each row; the row's own address in stack's ink; its chain. Where the frame pointer says so, a faint note at the row's end: `return address`, `main's saved rbp`. ### Backtrace A row a frame, newest on top: `#0` on a gold plaque, the name and offset, the file and line. Three rows; a deeper stack ends in a count. ### Source The whole file, in mono 20 on rows of 24, a window on it kept so that the current line is in its middle third. It scrolls by whole lines (0.4 s) and never cuts. Line numbers faint, ranged right in three characters. A line longer than the 67 characters the panel holds is cut with a faint `…`. - Current line: gold plaque on the number, gold ember across. - Trail: the last three other lines run keep a 4-unit bar at the left edge, gold cooling. ## The lens (rev 2) Everything the first pass drew that is not one of the five panels is a lens: a list's nodes and arrows, a call tree, an array's cells, the heap to scale, a string's bytes, a system call's crossing, the page map and the timeline of calls. One at a time, in the panel at the top of the program column. - It is drawn on the context's module (mono 20, rows of 24, values at 25) and one size up when it is the subject. The first pass's sizes (cells of 48, mono 30) are what it comes to under the camera at x1.5. - **It carries the words it is made of.** A list's lens is its nodes and, under them, the heap words that are those nodes, an address, a value and a `next` a row. A tree's nodes carry the frame they are; an array's cells sit over their bytes. - **It is tied to the context** the way a chain is tied to its target: the same address under a node as in `rdi`'s row; the registers' plaques on the node and on its row; the same mark at the same instant in the lens and in the words (read, struck, landed); and the step's one link. - What happens to a node happens to its words first: the words are the cause (`motion.md`, the cascade). - **With nothing to draw**, the panel still holds what a recording has beyond the five: the live heap, a chunk a row (address, size, its first words as a telescope), or the named variables, a row each (name, type, value by its class). They are the plainest lenses, and the default one whenever a recording has them. The forms themselves are as the first pass drew them, in mocks 1 to 8: | Lens | Mock | Its words | | --- | --- | --- | | list: nodes `[value | next]`, arrows in heap's ink, null a slash | [2](mock/02-list-insert.png), [9](mock/09-context.png) | the heap words, a node a row | | call tree: circles, results on the shoulder | [1](mock/01-fib-recursion.png) | each node's frame in the stack telescope | | array: cells, index tags, flights for a swap | [7](mock/07-sort-swap.png) | the bytes, where the array lives | | heap to scale: chunks, bins, masks, a wedge into one chunk | [4](mock/04-malloc-glibc-musl.png) | the chunk's words | | bytes: a grid of 8 with its text | [5](mock/05-memory-write.png) | themselves | | a system call: vellum, the call decoded, the bytes crossing | [3](mock/03-syscall-write.png) | the registers that carried it | | the far view: pages, system calls over time | [8](mock/08-far-view.png) | the mappings | Those eight frames were drawn as whole frames; each is now what its lens looks like with the camera on it. They have been redrawn in the new face and with pointers in their regions' inks, and are otherwise the first pass's. A title card and the legend ([mock 6](mock/06-title-legend.png)) are the only frames with no context: no program is running in them. ## Directing the eye in a full picture (rev 2) Everything is on screen, so nothing is found by being alone. In order of how often they are used: 1. **The cascade.** A step's effects arrive one place at a time, in the order they were caused, 0.30 s apart (`motion.md`). Onset is the pointer. 2. **The gold thread.** One current mark a panel: the source line, the pc, rip, frame #0, and the lens's current node. They move last, together. 3. **The strike**, the one solid warm thing in a frame of tints. 4. **The focus box.** The tag's box is gold in the panel the narration is in, and only there. It is the old level rail, moved onto the frame. 5. **The step's link**: one arrow, for one step, from a cause to its effect across panels. 6. **A veil** on the panels a named step does not touch (page at 50%, 0.3 s in and out). For a beat, not a scene. 7. **The camera**, to read: | Scale | Mono 20 becomes | Frames | For | | --- | --- | --- | --- | | x1.5 | 30 | 1195 by 560 | a column, or the lens with the registers' names and first links | | x2 | 40 | 896 by 420 | up to sixteen rows of one panel | | x4 | 80 | 448 by 210 | one chain, one node and its words | The rules of `motion.md` hold: the target is framed first, everything else fades, the move is 1.2 s, nothing else moves under it, and two seconds without a change is the limit. The camera comes back to the whole frame every time. It is a way of reading the context, not a place to be instead of it. **Levels** are no longer layouts. Going from a line of C to the register it writes to the bytes it stores is the cascade crossing the frame: source line (fire), disassembly note (where), registers (strike), stack or lens words (strike), lens (the idea changes). The viewer is never moved; their eye is. ## Motion [`motion.md`](motion.md) is the direction. What density changes in it: - A strike in the context: the arm is a 2-unit frame; the pulse goes out 3 units, not 4; the fill cools to nothing and leaves the tick. - A telescope extends link by link, 4 frames apart, each fading in over 6. - A register's plaque slides to the row or node the register now points at (0.4 s, `glide`), after the register is struck. - The step's link draws in 0.4 s (`standard`) after the strike, and fades over 0.3 s as the marks advance. - The pace counter and the progress line are on the clock rule over the caption, not in a head. - Camera frames are those in the table above; x1.5 is the usual one. ## Legibility rules (rev 2) - Mono 20 and sans 18 are the floor. Medium weight under mono 30. - Whatever the narration names is also at 35 in the caption or at 30 under the camera. - Lines: 2 units is the thinnest (rules, a read's frame, an arrow's shaft in a chain); 3 for a link and a lens's frames; 4 for a tick. - A region is told by ink; a mark never is. No mark sits under coloured digits except a strike, for its 0.6 s, and the gold ember of a current row. - No alpha tints but the veil, no gradients, no glow, no grain. - Dashes 12 on, 8 off; the hatch 5 on a pitch of 20. Nothing finer. - Solid vellum is the kernel and nothing else. - One gold mark a panel. One step's writes in vermilion at a time. - Nothing is hidden to make room. A row that cannot hold its chain ends in dots at its far end; a panel that cannot hold its rows ends in a count. ## The mocks `mock/gen.py` draws 1 to 8 and `mock/context.py` 9 to 11; resvg renders them; each has a `-480.png` beside it. | | Shows | After looking | | --- | --- | --- | | [9](mock/09-context.png) | **(rev 2)** the default frame at rest: moment 71, stopped in `reverse` at `mov rdi, [rdi + 8]` | the first draft's lens had plaques over its table's heads and a note over a column: nodes, addresses, plaques and words each got a row of their own | | [10](mock/10-context-step.png) | **(rev 2)** the same, mid-step: `rdi` struck, its chain re-followed, the word it read framed in three places, its plaque moved, the link to its node | the link ran through the register's name like a strike-through, and ended in empty space: it now leaves from the panel's edge and lands on the row, which is framed whole. Chain arrows went from 24 to 30 wide: at 24 they touched the digits | | [11](mock/11-context-lens.png) | **(rev 2)** the lens as subject: 432 tall, a size up | a note collided with a column head at the larger size and was dropped | | [1](mock/01-fib-recursion.png) to [8](mock/08-far-view.png) | the first pass's frames: now the lenses, and the title card | redrawn in JetBrains Mono, with pointers in region ink and the legend remade: what happened in one row, what a thing is in the other | The data in 9 to 11 is the recording's: every register and chain, the instructions, the stack. The backtrace is read off the stack's return addresses. The lens's heap words are what the chains and the program say the heap holds; the recording, made under ptrace, has no allocations in it. **At 480 wide** ([9](mock/09-context-480.png), [10](mock/10-context-step-480.png)): no digit of the context can be read. What is left is the two columns, four gold rows, the strike on `rdi` and the link from it into the lens, yellow and blue as texture, and the caption whole. In [11](mock/11-context-lens-480.png) the list's values can be read as well. That is the phone's share, and the reason for the rule about the caption. ## What this asks of the renderer (rev 2) 1. **Faces.** JetBrains Mono NL in four (Regular, Medium, Bold, Italic) and Go in three. `sk.Face` has no medium mono today. 2. **A camera rest at 1.5**, with text shaped for its size there (mono 30, an advance of 18), as it is at 1, 2 and 4. 3. **Many runs.** A context frame is about 700 separately inked runs of text: every group of four hex digits is its own. Unsure whether `f.text` at that count is comfortable in an export, or wants batching. 4. **From the recording**, which I have not checked beyond `ztrace show`: - the instructions *before* the pc (from earlier moments, or decoded backwards), for the two trail rows; - an instruction's memory operand as data (base, index, displacement), so the note under the pc can compute and follow its address; - a backtrace: `show` names return addresses in the stack but prints no frames for a ptrace recording; - a lens's words when nothing recorded an allocation (`-w`, or the agent). 5. Underlines, ticks and frames are rects; the scrolling source wants `f.clip`; chain arrows are 8-pixel polygons and rely on the supersampling. 6. Still open from the first pass: dashed strokes from `sk.draw`. ## Token changes For `anim/src/theme.zig`. Nothing in `time` changes but the two additions at the end. | Token | Was | Is | | --- | --- | --- | | `font.mono` | Go Mono, `Go-Mono.ttf` | JetBrains Mono NL, `JetBrainsMonoNL-Regular.ttf` | | `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: mono under 30 | | `font.mono_bold` | `Go-Mono-Bold.ttf` | `JetBrainsMonoNL-Bold.ttf` | | `font.mono_italic` | `Go-Mono-Italic.ttf` | `JetBrainsMonoNL-Italic.ttf` | | `size.mono.context` | | 20 | | `size.mono.small` | 25: gutters | 25: a lens as subject, a lens's values | | `size.mono.data` | 30: anything read | 30: the context under the camera | | `size.sans.micro` | 22 | 18 | | `size.sans.tag` | | 20 | | `size.sans.label` | 28 | 28, in title cards only | | `size.min_read` | 28 | 20 | | `size.min_any` | 22 | 18 | | `canvas.head`, `head_baseline`, `head_rule_y` | 48 to 96, 81, 104 | removed | | `canvas.stage` | y 120, h 768 | y 48, h 840 | | `canvas.clock_y` | | 900 | | `canvas.row_gap` | 24 | 12 | | `layout.solo`, `duo`, `duo_even`, `trio`, `trio_stack`, `trio_hero`, `quad`, `far`, `crossing` | | removed | | `layout.program`, `layout.state` | | `cols(0, 6, 0, 840)`, `cols(6, 6, 0, 840)` | | `layout.split.none` | | source 21 rows, disassembly 10 | | `layout.split.beside` | | lens 312, source 12, disassembly 6 | | `layout.split.subject` | | lens 432, source 8, disassembly 5 | | `layout.state_rows` | | registers 18, stack 8, backtrace 3 | | `color.region.stack` | | `f2d675` | | `color.region.heap` | | `86b6ff` | | `color.region.code` | | `ff8f9a` | | `color.region.data` | | `d59cf5` | | `color.string` | | `b5e8c8` | | `color.code.literal` | `c8f0d8` | `b5e8c8` | | `color.veil_alpha` | 0.65 | 0.50 for a beat's veil; 0.65 under the camera | | `Role.pointer`, `Form.arrow` | orchid frame and arrow | removed; `Role.link`: region ink, `Form.thin_arrow` 3 wide | | `mark(.write)` held, in the context | ember and bar | `metric.context.tick` | | `metric.context.row` | | 24 | | `metric.context.tag` | | 24 | | `metric.context.pad` | | 6 above and below the rows, 12 at the sides (8 in the stack) | | `metric.context.name_w` | | 60: five characters | | `metric.context.chain_x` | | 72 | | `metric.context.arrow_w` | | 30, for both arrows of a chain | | `metric.context.group_gap` | | half an advance: 6 at mono 20 | | `metric.context.tick` | | 4 wide, the row less 6 tall | | `metric.context.plaque_h` | | the row less 4 | | `metric.context.read_frame` | | 2 | | `metric.context.pulse_outset` | | 3 | | `metric.context.string_min` | | 6 characters | | `metric.context.source_chars` | | 67 | | `metric.lens.node` | 180 by 72 | 116 by 44 beside, 124 by 64 as subject | | `metric.max_rows` | 10 | removed: nothing is hidden | | `camera.scales` | 1, 2, 4 | 1, 1.5, 2, 4 | | `time.unroll` | | 4 f (0.0667) between links re-followed | | `time.link` | | 0.40 to draw, 0.30 to go | ## Implementation order (rev 2) 1. The faces and `size.mono.context`; the one-row panel. 2. **The telescope**: an address in its region's ink, the two arrows, the end by class, the cut at the row's end. It is three of the five panels. 3. Registers, stack, backtrace: the state column, at rest. 4. Source (scrolling) and disassembly with its note: the program column. 5. Marks at density: strike, tick, read frame, the telescope extending. The cascade of `motion.md` over these five panels. 6. Plaques at what registers point to, in the stack and then in a lens. 7. The lens panel and its three splits; the list first, with its words. 8. The step's link; the veil; the camera at x1.5. 9. The other lenses, from what exists: tree, array, heap, bytes, crossing. Shader effects worth having: still none. Export: ```sh canim --export - --size 3840x2160 --fps 60 --frames N | ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - \ -c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \ -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4 ```