diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 14:12:42 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 14:35:56 -0300 |
| commit | f8740f6996eefc235af066a6686f52847c158a6b (patch) | |
| tree | 1536ce2825e337e2dac75046093b583d04a96d9b /design/README.md | |
| parent | e2fa716dcda7de877908de006adc34f0c3593693 (diff) | |
| download | computeranim-f8740f6996eefc235af066a6686f52847c158a6b.tar.gz computeranim-f8740f6996eefc235af066a6686f52847c158a6b.zip | |
design, revision 2: the whole context in every frame, a lens beside it
The user's premise: show what pwndbg shows, hide nothing; the semantic
views stay as a lens on the machine. So every frame holds the registers
(all, each followed as a pointer), the stack telescope and the backtrace
in a column that never changes, and the source, the disassembly and the
scene's lens in the other. A value's ink says where it points (stack,
heap, code, data; rwx underlined), its paper says what happened to it.
JetBrains Mono NL for everything mono; the floor is mono 20, which a
phone does not read: what narration depends on is also in the caption.
Mocks 9 to 11 are drawn from a real recording of targets/list.
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 976 |
1 files changed, 536 insertions, 440 deletions
diff --git a/design/README.md b/design/README.md index 9e853bc..b108cf2 100644 --- a/design/README.md +++ b/design/README.md @@ -1,555 +1,651 @@ # canim: the look -How a canim frame is laid out, coloured, set and moved. The numbers are in -[`src/anim/theme.zig`](../src/anim/theme.zig) (`zig test` checks the contrast -figures quoted here); eight frames drawn with them are in [`mock/`](mock). +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.** The palette is 0x4200.cafe's own (pardes's - `lapis` theme), re-cut for video: a deep blue page, cream text, gold for - where execution is, vermilion for what just changed. -2. **Paper, not letters.** Meaning is carried by what is behind and around a - value (a fill, a frame, an arrow), never by the colour of its digits. Hue - on letters is syntax, and quiet. -3. **Every mark has its own form.** Written is filled, read is framed, a - pointer has an arrow, freed is hollow and dashed, unknown is two dots. No - two roles are told apart by hue alone. -4. **Solid vellum is the kernel.** The other side of a system call is the - page's negative: a cream ground with blue ink, at every scale, from the - slab under a crossing to a 12-unit block on a timeline. +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. **Mono is the machine, sans is the narrator.** Anything recorded from the - program is Go Mono; anything said about it is Go. +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. + + + +## 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 | -## Canvas +## The frame (rev 2) -1920 by 1080 logical units; a 4K master is the same layout at two pixels a -unit. Master at 2160p60 even for a 1080p audience: YouTube gives a 4K upload -a better 1080p stream. +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 only | -| running head | 48 to 96, rule at 104 | title; where the program is; level rail | -| stage | 120 to 888 | panels | +| 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 only | +| margin | 1032 to 1080 | page | -Side margins are 64. Between them, 12 columns of 120 with gutters of 32. -Panels stacked in a column are 24 apart and their heights are multiples of -24. The module is 12: a byte cell is 48, a memory row 60, a tag, a code line -and a register row 48. +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. -**No data below y = 888.** The player's controls and subtitles cover the -caption band; only narration goes there. +**The state column** (right, x 976 to 1856) is the same in every frame of +every scene: -**Order is meaning.** Source is leftmost, then the CPU, then memory. A lower -level is never left of, or above, a higher one; the kernel is always -underneath. Addresses increase downward in every grid, so the newest stack -frame is on top in the byte view as it is in the card view. +| 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 | -Layouts (`theme.layout`), by number of views: +**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: -| Views | Name | Columns | Mock | +| 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 | | --- | --- | --- | --- | -| 1 | `solo` | 12 | | -| 2 | `duo` | 5, 7: context and subject | 5 (the 5 holds two) | -| 2 | `duo_even` | 6, 6: a comparison | 4 | -| 3 | `trio` | 4, 4, 4: source, CPU, memory | 3 (above the kernel) | -| 3 | `trio_stack` | 5; 7 over 7 (240, 504) | 2 | -| 3 | `trio_hero` | 12 (408) over 7, 5 (336) | 7 | -| 4 | `quad` | 5; 7 (336) over 3, 4 (408) | 1 | -| far | `far` | 8, 4 (480) over 12 (264) | 8 | +| 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. -Four is the most. In a `quad` one panel is read and three are context; the -panel the narration is in has its tag's box filled gold. A panel shows at -most 10 rows of memory or of a table (14 lines of code); past that, elide -rows or go nearer. +**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, cards, node bodies | +| 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 | -| text, primary | `eee6d2` | 14.9 | 11.6 | anything to be read | -| text, dim | `9aa6d9` | 7.8 | 6.1 | names, notes | -| text, faint | `6a7ab8` | 4.5 | 3.5 | leading zeros, line numbers, column heads | +| 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 | -Marks (`theme.Role`, `theme.mark`). *Solid* is full strength; the *ember* is -the hold state, a colour of its own, not an alpha blend (gold blended over -lapis goes grey). Ratios: solid against the page, ink on solid, primary text -on ember. +### 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 | Ratios | Form | +| Role | Solid | Ember | In the context (mono 20) | In a lens's cell | | --- | --- | --- | --- | --- | -| current | gold `e8c46a` | `4a3d1c` | 11.1, 11.7, 8.6 | solid plaque on the label, ember across the row | -| write | vermilion `ff6a4a` | `5a2218` | 6.6, 6.9, 10.1 | solid fill, bold ink digits; cools to ember and a 6-unit solid bar | -| read | `6fd6e6` | `1c4652` | 11.0, 11.6, 8.3 | 3-unit frame, ember inside | -| pointer | `d59cf5` | `45305a` | 8.8, 9.2, 9.3 | 4-unit frame round the bytes, and an arrow | -| allocated | `7fdc9a` | `1f4a33` | 11.2, 11.7, 8.1 | ember block in a 3-unit solid frame | -| freed | no colour | | | hollow; dashed dim frame; coarse hatch where there is room | -| fault | vermilion | | | hazard bands round an ink plaque naming it | -| attention | bright | | | bright frame; a veil (page at 65%) over the rest | -| flow | primary | | | thin arrow, gone a second after it lands | -| unknown | faint | | | two 6-unit squares where the digits would be | -| kernel | vellum `eee6d2` | | 14.9 | the ground itself | +| 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). -- **Current** is one place a panel: the line, the instruction, rip, the newest - frame, the node, the page. All gold, so the eye joins them across panels. - rip is never "written"; it is current. -- **Write** is the only mark that fills a value and the only one that pulses. - The changed thing is the brightest warm thing on a blue frame. -- **Fault** shares write's colour on purpose (something was done to the - program) and is the only banded mark; it always carries the signal's name. -- **On the kernel's ground** ink is `0a1030`, dim text `4a5488` (5.8), rules - `b9ad8e`; accents stay solid inside a 2-unit ink frame; a cooled change is - `f3b9a0`. There are no embers there. +**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** say *which* object, thread or variable, the same in every view: -dark bodies under primary text (4.5 or better), so marks still read on top. -In order: ochre `8a5e0c`, teal `17707c`, madder `a03060`, malachite `1c7450`, -violet `6a3fb0`, azurite `2f5fc4`. At most four in a scene. Ochre and teal -are apart for every viewer; from the third on the name carries it, so a -pigment is never without its name. +**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 `c8f0d8`; comment `9aa6d9`, italic; line numbers faint. As -a pardes theme: `bg` page, `fg` primary, `kw`, `str` = `num`, `comment`, -`lineno`. pardes's own `lapis` is not used for video: its vermilion keywords -and gold strings would spend the two colours that mean "changed" and "here". +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. Two pairs fall together by hue for a deuteranope: -allocated with current, pointer with read. Neither pair ever shares a form -or a place (a block against a plaque, an arrow against a frame). +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.** Every accent is light (luminance 0.32 or more on a page of -0.007), so luma carries it; chroma only names it. Saturated colour is never -a line under 4 units or a fill under 12. Pigments, dark and saturated, are -fills only. Checked by encoding the mocks with x264 at CRF 34, and at 480p -CRF 30 scaled back up: 30-unit hex pairs, 25-unit address gutters, frames, -arrows and embers survive both; 2-unit rules, the hatch and 22-unit notes -fade at 480p, which is why none of them carries anything alone. +**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 | | --- | --- | --- | -| Go Mono | `Go-Mono.ttf` | data, code (sketchbook's built-in face) | -| Go Mono Bold | `Go-Mono-Bold.ttf` | keywords, a struck value, plaque letters | -| Go Mono Italic | `Go-Mono-Italic.ttf` | comments | +| 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, the running head | +| Go Medium | `Go-Medium.ttf` | tags, labels | | Go Bold | `Go-Bold.ttf` | titles | -Bigelow & Holmes, BSD-3-Clause (the Go licence); installed here by `ttf-go` -in `/usr/share/fonts/go/`, upstream `golang.org/x/image/font/gofont/ttfs`. -They drew Lucida, acme's face; the two families share an x-height and have -tabular figures and a slashed zero, and neither has ligatures to turn `->` -into an arrow. - -Sizes, in units: - -| Mono | | Sans | | -| --- | --- | --- | --- | -| 25 | gutters, types, small tags | 22 | tag notes, glosses, the rail | -| **30** | bytes, words, registers, code | 24 | a sentence beside a row | -| 35 | values in nodes and chunks | **28** | tags, labels, legend names | -| 45 | a value in flight | 30 | kicker | -| 60 | hero cells, a system call's name | 40 on 54 | caption (code in it: mono 35) | -| | | 44 | subtitle | -| | | 116 on 128 | title | +JetBrains Mono: OFL 1.1, `/usr/share/fonts/TTF/` (`ttf-jetbrains-mono` +2.304). Go: BSD-3-Clause, `/usr/share/fonts/go/`. -- **Mono sizes are multiples of 5.** Go Mono advances 0.6 em, so a character - is 15, 18, 21, 27 or 36 units, a hex pair is 36, and the grid is the same - whole-number arithmetic at 1080p and at 4K (the renderer rounds advances - to whole pixels). -- **Hard minimum: mono 30, sans 28** for anything the narration depends on. - On a phone held sideways that is an x-height of about 1.1 mm. 22 to 25 is - furniture: a viewer may lose it and still follow. -- **Hex**: lower case, groups of four, half a character apart, no `0x` - (`0x` belongs to source code and to sentences). A register is 16 digits, - an address 12, or its last 8 in a panel under 8 columns whose tag gives - the rest. Leading zeros are faint. In an address gutter only the last - group is primary: the end that changes from row to row. -- **Decimal** for what the source calls a number (locals, array values); - hex for what the machine holds. -- Code for a video is written to fit: 34 characters a line in 5 columns, 42 - in 6, 51 in 7. The panel strips common indentation. +- **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. -## Components +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. -Every component draws the same states the same way: plain; **write** (solid, -this step); **held** (ember and bar, changed within 3 steps); **read** -(framed, this step); **current**. What the recording provides: +| 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 | -| Event (`trace.Kind`) | Drawn as | +| Sans | For | | --- | --- | -| `step` and a `Regs` that differs | write on those registers; rip moves the current marks | -| `mem_write`, `mem_read` | write, read on those bytes (and on their page, from far) | -| `line` | the current line moves; the old one joins the trail | -| `call`, `ret` | a card on, or off, the call stack; a node in the call tree, then its result | -| `cmp` | a comparison plaque (`31 > 12`) | -| `variable` | a name beside its rows; a row in the locals table | -| `alloc`, `free` | a chunk becomes allocated, freed | -| `map`, `unmap`, `fault` | a row of the page map; a page becoming present | -| `syscall_enter`, `syscall_exit` | a block on the timeline; a crossing | -| `signal` | a fault band | -| `sched`, `thread_start` | a lane and a pigment for each thread | -| `mark` | a cue for a caption or a pause | +| 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 | -### Panel +**The hard floor is mono 20 and sans 18.** Nothing is smaller, anywhere. -Tag 48 tall on `raised`; a 20-unit box 14 in (gold in the panel the -narration is in, a faint hollow elsewhere); title sans medium 28 at x + 48; -a note, sans 22 faint, ranged right; rule 2 units round the body (dim when -in focus). The body is the page. Padding 20 and 16. +**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. -### Register table (mocks 1, 3, 5) +**Hex.** -Rows of 48: name (mono 30, dim) 18 in; value, 16 digits in fours, ranged -right. Needs 3 columns; 4 with a role beside the name (`rdi` *1st*). +- 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. -- Shown by default, in this order: rip, rax, rdi, rsi, rdx, rcx, rsp, rbp, - then flags CF ZF SF OF. Any other register appears when a step touches it - and leaves when its ember has gone. Rows never reorder. -- rip: gold plaque on the name, gold ember across the row. -- Flag chips 60 by 36: set is a 3-unit vellum frame and bold bright letters; - clear is a rule frame and faint letters; just changed has a 6-unit - vermilion bar under it. +## The context (rev 2) -The same table, with a type column and decimal values, is the **locals** -table (mock 7). +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`. -### Memory grid (mocks 2, 5, 8) +### Panel -One 8-byte word a row, always: a row is a stack slot, a pointer, a field. -Three distances: +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. -**Bytes.** Left to right: mark lane (88) for registers and pointer variables -that hold this row's address, as plaques pointing in; address gutter (mono -25); arrow lane (52, plus 22 for each further arrow nested in it); 8 cells of -46 on a 48 pitch; the same bytes as text (mono 30, non-printing as faint -dots); names. Rows are 60 apart. +### Registers -- A zero byte has faint digits, so data stands out of padding. -- Never observed: two dots and no cell. Absence of fill is absence of - knowledge. -- A pointer: a 4-unit frame 6 outside its 8 cells, and an arrow that leaves - the frame's left edge, runs in the lane, and ends on the left edge of the - byte it holds the address of. A target off-panel ends in a plaque at the - panel's edge. -- Whose bytes: a divider row (a 12-unit square, gold for the frame that is - running; the function's or object's name; a rule). Stack frames, heap - chunks and globals are all dividers. -- A name spanning rows gets a 3-unit bracket. Variable names are mono; - descriptions (`saved rbp`) are sans. -- Bytes not shown: an elision row, three dots and what they are. -- A string: text cells 84 tall, the character over its byte (mock 3). +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. -**Words.** The 8 bytes as one number, on the footprint of the 8 cells (382 -by 46), with the field's name and meaning to its right (`next`, `= NULL`). -Bytes turn into their word in place: the pairs reverse order as they close -up, which is little-endian shown rather than said. +- 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. -**Pages** (the far form). A row a mapping: address, `r` `w` `x` chips, name, -size, then one 22-unit square a page on a 24 pitch. Hollow is mapped and -untouched, `rule`-filled is present, and the marks apply at this scale too: -the page holding rip is gold, a page read is framed cyan, written is -vermilion. The kernel's half is a vellum band underneath. +### The telescope -### Stack +One row a chain, read left to right: *this, which points to that, which +holds this.* -As memory: the grid, with a divider per frame and `rsp`, `rbp` in the mark -lane. As an idea: **cards** (mock 1), newest on top, 56 tall and 12 apart, -with a 12-unit spine (gold on the newest), the function in bold, its -arguments, and the line it is at. A call slides a card in from above; a -return strikes its value on the card, the card leaves upward, the value -flies to the caller. +- **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).) -### System call (mock 3) +### What a value shows as (rev 2) -The kernel's ground rises from the bottom edge to y = 576, full bleed, under -three user panels. The three columns keep their meaning through it: under -the source, what the kernel runs (cards in ink frames); under the registers, -the call decoded (its name, mono bold 60; rows of register, argument, value, -meaning); under memory, the kernel's copy of the bytes. +The tracer classifies; this is how each class is set. -- The registers that carry arguments are framed as read. -- A crossing is a 6-unit arrow, vellum above the line and ink below it. -- On return an arrow comes up and rax is written. An error return is a fault - band on rax with the errno's name. +| 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 | -**Timeline strip** (mock 8): the same boundary from far away. A 3-unit -vellum line with user time above and each call hanging below it as a vellum -block 44 tall, as wide as its time in the kernel (12 at least, 16 apart). -Calls not yet made are hollow. Names (mono 25) go under blocks left to -right wherever one fits. The current call has a gold plaque and a gold line -through it; brackets above name the phases of user time. With several -threads, a lane each, with its pigment and name. +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. -### Source panel (mocks 1, 2, 3, 5, 7) +### Disassembly -Mono 30 on lines of 48. Gutter: three digits ranged right, then 16; code 20 -after. +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. -- Current line: gold plaque on the number (ink, bold), gold ember across. -- Trail: the last three lines executed keep a 6-unit bar at the left edge - in gold cooling (`ae9350`, `746235`, `463b20`). -- Values: a hollow plaque at the end of the current line (`n = 1`). -- Lines left out: an elision row. -- **Unfold.** The current line opens into its instructions, indented 36 - behind a rule; the instruction at rip has an 8-unit gold bar and ember. - This is the step from source to CPU, and it happens in place. -- **One expression.** A bright frame round it, the veil over the rest; a - copy is set on a line below the code and its parts are replaced by their - values one at a time, each replacement a write. +- 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`). -### Data structures (mocks 2, 7) +### Stack -- **Array.** Cells 96 by 84 (mono 35), or 168 by 132 (mono 60) when the - array is the subject. The index, mono 25 faint, is inside the cell at top - left; index variables are dark tags inside it at top right, and slide from - cell to cell. A comparison frames both cells as read and puts the `cmp` - above them. A swap is two flights, one over and one under. -- **List node.** 180 by 72: the value (mono 35), then a 72-unit pointer - compartment with a 14-unit square the arrow leaves from. Null is a slash. - Arrows turn square corners with a 12-unit fillet and enter a node at its - left edge. -- **Tree, graph.** Circles of radius 24 (36 alone on the stage), edges 3 - units. Not yet reached: absent in a call tree, which grows as it runs; a - hollow ring in a graph. Waiting: page fill in a 4-unit vellum ring, on - 4-unit vellum edges. Current: solid gold. Done: `raised`, dim digits, its - result in a 28-unit badge on its shoulder. -- **A value moving.** It lifts into a card (100 by 60, bright frame, bold - 45), flies an arc, lands as a write. Where it left keeps its digits, - faint: a copy does not erase. +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`. -### Heap map (mock 4) +### Backtrace -A strip to scale, 4 units a byte, 88 tall (56 when two are stacked). The -allocator's own bytes are `rule`-filled; allocated is a green ember in a -green frame with its variable's name; freed is hollow, dashed and hatched; -never used is a rule frame; three dots where it continues. Bytes a step -wrote are vermilion at scale, inside the chunk. A **wedge** (two rules from -a thing's corners to its enlargement's) opens a chunk into word rows. -Bookkeeping is drawn as what it is: a row of counts for bins, a row of bits -for a mask, an arrow for a list's head. Two allocators side by side use the -same three tiers at the same heights. +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. -### Words on the frame +### Source -- **Label**: sans medium 28 beside its subject; an identifier is mono 30. -- **Note**: sans 24 dim; a gloss the narration also says. -- **Plaque**: 40 tall, 12 padding. Hollow for a value, `raised` for a place - or a name, a pigment for a tracked object. -- **Callout**: there is no bubble. A note plus a bracket, a wedge or a flow. -- **Caption**: sans 40 on 54, ranged left on the margin, two lines of 64 - characters at most. On the kernel's ground it is ink. -- **Running head**: the title (sans medium 28, dim); then, mono 25 faint, - where the program is, which is the current line itself whenever no source - panel is on screen. At the right the **level rail**: source, cpu, memory, - kernel, each a 16-unit square: gold where the narration is, solid when on - screen, hollow when not. -- **Title card** (mock 6): a gold square and the series (sans medium 30); - the title, Go Bold 116 on 128, bright; a subtitle, 44, dim. -- **Legend** (mock 6): a sample 94 by 46, a name (28), a gloss (22). The - full card follows the title once; up to four entries may sit in the - caption band while no caption is up. +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 `…`. -## Levels, and moving between them +- 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. -What keeps a viewer's place: +## The lens (rev 2) -1. **Place.** Left is source, right is memory, down is the kernel. A level - enters from its own side and leaves to it. -2. **Gold.** Each panel has one current mark. Going down a level, the upper - level's gold is the last thing to dim and the first to return. -3. **The running head.** When the source panel is collapsed, its current - line is written in the head. The rail says which levels are on screen. -4. **Pigment.** A tracked variable has one pigment in the locals table, on - its list node and on its rows of memory (mock 2). -5. **Three lines, three meanings.** A pointer arrow (orchid, 4 units, - filled head): this number is that address. A flow (vellum, 3 units, for - a second): this value went there. A wedge (two rules): this, magnified. +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. -Source to registers to bytes and back, as a sequence: +- 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. -| | What happens | Seconds | -| --- | --- | --- | -| 1 | the current line holds | 0.5 | -| 2 | it unfolds; the lines below move down, instructions arrive 0.03 apart | 0.4 | -| 3 | if registers are not up: the source narrows, they enter from the right | 0.8 | -| 4 | the instruction mark steps; each step strikes the registers it writes | 0.25 a step, then hold | -| 5 | an instruction with a memory operand: the operand is framed | 0.4 | -| 6 | a flow draws from the register to the row; the value flies it; the bytes strike | 0.4, 0.6 | -| 7 | nearer: the rows are framed, the rest veiled, the camera goes to x2; the source is now the head's line | 0.4, 0.3, 1.2 | -| 8 | back: camera to x1, veil off, the line folds, the mark steps to the next line | 1.2, 0.3, 0.4, 0.25 | +The forms themselves are as the first pass drew them, in mocks 1 to 8: -From far to near (mock 8): a wedge draws from the page, or the block of -time, to a panel beside it (0.3). Both may stay, or the camera goes in (1.6 -for x4) and the far view survives as the head's text. +| 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 | -## Motion +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. -Revised and extended by [`motion.md`](motion.md): the order of events -within a step, charts frame by frame, and the tokens it changes. What -follows is the first pass. +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. -60 frames a second; every duration is a whole number of frames -(`theme.time`). +## Directing the eye in a full picture (rev 2) -| Name | Seconds | For | -| --- | --- | --- | -| `snap` | 0.10 | a colour changing where nothing moves | -| `quick` | 0.20 | leaving; a small change of state | -| `step` | 0.25 | the current mark moving to a neighbour | -| `move` | 0.40 | moving within a panel, up to 400 units | -| `travel` | 0.60 | moving between panels, or further | -| `layout` | 0.80 | panels rearranging | -| `camera` | 1.20, 1.60 | to twice or half the scale; beyond | - -| Curve | cubic-bezier | For | -| --- | --- | --- | -| `standard` | 0.2, 0, 0, 1 | whatever moves and stays: off promptly, a long settle | -| `enter` | 0, 0, 0.2, 1 | arriving | -| `exit` | 0.4, 0, 1, 1 | leaving | -| `camera` | 0.65, 0, 0.35, 1 | camera and layout | -| `linear` | | colour cooling, the playhead | +Everything is on screen, so nothing is found by being alone. In order of +how often they are used: -Nothing bounces. The one overshoot is a struck cell's scale, -`1 + 0.08 sin(pi t)` over 0.20. +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: -**How a change is signalled.** A write: solid in 0.10 with a 0.20 pulse; -solid for 0.50; cools over 0.40 to its ember and bar; stays while the thing -has changed within 3 steps (4 s where time runs free); gone in 0.60. A -read: framed in 0.10, kept for the step (0.50 at least), gone in 0.30, no -pulse. The current mark slides (0.25); over more than 8 rows it goes out -and comes in (0.10 each) and the trail shows where it was. A pointer -changing target: the head travels the lane (0.40); the old path stays, -dashed and faint, for 0.80, then fades in 0.30. +| 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 | -**What moves and what fades.** A thing that is the same thing before and -after moves: a value, the current mark, an arrow's head, a card. A thing -that begins or ends fades: a frame, a caption, a panel's contents. A value -in flight lifts (0.10, to 1.12), flies an arc a quarter as high as it is -long (34 to 120 units), and lands as a write. +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. -**How much at once.** One thing moves because the program did something; -at most two more move because of it (a value lands, a cell strikes, an -arrow turns). Things arriving together start 0.03 apart in reading order, -the last no more than 0.30 after the first. The camera and the layout move -alone, with no state changing under them. +**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. -**Pace.** +## Motion -- *Walk*: 1.5 s a step, with everything above. The first three times a - pattern is shown, and any step the narration names. -- *Run*: 0.25 s a step. No pulses, no flights; colour only. -- *Sprint*: under 0.05 s a step. Single changes are not drawn; embers and a - counter are. -- Still for 0.8 after the stage is rearranged, for 1.0 before it is again. -- A caption stays 1.5 s plus 0.06 a character. It fades in over 0.25 rising - 8 units and is never typed out. Captions change while nothing moves. +[`motion.md`](motion.md) is the direction. What density changes in it: -**Camera.** Three scales only: x1 the frame, x2 a panel, x4 a few cells. It -never turns. The target is framed for 0.4 first; the camera holds 0.6 on -arrival; 1200 units a second at most. Whatever would end smaller than its -minimum size is faded out before the move, not shrunk. +- 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 +## Legibility rules (rev 2) -- Text: mono 30 and sans 28 or larger for what must be read; nothing under 22. -- Lines: 2 units is the thinnest (rules, never meaning); 3 the thinnest - that means something; 4 for arrows. Nothing is 1 pixel at 1080p. -- No hue alone: each role has its form (the table above; a test checks no - two share one). -- No alpha tints, no gradients, no glow, no grain. Flat fills cannot band, - and a codec spends its bits on edges, which are all axis-aligned here but - for arrows and tree edges. -- Dashes are 12 on, 8 off; the hatch is 5 on a pitch of 20; a fault's bands - are 12. Nothing finer: it turns to mush at 480p. Freed reads by being - hollow and dashed; the hatch only helps at 720p and up. -- Solid vellum is the kernel and nothing else: no vellum chips, tags or - buttons. +- 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 -Generated by [`mock/gen.py`](mock/gen.py) and rendered with resvg; each has -a `-480.png` beside it, the phone check. +`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 | Changed after looking | +| | Shows | After looking | | --- | --- | --- | -| [1](mock/01-fib-recursion.png) | `quad`: source, call tree, call stack, registers | gold tints were alpha blends and came out grey, so embers became colours of their own; the flags ran into the panel's edge, so the table shows five registers | -| [2](mock/02-list-insert.png) | list nodes over the heap words that hold them | the pigment spines sat at the far right, away from the rows they named: now plaques in the mark lane, pointing at their rows; column heads gave way to a note in the tag, to fit six rows | -| [3](mock/03-syscall-write.png) | `write` crossing into the kernel | the memory panel overflowed, hence the 8-digit gutter for narrow panels; U+2423 fell back to another font, so the visible space is drawn; `user` and `kernel` set larger | -| [4](mock/04-malloc-glibc-musl.png) | glibc and musl after `free(b)` | first pass was three tiers of collisions and an arrow touring the panel; rebuilt as the same three tiers both sides, a wedge into `b`, and a short arrow from the bin to the row | -| [5](mock/05-memory-write.png) | a pointer being stored, byte by byte | a line from `rax` ran under the row like an underline: now a flow that stops short of the gutter; `rsp` and `rbp` moved from the far right to the mark lane; frame dividers added | -| [6](mock/06-title-legend.png) | title card and the legend | six glosses collided at five-across widths: shortened, twelve entries in two rows | -| [7](mock/07-sort-swap.png) | insertion sort, a compare and a swap | cells were small in an empty panel, so the hero size; index variables moved from under the cells to tags inside them, freeing the space a swap needs | -| [8](mock/08-far-view.png) | page map, one page magnified, system calls | the kernel row was clipped and page counts ran out of the panel: sizes got a column, the kernel a band; the wedge went from three lines to two; two call names collided, so names are placed only where one fits | +| [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. -Across all of them, after the first round: mono sizes went from 22, 24, 28 -to 25, 30 (whole-unit advances, and larger on a phone); set flags and index -tags stopped being vellum chips once vellum meant the kernel; the hatch was -coarsened after the 480p encode. +**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. -Specified here and not yet drawn: a graph, a tree as the subject, ordinary -array cells, thread lanes, a fault in place, the bytes-to-word change, the -expression line. +## What this asks of the renderer (rev 2) -## What this asks of the renderer +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`. -1. **More than one face in `f.text`**: Go Mono Bold (and Italic), and Go in - three weights. The README describes one family set by an environment - variable. Sans text is nearly all written by the author, so it can be - Typst (which must be given `--font-path` for the Go fonts); bold mono is - data and cannot. Without it the design still works: bold falls back to - regular and the fills carry the state. -2. **Text under a moving camera.** Text is drawn at whole-pixel advances for - its size, so at the in-between scales of a zoom the letters will shift - against each other. Either a panel is drawn to an image for the move and - scaled (that needs linear filtering; images sample nearest natively), or - moving text is drawn as outlines. -3. **Dashed strokes** from `sk.draw` (the vector module has dashing). -4. **Hatch and hazard fills**: lines clipped to a rect; `f.clip` suffices. -5. **Whole-unit mono advances** at 60, 50, 70, 90, 120 pixels (the 4K sizes) - as well as at 30, 25, 35, 45, 60: Go Mono's 0.6 em should round to them. -6. The veil is one translucent rect; nothing else needs alpha, additive - blending or a shader. +## Token changes -## Implementation order +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 | -Most clarity for the least code first. +## Implementation order (rev 2) -1. `theme.zig`, the panel, mono text in columns: the **register table** and - the **source panel** with the current line and trail. Rects and text. -2. **The mark state machine**: plain, write, held, read, current, with the - strike and cooling timings. Every later component is this on a - different shape. -3. **Caption and running head** with the level rail. -4. **Memory grid**, bytes and words: gutter, dividers, elision, names. -5. **Arrows** with filleted elbows and heads: pointers, flows. Then list - nodes and call stack cards, which are rects and arrows. -6. **The kernel's ground** and the crossing; the timeline strip. -7. **Flights**: a value on an arc. Hero array cells, compare, swap. -8. **Unfold**, the step from a line to its instructions. -9. Call tree (a tidy tree layout), heap strip, wedge, page map. -10. Veil and camera at x2 and x4; bytes to word; the expression line. +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: none. A glow on a write would soften the one -edge that most needs to stay sharp, grain costs bitrate and there is no -gradient for it to protect, and a vignette darkens the corners where the -running head and rail live. +Shader effects worth having: still none. Export: |
