diff options
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 557 |
1 files changed, 557 insertions, 0 deletions
diff --git a/design/README.md b/design/README.md new file mode 100644 index 0000000..826973e --- /dev/null +++ b/design/README.md @@ -0,0 +1,557 @@ +# 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). + +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. +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. + + + +## Canvas + +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. + +| 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 | +| caption | 912 to 1032 | one or two lines of narration | +| margin | 1032 to 1080 | page only | + +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. + +**No data below y = 888.** The player's controls and subtitles cover the +caption band; only narration goes there. + +**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. + +Layouts (`theme.layout`), by number of views: + +| Views | Name | Columns | Mock | +| --- | --- | --- | --- | +| 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 | + +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. + +## Colour + +| | Hex | On page | On `raised` | Use | +| --- | --- | --- | --- | --- | +| page | `0a1030` | | | the ground; panel bodies too | +| raised | `16245f` | 1.3 | | tags, cells, cards, 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 | +| 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. + +| Role | Solid | Ember | Ratios | Form | +| --- | --- | --- | --- | --- | +| 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** 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. + +**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. + +**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". + +**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). + +**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. + +## Type + +| 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 | +| Go | `Go-Regular.ttf` | captions, notes | +| Go Medium | `Go-Medium.ttf` | tags, labels, the running head | +| 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 | + +- **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. + +## Components + +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: + +| Event (`trace.Kind`) | Drawn as | +| --- | --- | +| `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 | + +### Panel + +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. + +### Register table (mocks 1, 3, 5) + +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*). + +- 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 same table, with a type column and decimal values, is the **locals** +table (mock 7). + +### Memory grid (mocks 2, 5, 8) + +One 8-byte word a row, always: a row is a stack slot, a pointer, a field. +Three distances: + +**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. + +- 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). + +**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. + +**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. + +### Stack + +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. + +### System call (mock 3) + +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 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. + +**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. + +### Source panel (mocks 1, 2, 3, 5, 7) + +Mono 30 on lines of 48. Gutter: three digits ranged right, then 16; code 20 +after. + +- 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. + +### Data structures (mocks 2, 7) + +- **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. + +### Heap map (mock 4) + +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. + +### Words on the frame + +- **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. + +## Levels, and moving between them + +What keeps a viewer's place: + +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. + +Source to registers to bytes and back, as a sequence: + +| | 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 | + +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. + +## Motion + +60 frames a second; every duration is a whole number of frames +(`theme.time`). + +| 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 | + +Nothing bounces. The one overshoot is a struck cell's scale, +`1 + 0.08 sin(pi t)` over 0.20. + +**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. + +**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. + +**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. + +**Pace.** + +- *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. + +**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. + +## Legibility rules + +- 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. +- One gold mark a panel. One step's writes in vermilion at a time. + +## The mocks + +Generated by [`mock/gen.py`](mock/gen.py) and rendered with resvg; each has +a `-480.png` beside it, the phone check. + +| | Shows | Changed 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 | + +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. + +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 + +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. + +## Implementation order + +Most clarity for the least code first. + +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. + +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. + +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 +``` |
