summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 17:16:50 -0300
committerGabriel Schneider <[email protected]>2026-11-10 17:56:05 -0300
commit74c45474f7e3e1b3539eb88484e6749082c6addf (patch)
tree29be105369df0b9f5bb92adb50360fd99fd664b8 /design/README.md
parent47f43f0f26b08901c1ddd16aacbe50c2c843ab8a (diff)
downloadcomputeranim-74c45474f7e3e1b3539eb88484e6749082c6addf.tar.gz
computeranim-74c45474f7e3e1b3539eb88484e6749082c6addf.zip
design: the band is two panels; what the first videos taught
An independent review of the first videos, frame by frame, is placed in the catalogue. A lens is a drawing over the program column and its view over the state column (the dump; the backtrace for calls), which leaves the stack six slots as subject: the frame whole, from rsp to past rbp. Operands are whole. A mark covers the bytes that changed. A pin travels and keeps its side. A call's node is a projection of its return address. Fast passes are veiled. Captions have numbers a scene can be checked by, and a scene's first step comes by four seconds. Effects before causes and panels from different moments are forbidden by name. Mock 12 draws fib(4) calling fib(2) from the recording. Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md571
1 files changed, 383 insertions, 188 deletions
diff --git a/design/README.md b/design/README.md
index 8624017..bb78f1e 100644
--- a/design/README.md
+++ b/design/README.md
@@ -52,32 +52,32 @@ this table.
| | [`byte`](#byte) | two hex digits of a dump | `number`, `pointer`, `allocator`, `unread`; `pad` |
| | [`mark`](#mark) | what happened to a thing | `current`, `armed`, `struck`, `held`, `read`, `trail`, `allocated`, `freed`, `fault`, `attention`, `unknown`, `kernel` |
| | [`plaque`](#plaque) | a solid label under the current mark | `gold`, `chip` |
-| | [`pin`](#pin) | a register's name at the thing it points to | `row`, `under` |
+| | [`pin`](#pin) | a register's or a variable's name at the thing it points to | `row`, `under` |
| | [`bracket`](#bracket) | a span marked at its edge | `quiet`, `tie` |
| | [`tag`](#tag) | a panel's title bar | `focus`; `note` or `legend` |
| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop |
| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) |
-| | [`slot`](#slot) | a word of the stack and its chain | pins |
+| | [`slot`](#slot) | a word of the stack and its chain | pins; `free` |
| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` |
| | [`line`](#line) | a line of source | `current`, `trail` |
| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run |
| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` |
| 3 panel | [`registers`](#registers) | all seventeen | |
-| | [`stack`](#stack) | the words from rsp, and the frames they belong to | 8 or 4 slots |
-| | [`backtrace`](#backtrace) | the call chain as rows | only in the `none` split |
+| | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | 8 or 6 slots |
+| | [`backtrace`](#backtrace) | the call chain as rows | in the `none` split; the view of `calls` |
| | [`source`](#source) | a window on the file | 14, 8 or 10 lines |
-| | [`disasm`](#disasm) | the instructions round the pc | 17 or 11 rows |
-| | [`lens`](#lenses) | a drawing of some state, and the bytes it is drawn from | `beside`, `subject` |
+| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows |
+| | [`lens`](#lenses) | a drawing of some state over the program column, and over the state column the pane it is a view of | `beside`, `subject` |
| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | |
-| | [`nodes`](#nodes) `array` `calls` `heap` `syscalls` `pages` | the drawings a lens can hold | |
+| | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) `heap` `syscalls` `pages` | the drawings a lens can hold | |
| 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing |
-| | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin` |
+| | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin`; a stub when that is out of view |
| | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step |
| | [`echo`](#4-ties) | the same mark in two panels at once | for a step |
| 5 frame | [`stage`](#5-the-frame) | the band and the two columns | split `none`, `beside`, `subject` |
| | [`clock`](#clock-and-caption) | where in the recording | |
| | [`caption`](#clock-and-caption) | the narrator | |
-| | [`veil`](#clock-and-caption) | page over what a beat does not touch | |
+| | [`veil`](#clock-and-caption) | page over what a beat does not touch, or a pace cannot show | |
| | [`card`](#clock-and-caption) | a title, the legend: no program running | |
| 6 verb | [`fire` `arm` `strike` `cool` `read` `extend` `link` `project` `travel` `advance`](#6-verbs) | what one block does | |
| | [`cascade` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | |
@@ -181,7 +181,7 @@ Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros:
| Option | Draws |
| --- | --- |
| `lead` n | the first n digits at 60% of the ink toward the page. Used in a column of addresses (disassembly, stack slots, a dump's gutter) with n = the digits every row shares, leaving at least two: the eye reads the part that changes |
-| `name` | code only: `name+offset` in primary, 10 units on; the module when there is no symbol: `libc+27781` |
+| `name` | code only: `name+offset` in primary, 10 units on; the module when there is no symbol, its offset from the module's first mapping: `libc+27781` |
| `rwx` | a 2-unit underline |
States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each
@@ -200,7 +200,7 @@ What is not an address. The tracer classifies; the class decides.
| small negative | within 4096 of 2^64 | `-1` |
| string | a pointer to printable bytes and a NUL | `"..."` in string ink, C's escapes; cut with `…` and no closing quote, never under six characters |
| file descriptor | a signature or a type says so | the number, and faint what it is open on: `3 "note"` |
-| flags | eflags; an argument a signature calls flags | names |
+| flags | eflags; an argument a signature calls flags | names; bits no name covers as `0x` and their hex: `O_RDONLY 0x8000`. Never bare hex |
| boolean, character | the debug info types it so | `true`; `0x41 'A'` |
| unknown | never observed | two dots |
@@ -234,8 +234,9 @@ Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth.
`pad`: in a little-endian word, the bytes above its highest non-zero byte
are at 45% toward the page: `70 10 b4 28` stands out of `00 00 00 00`,
-and is the address `28b41070` read from the right. Marks are per run of
-bytes, never per byte: see [`bytes`](#bytes). Mocks 9 to 11.
+and is the address `28b41070` read from the right. A mark covers the
+bytes whose value changed, never more: see [`bytes`](#bytes). Mocks 9
+to 11.
### mark
@@ -269,18 +270,31 @@ and bright. Nothing else is a plaque: a register's name at a target is a
### pin
-A register's name at the thing it points to: the names, bold, primary, and
-a head in the target's region ink that touches the target. It answers "who
-points here", and it is a [`link`](#4-ties) at rest.
+A name at the thing it points to, and a head in the target's region ink
+that touches the target. A register's name is bold primary; a variable's
+(a pointer the debug info names: `cur`, `head`) is bold in the ink of
+where it lives, stack for a local and data for a global, so `cur` under
+a heap node reads "on the stack, pointing here". It answers "who points
+here", and it is a [`link`](#4-ties) at rest.
| Form | Where | Anatomy |
| --- | --- | --- |
| `row` | a row's lane (the stack) | the names, then a head 9 by 12 pointing right at the row's address |
-| `under` | under a drawn node | a stub 3 wide rising to the node's bottom edge, head 10 by 10; the first name left of the stub, the others right |
+| `under` | under a drawn node or cell | a stub 3 wide rising to the node's bottom edge, head 10 by 10; names 9 either side of the stub |
A pin for every register whose value is exactly the row's or node's
-address; three names, then a count. No box, no fill: the boxed names of
-the last revision read as buttons. Mocks 9 to 11.
+address, and for every variable the scene names, from the opening; three
+names, then a count. No box, no fill.
+
+- **Names keep their side.** On an `under` pin the first name to come is
+ left of the stub and the next right of it. When one leaves, the others
+ stay where they are, and the next to come takes the free side. Two names
+ never print in one place.
+- **A pin is one thing.** One register or variable has one pin, and it
+ travels between the things it points at: it never jumps, and is never
+ in two places ([`travel`](#6-verbs)).
+
+Mocks 9 to 12.
### bracket
@@ -332,6 +346,10 @@ A lane 112 wide for a `row` pin; the chain from 122, beginning with the
slot's own address in stack ink with `lead`; room to 136 from the right
edge, which belongs to the [`call`](#call) spans.
+`free`: a word above rsp, which the stack has not reached. Shown only
+while the window is held still for the camera ([`visit`](#6-verbs)): its
+address at 60%, its word in faint, no chain, no pin. A push fills it.
+
### insn
An instruction, pwndbg's way: what it is, and what its operands are now.
@@ -343,8 +361,20 @@ An instruction, pwndbg's way: what it is, and what its operands are now.
| 40 | address | code ink, `lead` |
| 134 | line | the source line this run of instructions came from, ranged right in three characters, faint; on the first row of each run only; gold and bold for the current line |
| 180 | mnemonic | keyword, bold |
-| 264 | operands | as the disassembler writes them, 24 characters; a jump's or call's target is an `address` in code ink |
-| 564 | annotation | 25 characters; cut at its far end |
+| 264 | operands | as the disassembler writes them, whole; a jump's or call's target is an `address` in code ink |
+| 564 | annotation | from 564, or a character after operands that run past it; a chain, cut at its far end by the chain's rule |
+
+**Room.** The row holds 50 characters from 264, to 12 from the panel's
+edge. Operands are never cut where the row has room, and never inside
+`[]`: we do not hide what the instruction says. When the operands and the
+whole annotation do not fit, in this order:
+
+1. the annotation moves left to where it just fits, never left of 564;
+2. a size word (`qword ptr `) goes from a memory operand whose size a
+ register operand gives: `mov rax, [rbp - 0x28]`. Nothing is lost;
+3. the operands give way to the annotation: they end where it begins, in
+ a faint `…`. A cut that would fall inside `[]` falls before the `[`,
+ and the annotation's first hop is the address the brackets named.
| State | Draws |
| --- | --- |
@@ -366,7 +396,9 @@ An instruction, pwndbg's way: what it is, and what its operands are now.
| makes a system call | its name and arguments by name, as a call; the kernel's rows hang under it on vellum |
Mocks 9 to 11 show the read, the register-setter, the taken jump and
-`outside`. Call, return, write and syscall annotations are not drawn.
+`outside`; 12 a call with its argument, a write, and operands longer
+than 24 characters with the annotation moved right of them. Return and
+syscall annotations are not drawn.
### line
@@ -378,7 +410,8 @@ other lines run.
### bytes
A hexdump row. Its runs come from the types of what the program's
-pointers reach.
+pointers reach: a run is one field of the element's type, an `int` 4
+bytes and a pointer 8, never two fields and never a store's width.
| x | Column | |
| --- | --- | --- |
@@ -391,21 +424,30 @@ The reading replaces a hexdump's text column: where bytes are text the
reading is the text, in quotes; where they are a pointer it is the address,
so a little-endian pointer is read without leaving the dump.
-Marks are per run: `struck` (the paper solid vermilion, digits bold in
-ink), `read` (a 2-unit frame 3 out), `held` (a tick in the gap at the
-run's left). A struct wider than a row spans rows, and its bracket spans
-them.
+Marks: `struck` (the paper solid vermilion, digits bold in ink) covers
+the bytes whose value changed between the two stops, inside one run,
+from the first that changed to the last: a pointer whose low byte alone
+moved is struck on that byte, and two `int`s swapped are struck as two
+runs of 4. A byte stored with its own value is not marked: the recording
+sees values, not stores. `read` (a 2-unit frame 3 out) frames the run
+read. `held` is a tick in the gap left of what was struck. A struct wider
+than a row spans rows, and its bracket spans them.
### call
One frame of the call chain, in two forms.
- `span`, on the stack: a bracket 14 in from the panel's right edge down
- the slots that are the frame, and the function's name left of it, Go
- Medium 18. `newest`: gold bracket, bright name. Older: rule and dim. A
- frame that runs past the panel's last slot has no bottom serif.
-- `row`, in a backtrace panel: `#n` (a gold plaque on the newest), the
- name and offset in primary at 60, file and line in dim at 276.
+ the slots that are the frame, and left of it the function's name, Go
+ Medium 18; for the function a `calls` lens draws, its arguments as a
+ call, `fib(4)`: two frames of one function are told apart, and the
+ digits are the ones on its node.
+ `newest`: gold bracket, bright name. Older: rule and dim. A frame that
+ runs past the window has no serif at that end.
+- `row`, in a backtrace panel: `#n` at 12 (a gold plaque 40 wide on the
+ newest), the name and offset in primary at 60, the arguments at 384
+ (`n=4`, primary), file and line ranged right, dim. Arguments where the
+ debug info gives them.
## 3. Panels
@@ -420,17 +462,36 @@ moment's registers and mappings.
### stack
-`slot`s from rsp, low addresses on top: eight; four when the lens is the
-subject. `call` spans down its right edge: the backtrace, drawn on the
-words that are each frame. rsp and rbp are pins in its lane. Reads the
-stack words, and each frame's extent (the frame-pointer chain, or the
-unwinder's CFA).
+`slot`s, low addresses on top: eight; six when the lens is the subject.
+`call` spans down its right edge: the backtrace, drawn on the words that
+are each frame. rsp and rbp are pins in its lane. Reads the stack words,
+and each frame's extent (the frame-pointer chain, or the unwinder's CFA).
+
+**The window** is on the newest frame: the words from rsp to its return
+address, `[rsp, rbp+16)`, its locals, saved rbp and return address.
+
+- Where the frame is no longer than the window, the window's top is rsp
+ and the caller's words fill the rest.
+- Where it is longer, the window scrolls down it by whole slots
+ ([`scroll`](#6-verbs)) to keep the slot a step touches in its middle
+ rows (the third and fourth of six; third to sixth of eight), and stays
+ there until a step touches a slot outside them. Its top never passes
+ above rsp.
+- A push or a call moves the top with rsp: the rows slide one slot (18 f,
+ as rows making room), at the memory level, before the new word is
+ armed.
+- While the camera is on the stack the window holds still
+ ([`visit`](#6-verbs)): pushes fill `free` slots in the middle of the
+ frame, and rsp's pin climbs to them.
+
+Tag: `six words from rsp`, or the range when scrolled (`rsp+20 to
+rsp+48`), and `· the frames they belong to`.
### backtrace
-`call` rows, newest on top, four and then a count. A panel of its own only
-in the `none` split, where there is room under the stack; in the others
-the stack's spans carry it.
+`call` rows, newest on top. A panel of its own in the `none` split, four
+and then a count, under the stack; the view panel of a [`calls`](#calls)
+lens, seven; in the other splits the stack's spans carry it.
### source
@@ -442,7 +503,7 @@ to 26 of 42`.
### disasm
Seventeen `insn`s in address order: the pc's, eight above, eight below.
-Eleven (five, the pc, five) when the lens is the subject.
+Nine (four, the pc, four) when the lens is the subject.
- Rows above the pc are the function's own instructions. Near its start
there are fewer, and the pc's row sits higher; the window stays full
@@ -454,37 +515,40 @@ Eleven (five, the pc, five) when the lens is the subject.
### lenses
-A lens is the band across the top of the stage: **a drawing, and beside
-it the pane the drawing is a view of.**
+A lens is the band across the top of the stage: **a drawing, over the
+program column, and over the state column the pane the drawing is a view
+of**, each a panel with its own tag. The gutter between them is the ties',
+as it is below. Beside the context both are 152 high; as the subject the
+drawing is 296 and its view 200 ([the frame](#5-the-frame)).
-| Lens | Drawing | Is a view of | Mock |
+| Lens | Drawing | Its view | Mock |
| --- | --- | --- | --- |
-| `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes, right half of the band | 9 to 11; 2 at camera scale |
-| `array` | cells, index tags, flights for a swap | a `hexdump` of the array's bytes, an element a run | 7 at camera scale |
+| `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes | 9 to 11; 2 at camera scale |
+| `array` | cells, index pins, flights for a swap | a `hexdump` of the array's bytes, an element a run | 7 at camera scale |
| `heap` | the heap to scale: chunks, bins | a `hexdump` of the chunk in hand | 4 at camera scale |
-| `calls` | a call tree, results on the shoulder | the `stack` panel: each node is a `call` span. The drawing has the band's whole width | 1 at camera scale |
-| `syscalls` | the crossing: vellum, the call decoded | the `registers` that carried it, by `echo`. Whole width | 3 at camera scale |
-| `pages` | the far view: pages, system calls over time | the mappings. Whole width | 8 |
+| `calls` | a call tree under its caller, results on the shoulder | the `backtrace`; each node is also a `call` span on the stack, tied by `project`. Subject only: a tree needs the height | 12; 1 at camera scale |
+| `syscalls` | the kernel's side, on vellum: the calls so far, the call decoded, the bytes it holds | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 3 at camera scale |
+| `pages` | the far view: pages, system calls over time | the mappings, a row each | 8 |
| `hexdump` alone | bytes and their text | itself | 5, in its first-pass form |
**What a new lens must provide** to fit the frame:
-1. A drawing that fits 856 by 116 (`beside`) and by 212 (`subject`), or
- twice the width where it is a view of the stack or the registers.
-2. The pane it is a view of, and for every element the bytes, slot or
- register it is drawn from.
+1. A drawing that fits 856 by 116 (`beside`) and by 260 (`subject`).
+2. Its view, a pane of rows that fits the state column (five beside,
+ seven as subject), and for every element the bytes, slot or register
+ it is drawn from.
3. A `place` for every element, so ties can land. A 12-unit lane clear at
- the top of the drawing and one at the bottom: **bytes arrive from
- above, pointers from below.**
+ the top of the drawing and one at the bottom: **bytes from its view
+ arrive from above; pointers, and a frame from the stack, from below.**
4. Each mark on its cells: `current`, `armed`, `struck`, `held`, `read`.
-5. Its `establish`: how its elements rise from what they are drawn from.
+5. Its `establish`: how its elements come in beside what they are drawn
+ from.
### nodes
-Boxes of 116 by 44, 28 apart: six fit the band's half (124 by 72, 22
-apart, as subject). The
-value's half is raised, the number in mono 25 (45); the pointer's half,
-48 wide, is the well, with a 10-unit square the arrow leaves from. Arrows
+Boxes of 116 by 44, 28 apart: six fit the drawing (124 by 72, 22 apart,
+as subject). The value's half is raised, the number in mono 25 (45); the
+pointer's half, 48 wide, is the well, with a 10-unit square the arrow leaves from. Arrows
3 wide in the ink of the region pointed into, head 12 by 10; null is a
dim slash. **Above** each node its address, in its region's ink: the same
digits as its row in the dump. **Under** it, its pins. Marks on a half:
@@ -493,11 +557,48 @@ digits as its row in the dump. **Under** it, its pins. Marks on a half:
### hexdump
`bytes` rows, sixteen a row, a window of the region kept round the rows
-the step touches: five beside, nine as subject. Rows in address order; a gap in the
-addresses is one row holding `more`'s three dots and the count of rows
-left out. Tag (the band's
-right half): `its bytes`, the range shown, and the legend of runs: each
-field's name in its bytes' ink, `malloc's`, `never read`.
+the step touches: five beside, seven as subject. Rows in address order;
+a gap in the addresses is one row holding `more`'s three dots and the
+count of rows left out. Tag: `its bytes`, the range shown, and the legend
+of runs: each field's name in its bytes' ink, `malloc's`, `never read`.
+
+### array
+
+Cells in a row, an element a cell (80 by 44 beside, 96 by 72 as subject),
+the index over each in faint, the variables that index it (`i`, `j`) as
+`under` pins. Its dump's runs are its element's type. A swap is two
+flights: each value lifts as a card (1.12 of the cell, 6 units off it),
+one flies over and one under, on an arc a quarter as high as it is long,
+34 at least and 120 at most, and never past the drawing's lanes: an arc
+that does not fit is lowered until it does. In flight a card is over the
+cells and under every name and pin, which stay legible through it.
+
+### calls
+
+The calls of one function as a tree under its caller, laid out for the
+whole run so that a node is where it will always be from the moment it
+appears: leaves in call order, a parent over the middle of its children.
+
+| Part | Drawn |
+| --- | --- |
+| node | a disc 48 across; its argument in mono 25 at its centre, primary |
+| levels | 46 apart, the root's centre 48 under the tag; leaves spread over the drawing's width (about 111 apart for eight) |
+| result | on its shoulder (12 right of the centre, 42 up): a square of 30 framed 2 in faint, the number in mono 25 primary; struck when the call returns |
+| edge | 3 wide, centre to centre, under the nodes; primary on the path of calls waiting, rule elsewhere |
+| the caller | `main`, a raised box 64 by 28 left of the root on its level, the name in mono 20; an edge into the root |
+
+States, as marks: `current` (the call running) is a gold disc, its
+argument bold in ink; waiting (it called, and waits) a page disc in a
+3-unit primary ring; done a raised disc; not yet made, nothing. The
+caller is a node too: gold until the first call, then waiting. So the
+band is never empty: before the first call it holds the caller, gold,
+with the backtrace beside it.
+
+Its view is the [`backtrace`](#backtrace): the waiting path read as rows,
+`#0` the gold node. Each node is also the `call` span of its frame on the
+stack, and the two are tied twice: by digits (`fib(4)` beside the span,
+`4` on the node) and, on the step that makes or ends the call, by a
+[`projection`](#4-ties) from the frame's return address to the node.
## 4. Ties
@@ -508,16 +609,30 @@ one pane a thing in another is.
| --- | --- | --- | --- | --- |
| `thread` | this line is these instructions, and the machine is here | the source's current line; every run of its instructions in the disassembly | standing; moves with the current mark | gold, 3 units: a `tie` bracket on the line, one on each run, a line in the left margin (x 54) between them |
| `link` | this register now points at that | the `reg` just struck; the row or node whose address it holds | for the step that set it | 3 units, in the ink of the region pointed into, head on the target; ends in the target's `pin` and leaves it behind |
-| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; the part of the drawing made of them | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket over the node's address; and the mark itself on the run and on the part |
+| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; or the return address of a frame made or ended, on the stack; the part of the drawing made of them (a node's address, a cell, a call's node) | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket at the part (over a node's address; under a call's node); and the mark itself on the run and on the part |
| `echo` | these are one event | the same mark at the same instant in two panels: the annotation's address and the dump's run | for that step | no line |
-| ink, digits | these are one thing | an address anywhere and its row, node or name | always | no line |
+| ink, digits | these are one thing | an address anywhere and its row, node or name; a call's arguments on its span, its backtrace row and its node | always | no line |
`call` spans and `pin`s are ties too, the kind that need no line because
they sit on their target.
+The calls lens needed no fifth tie: a frame's return address is the
+bytes the call left in memory, and the node is the part of the drawing
+made of them, which is what a projection says. A node and its frame are
+also tied by digits, standing, through the arguments on the span.
+
**Budget.** One `thread`, always. For a step, one `link` and one
`projection`. Never more than three drawn lines in the frame; a second
-pointer or a second run in the same step gets `echo` and pins.
+pointer or a second run in the same step gets `echo` and pins. rsp never
+takes a link: its pin is on the window's top row by construction.
+[`establish`](#6-verbs) draws no lines.
+
+**Off the window.** A link whose target is outside its panel's window (a
+slot past the stack's last row) comes down its lane to the panel's
+nearest row, turns into the pin lane and ends on the panel's rule: a
+head 9 by 12 pointing out of the panel, and beside it in faint mono 20
+how far the target is, `12 rows`. The pin is drawn when the window
+reaches it.
**Routes.** A tie runs only in channels, with corners of radius 8 (6 for a
projection):
@@ -525,18 +640,25 @@ projection):
| Channel | Carries |
| --- | --- |
| the left margin, x 54 | the thread |
-| the gutter's left lane, x 950 | a link, coming up from the registers |
-| the gutter's right lane, x 962 | a projection, from the dump |
-| a lens's bottom lane, 8 above its edge | a link, to the pin under its node |
-| a lens's top lane, 4 under its tag | a projection, to the bracket over its node's address |
+| the gutter's left lane, x 950 | what climbs into the band from the state column: a link from a register to a pin under a node; a projection from a frame's return address to its call node |
+| the gutter's right lane, x 962 | what keeps to its own height or goes down: a projection from the band's view to the drawing; a link from a register down to a slot |
+| a lens's bottom lane, 8 above its edge | what arrives from below: a link to the pin under its node; a projection to a call node |
+| a lens's top lane, 4 under its tag | a projection from the view, to the bracket over its node's address |
+| a panel's pin lane | a link's last leg to a `row` pin, or its stub |
-A link stays below a lens's nodes and a projection above them, and each
-has its own lane in the gutter, so the two cannot cross. A tie may cross
-a panel's rule; it never crosses a letter, a digit or another tie.
+Ties that climb from the state column take the left lane and arrive from
+below; the view's projections keep to the band in the right lane and
+arrive from above. A link down to a slot takes the right lane under the
+band and ends above the frame's return address, where a calls
+projection leaves for the left lane: so the ties of one step cannot
+cross. A tie may cross a panel's rule; it never crosses a letter, a digit
+or another tie. A projection climbing to a call node crosses no edge:
+under a node that has just been made there is only room for its own
+children.
**Order.** A tie arrives before the thing it points to reacts: see
[`link` and `project`](#6-verbs). Mock 9 shows the standing ties; 10 and
-11 all four.
+11 all four; 12 the projection to a call.
## 5. The frame
@@ -552,38 +674,61 @@ No data below 888: a player's controls cover it.
**The program column** (left): source over disassembly: what was written,
what runs. **The state column** (right): registers over stack: what they
-act on. **The lens band** (top, both columns): what it means, and the
-bytes that mean it. The split is the one thing about the layout a scene
-chooses.
+act on. **The lens band** (top): what it means, over the program column,
+and the pane that means it, over the state column. The split is the one
+thing about the layout a scene chooses.
-| Split | Band | Source | Disassembly | Registers | Stack | Backtrace |
-| --- | --- | --- | --- | --- | --- | --- |
-| `none` | | 14 lines, 48 to 416 | 17, 428 to 868 | 48 to 488 | 8, 500 to 724 | 4, 736 to 864 |
-| `beside` | 152, 48 to 200; dump of 5 | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack |
-| `subject` | 248, 48 to 296; dump of 9 | 10 lines, 308 to 580 | 11, 592 to 888 | 308 to 748 | 4, 760 to 888 | in the stack |
+| Split | Drawing | Its view | Source | Disassembly | Registers | Stack | Backtrace |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `none` | | | 14 lines, 48 to 416 | 17, 428 to 868 | 48 to 488 | 8, 500 to 724 | 4, 736 to 864 |
+| `beside` | 152, 48 to 200 | 152, 48 to 200: 5 rows | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack |
+| `subject` | 296, 48 to 344 | 200, 48 to 248: 7 rows | 10 lines, 356 to 628 | 9, 640 to 888 | 260 to 700 | 6, 712 to 888 | in the stack; the view of `calls` |
**What gave** for seventeen instructions: a lens, the whole of a function
and seventeen instructions do not fit one column of 840. So the lens left
the program column for a band of its own; the backtrace became spans on
the stack; the flags moved into rip's row; a panel's padding went from 6
to 4; and beside a lens the source shows eight lines. As the subject the
-lens takes six rows from the disassembly and four slots from the stack.
+drawing takes eight rows from the disassembly (seventeen to nine), the
+source gets two back, and the view stops two rows short of the drawing so
+that the stack keeps six slots: a small frame's locals, saved rbp and
+return address together. With a lens open the source is a window of
+eight or ten lines on the file, not all of it: the drawing's height is
+bought with the source's lines, and whether that is the trade rule 6
+allows is open.
| Of the frame | `none` | `beside` | `subject` |
| --- | --- | --- | --- |
| context | 68% | 56% | 48% |
-| lens band (drawing and bytes, half each) | | 13% | 21% |
+| lens band (the drawing and its view) | | 13% | 21% |
| caption band | 10% | 10% | 10% |
### clock and caption
- **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4
high, along it as far as the recording has run; `moment 72 of 95` in
- mono 20, faint, under its right end.
-- **`caption`**: one or two lines, Go 40 on 54, ranged left on the
- margin; code in it is mono 35. Hex in it is unbroken too.
+ mono 20, faint, under its right end. It says where the recording is, so
+ at a walk and a run it is still while a step plays: when the step's
+ mark has landed, the step's piece of gold fades in (12 f; 8 f at a run)
+ and the count changes as the fade starts. At a sprint the gold grows
+ with the recording, linearly, and is the one thing that says "fast".
+- **`caption`**: one or two lines of at most 64 characters, Go 40 on 54,
+ ranged left on the margin; code in it is mono 35. Hex in it is unbroken
+ too. What a scene author checks, characters counted as shown:
+
+ | Rule | Number |
+ | --- | --- |
+ | on screen, from arrived to leaving | at least 1.5 s + 0.06 s a character (90 f + 3.6 f) |
+ | on screen | at most 12 s; a longer stretch wants a second caption or a shorter scene |
+ | before the first step it describes fires | 60 f after it has arrived; 120 f for a scene's first |
+ | a scene's first | arrives at 1.0 s; the first step fires by 4.0 s |
+ | changes | only in a rest, never under a moving thing |
+ | longer than two lines | two captions, split at a phrase rest |
+ | the last | its reading time before the cut, and 2 s on the finished picture; the scene grows to fit |
+
- **`veil`**: the page at 50% over the panels a named beat does not
- touch; at 65% under the camera.
+ touch, and over what a pace cannot show ([`run`, `sprint`](#6-verbs));
+ at 65% under the camera. In over 18 f, out over 18 f.
- **`card`**: a title or the legend ([mock 6](mock/06-title-legend.png)).
The only frames with no context.
- **Camera rests**: x1 (the frame), x1.5 (1195 by 560: a column, or the
@@ -600,34 +745,37 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
| --- | --- | --- |
| `fire` | the current plaque | 0 to 12: it pulses once. Nothing else moves |
| `arm` | a value about to be written | s-12 to s: the `armed` frame, in over 2 f; the old value still in it |
-| `strike` | a value written | s to s+6 the fill comes in, linear; the new digits at s+3; s to s+12 its edges go out 3 units (4 in a lens's cell) and back, sine; solid to s+36 |
-| `cool` | a struck value | s+36 to s+60, `glide`: in the context to nothing, leaving `held` for three steps (then out over 36 f); in a lens's cell to its bar |
+| `strike` | a value written | s to s+6 the fill comes in, linear; the new digits at s+3; s to s+12 its edges go out 3 units (4 in a lens's cell) and back, sine; solid until the advance |
+| `cool` | a struck value | starts with the advance: 24 f, `glide`, in the context to nothing, leaving `held` for three steps (then out over 36 f); in a lens's cell to its bar. The digits go to their ordinary face at its middle |
| `read` | a value read | in over 6 f; held to the advance; out over 18 f. No arm, no pulse |
| `extend` | a chain whose first hop was struck | each later hop is followed again, 4 f apart, fading in over 6 f |
-| `link` | a `reg` just struck, and its target | s+6: the old pin fades (12 f) and the line draws from the register's row, head first, 24 f (36 f over 400 units), `standard`; the pin lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f |
-| `project` | a run read or struck, and its part of the drawing | on the run's mark: the bracket on the row (6 f), the line draws from the bytes to the drawing (18 f, `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`); out with the advance, 18 f |
-| `travel` | a value or a tag going from one place to another | 30 f to 200 units, 36 f to 400, 48 f beyond; `glide` |
+| `link` | a `reg` just struck, and its target | s+6: the old pin fades (12 f) and the line draws from the register's row, head first, 24 f (36 f over 400 units), `standard`, the pin riding its head; the pin lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f. A target out of the window: the line ends in its stub, and the pin waits for the window |
+| `project` | a run read or struck, and its part of the drawing | on the run's mark: the bracket on the row (6 f), the line draws from the bytes to the drawing (18 f; 30 f over 600 units; `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`; a new call's node fades in, 6 f); out with the advance, 18 f |
+| `travel` | a value, a card or a pin going from one place to another | `glide`. A value or card: 30 f to 200 units, 36 f to 400, 48 f beyond. A pin goes along its lane, 18 f after the strike that moved it: in a drawing 30 f to the next node or cell, 36 f to one farther; in the stack's lane 24 f to the next row and 2 f a further row, 36 f at most. A pin that comes fades in over 12 f rising 8 units; one that goes fades out over 12 f; a name joining or leaving a pin cross-fades over 12 f. On a `link` the pin rides the line's head instead. 8 f at a run; at a sprint only at a phrase's end |
| `advance` | the current marks | last. The thread, the plaques and rip move together: 12 f to an adjacent row, 24 f up to eight rows, `standard`; farther, out and in over 6 f. A taken jump's line draws in the jump lane with it |
-| `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`), the idea (the drawing, by `project`); each armed, then struck; hold 36 f after the last strike and 12 f a further value, 84 at most; `advance`; rest 24 f |
-| `run` | steps that need not be read | 18 f a step, no arm, marks jump; 24 steps at most |
-| `sprint` | steps to be got through | 4 f a step: only the current marks and the clock move. Each change of pace ramps at 0.6 of the step before |
-| `establish` | a scene's opening | the state column, then the program column, then the band: 60 f and 30 f a panel. A lens's dump first; then each element rises from its row by `project`, 6 f apart in address order, and the lines go, leaving the quiet brackets |
-| `scroll` | a `source` or `disasm` window | whole rows, 24 f, `glide`; marks ride with their rows |
-| `relayout` | a change of split | 48 f, `glide`; nothing else moves under it |
-| `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`; 120 f at most without a change; back |
-| `say` | the caption | out 12 f, gap 6 f, in 18 f; it leads what it describes by 60 f, 120 f at a scene's first |
+| `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`), the idea (the drawing, by `project`); each armed, then struck; hold 36 f after the last strike and 12 f a further value, 84 at most; `advance`; rest 24 f. A level with nothing on screen to change gives up its slot |
+| `run` | steps that need not be read | 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; values change with an ember, never a solid; no ties but the thread. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most |
+| `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before |
+| `establish` | a scene's opening | done by 54 f: the panels fade in, 18 f each, 6 f apart (registers, stack, source, disassembly, the band's view, the drawing's panel: 0 to 48); from 30 f the drawing's elements fade in rising 8 units, 12 f each, 2 f apart in address order and all begun by 42 f, each with its row's quiet bracket (an `echo`: no lines). The first caption arrives at 60 f |
+| `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows. A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before |
+| `relayout` | a change of split | the drawing fades out (12 f); every panel moves to its new box, clipped to the box as it moves (48 f, `glide`); the drawing fades in at its new size (12 f). Nothing else moves under it |
+| `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`. The panel's tag and whole rows in frame, the rows the visit's steps change in its middle third, never at its edge; a stack visited holds its window still. 120 f at most without a change; back |
+| `say` | the caption | out 12 f, gap 6 f, in 18 f; the numbers are under [caption](#clock-and-caption) |
A step is as long as its content: 0.8 s when only the line moves, 1.5 s
-for one register, 2.0 s for a register and memory, 2.5 s across three
-levels.
+for one register, 2.0 s for a register and memory, 3.0 s for a call and 3.1 s
+for a return across three levels, 2.7 s for a swap.
## Composition
**What may contain what.**
-- The stage holds the band and two columns. A column holds panels. A
- panel holds a tag and rows, or (a lens) a tag and a drawing. A row
- holds atoms. Nothing nests deeper.
+- The stage holds the band and two columns; the band is two panels, one
+ over each column. A column holds panels. A panel holds a tag and rows,
+ or (a lens) a tag and a drawing. A row holds atoms. Nothing nests
+ deeper.
+- Every panel shows the same moment. A register from one stop beside a
+ stack from another is a lie, however small.
- A mark sits on an atom or a row, never on a panel. A panel's only
states are `focus` and veiled.
- A tie sits over panels, in channels. It joins `place`s that blocks
@@ -659,10 +807,15 @@ levels.
- Two strikes landing in the same frame. Two writes of one step are 6 f
apart, in the order they happened.
- An effect before its cause: a drawing changing before its bytes, a
- current mark moving before the hold.
+ card lifting before its bytes are struck, a result stored before the
+ kernel returns it, a current mark moving before the hold.
+- A mark wider than what changed: bytes struck that kept their value.
+- A pin that jumps, two pins for one name, two names in one place.
- A space inside a number. A row that wraps. Rows that reorder.
- Anything hidden to make room: a row that cannot hold its chain ends in
- `more`, a panel that cannot hold its rows ends in a count.
+ `more`, a panel that cannot hold its rows ends in a count, a link whose
+ target is out of view ends in a stub and a count, a label cut short
+ ends in `…`.
- Mono under 20, sans under 18. Lines under 2 units. Dashes finer than 12
on 8 off.
- Alpha tints (but the veil), gradients, glow, grain, rounded panels.
@@ -671,21 +824,22 @@ levels.
## The mocks
-`mock/context.py` draws 9 to 11, one function a block under the block's
+`mock/context.py` draws 9 to 12, one function a block under the block's
name; `mock/gen.py` draws 1 to 8. Each has a `-480.png` beside it.
```sh
cd design/mock
-python3 context.py && for n in 09-context 10-context-step 11-context-lens; do
+python3 -B context.py && for n in 09-context 10-context-step 11-context-lens 12-calls-subject; do
resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done
-python3 gen.py # 1 to 8, then resvg the same way
+python3 -B gen.py # 1 to 8, then resvg the same way
```
| Mock | Is | Blocks it shows |
| --- | --- | --- |
-| [9](mock/09-context.png) | `beside`, at rest: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot`, `pin` row; `call` spans; `insn` current, ran, ahead, outside, with the jump lane; `line`; `bytes` with number, pointer, allocator, unread and `pad`; `nodes` with pins under; `thread`; marks current, held, trail |
-| [10](mock/10-context-step.png) | the same, mid-step | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection` |
-| [11](mock/11-context-lens.png) | `subject` | the band at 248, the drawing a size up, a dump of nine, eleven instructions, four slots |
+| [9](mock/09-context.png) | `beside`, at rest: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot`, `pin` row; `call` spans; `insn` current, ran, ahead, outside, with the jump lane; `line`; `bytes` with number, pointer, allocator, unread and `pad`; `nodes` with pins under, two names on one; `thread`; marks current, held, trail |
+| [10](mock/10-context-step.png) | the same, mid-step | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin, rax's name kept on its side; `projection` |
+| [11](mock/11-context-lens.png) | `subject` | the drawing 296 high and a size up, its view a dump of seven, nine instructions, six slots |
+| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments; `call` spans with arguments; the stack's window from rsp, six slots; a `projection` from the return address to the new node; `insn` with a call and its argument, a write, and operands of 27 characters whole |
| [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale |
| [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` |
| [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` |
@@ -701,24 +855,29 @@ the band.
**Specified, not drawn.**
-- The `none` split, and the `backtrace` panel with `call` rows.
-- `insn` annotations for a call with its arguments, a return, a memory
- write, a system call, `not taken`, a jump out of the window.
+- The `none` split, and the `backtrace` as a panel of its own.
+- `insn` annotations for a return, a system call, `not taken`, a jump out
+ of the window; operands giving way (none in 9 to 12 needs to).
- `value` classes other than digit, small number and string.
- `armed`, `fault`, `attention` and the veil in the context.
-- A `projection` for a write (vermilion). A `link` to a `slot`.
+- A `projection` from the dump for a write. A `link` to a `slot`, and its
+ stub off the window. A variable's pin.
+- The stack's window scrolled down a long frame, and held for a visit
+ with `free` slots.
- A struct wider than one `bytes` row; a gap in a dump; text in a dump.
-- `array`, `heap`, `calls`, `syscalls`, `pages` in the band.
+- `array`, `heap`, `syscalls`, `pages` in the band.
- `pin` with a count; `rwx`.
- Every verb: the mocks are stills. `establish`, `link` and `project`
have no chart from a render yet.
-**The data in 9 to 11** is the recording's: registers, chains, stack, the
-instructions and their lines. The frames' extents are read off the
-frame-pointer chain. The dump's node bytes are what the chains and the
-program say the heap holds; its allocator rows are glibc's layout, with
-the word nothing reads drawn as never read. A recording made under ptrace
-has seen neither.
+**The data in 9 to 12** is the recordings': registers, chains, stack, the
+instructions and their lines (12: `ztrace show` on
+`anim/zig-out/recordings/steps.ztrace`, lines from its binary by
+`addr2line`). The frames' extents are read off the frame-pointer chain.
+The dump's node bytes are what the chains and the program say the heap
+holds; its allocator rows are glibc's layout, with the word nothing reads
+drawn as never read. A recording made under ptrace has seen neither. The
+arguments on 12's spans and rows are the calls' own, from the tree.
**At 480 wide** no digit of the context reads. What is left: the layout,
the gold rows and the thread, the strike on `rdi` and its link into the
@@ -728,72 +887,108 @@ still read.
## What this asks of the renderer
-1. **Faces.** JetBrains Mono NL in four and Go in three; `theme.font.mono`
- is still Go Mono.
-2. **Places.** `ties.Place` has register, word, node, source and pc. The
- thread needs every run of the current line's instructions, not the pc
- alone; a projection needs a run of bytes in the dump and a *part* of a
- node (its value, its pointer half); a link needs the pin's place.
-3. **From the recording**:
- - the line of each instruction in the window, for the `line` column
- and the thread;
- - which instructions ran between two stops, for `ran` rows when
- stepping by line (or a recording by instruction);
- - each frame's extent on the stack, for `call` spans;
- - the bytes of a lens's region at each stop, so that allocator rows
- are read and not guessed; without it they are `unread`, honestly;
- - a callee's prototype, for the number of arguments under a call.
-4. **Runs.** Mock 10 is 351 runs of text, 174 rects and 63 paths. An
- address is one run now (two with `lead`).
-5. A camera rest at 1.5, with text shaped for mono 30 there.
-6. Still open from the first pass: dashed strokes from `sk.draw`.
+What the documents say and `anim/src` does not yet do, as read on 10
+November (`theme.zig` as of 15:30, the views as of 17:20; another round of
+renderer work was under way); the tokens are under
+[Token changes](#token-changes).
+
+1. **The band as two panels.** `layout.Split` gets a `view` beside
+ `band`: the drawing over the program column and its view over the
+ state column, each with its own tag (`the list`; `its bytes`, the
+ range, the legend of runs). `nodes` and `array` draw in `band` and
+ `hexdump` in `view`; `calls` draws the tree in `band` and the
+ `backtrace` in `view`; `syscalls` the kernel's side in `band` and the
+ buffer's dump in `view`. A `relayout` moves both boxes.
+2. **The `subject` split**: drawing 296 high, view 200 (seven rows),
+ source 10 at 356, disassembly 9 at 640, registers at 260, stack 6 at
+ 712. The test "the splits fill the stage" changes with it.
+3. **The stack's window** (`stack`): `[rsp, rbp+16)`; from rsp when the
+ frame fits, else scrolled by whole slots to keep the touched slot in
+ its middle rows, never above rsp; it slides with rsp at the memory
+ level, before the arm; held still under the camera, with `free`
+ slots. The tag's note follows the window. `lead` and the
+ disassembly's line numbers are computed from the rows on screen, on a
+ scroll's first frame (the glitch at fib 22.25 s). Spans carry their
+ arguments, `fib(4)`.
+4. **An instruction's room** (`insn`): operands whole; the annotation
+ from 564, or a character after them. `disasm.zig` already moves the
+ annotation right and cuts operands only for an annotation that needs
+ the room; new are the size word dropped before any cut, and a cut
+ never inside `[]`.
+5. **Runs and marks on bytes** (`bytes`): runs from the element's type
+ (sort's `int`s are runs of 4); a strike covers only the bytes whose
+ value changed.
+6. **Pins** (`pin`, `travel`): one pin a name, travelling on `time.pin`,
+ never popping; names keep their side; variables' pins from the debug
+ info, in the ink of where the variable lives, from the opening (list's
+ `head`, which is never drawn now).
+7. **Ties**: the calls projection, from a frame's return address up the
+ gutter's left lane and the drawing's bottom lane to a bracket under
+ the node, on a call (write) and on a return (read); a link down to a
+ slot in the right lane; a link's stub and count when its target is
+ out of the window; no link for rsp.
+8. **`calls`**: `metric.calls` (now local to `calls.zig`, and smaller);
+ the caller's node, gold before the first call; the backtrace as the
+ view, with arguments.
+9. **Fast passes** (`run`, `sprint`): registers, stack and disassembly
+ veiled from the first shortened step (in 18 f) to the last (out 18 f);
+ at a sprint the source and the view too; no link or projection at
+ either.
+10. **The clock**: still while a step plays at a walk or a run; the
+ step's gold fades in after its mark lands. The syscalls scene moves it
+ every frame now.
+11. **The opening and the captions**: `establish` done by 54 f, with no
+ lines; the first caption at 60 f; the first step by 240 f. A scene
+ whose caption is up for less than its reading time, or more than 12
+ s, or arrives less than 60 f before what it names, is wrong in a way
+ the build can tell: warn.
+12. **Order**: a system call's result stored only after `returns` has
+ the value (`syscalls.zig`'s `stored` already follows `returns`); a
+ swap's bytes struck, then the projection, then the cards; arcs lowered
+ into the drawing's lanes, cards under names and pins.
+13. **`relayout`**: the drawing fades out and in round the move; every
+ panel clipped to its box while it moves.
+14. **Labels**: flags as names or `0x` hex; a module's offset from its
+ first mapping (`list+402c89` reads as if the module began at 0); every
+ cut label ends in `…` (`set_tid_add`).
+15. **One moment**: every panel from the same stop (the syscalls scene's
+ registers are from inside the libc wrapper, its stack and rip from
+ `main`).
+16. **From the recording**: each call's arguments, for spans, backtrace
+ rows and nodes; the variables a scene names and where each lives.
## Token changes
-For `anim/src/theme.zig` as it stood when this was written. "Was" is what
-is in the file.
+Against `anim/src/theme.zig` as it is now (15:30): "In theme.zig" is what
+is in the file, "Is" what the documents say.
-| Token | Was | Is |
+| Token | In theme.zig | Is |
| --- | --- | --- |
-| `font.mono`, `mono_bold`, `mono_italic` | Go Mono | JetBrains Mono NL Regular, Bold, Italic |
-| `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: all mono under 30 |
-| `metric.context.pad` | 6 | 4 |
-| `metric.context.group_gap` | 6 | removed: hex is unbroken |
-| `metric.context.lead_alpha` | | 0.6: the shared digits of a column of addresses |
-| `metric.context.pad_alpha` | | 0.45: a word's padding bytes in a dump |
-| `layout.registers` | 18 rows | 17: the flags are in rip's row |
-| `layout.stack` | 8 | 8; 4 in `subject` |
-| `layout.backtrace` | 3, always | 4, in `none` only |
-| `layout.band` | | y 48, full width: 152 `beside`, 248 `subject` |
-| `layout.split.none` | source 14, disasm 17 | the same; registers, stack 8, backtrace 4 beside them |
-| `layout.split.beside` | lens 312 in the program column, source 8, disasm 10 | band 152; source 8, disasm 17; registers, stack 8 |
-| `layout.split.subject` | lens 432, source 5, disasm 8 | band 248; source 10, disasm 11; registers, stack 4 |
-| `layout.dump_rows` | | 5 `beside`, 9 `subject` |
-| `metric.insn` | | columns at 2, 31, 40, 134, 180, 264, 564; operands 24 characters, annotation 25 |
-| `metric.bytes` | | bracket 7, address 18, bytes from 132 on a pitch of 30 with 12 after the eighth, reading 640 |
-| `metric.slot` | | pin lane 10 to 112, chain 122, room to 136 from the right |
-| `metric.table.flag` | 60 by 36 | chip 32 by 20, pitch 42, ranged right in rip's row |
-| `metric.pin` | | `row`: head 9 by 12, 5 after the names; `under`: stub 3 wide, the mono size and 10 long, head 10 by 10, names 9 either side |
-| `metric.bracket` | | `quiet` 2 and 5; `tie` 3 and 6 (thread 7) |
-| `metric.plaque` | 40 high, pad 12 | gold only: 54 (rip), 50 (a line number), 24 (the pc) wide, the row high |
-| `metric.node` | 180 by 72, pointer 72 | 116 by 44, 28 apart; 124 by 72, 22 apart as subject; pointer half 48; origin 10 |
-| `metric.lens.lane` | | 4 under the tag (projections); 8 above the bottom edge (links) |
-| `metric.tie.thread_x` | | 54 |
-| `metric.tie.lanes` | | 950 (link), 962 (projection) |
-| `metric.tie.radius` | | 8; 6 for a projection |
-| `stroke.tie` | | thread 3, link 3, projection 2 |
-| `color.well` | | `101a48` |
-| `Role.pointer` | orchid frame and arrow | removed. `Role.link`: region ink, 3 wide |
-| `mark(.write)` held | ember and a 6-unit bar | in the context a tick, 4 wide; in a lens's cell a bar, 4 high |
-| `color.veil_alpha` | 0.65 | 0.50 for a beat; 0.65 under the camera |
-| `metric.max_rows` | 10 | removed: nothing is hidden |
-| `time.link` | draw 0.40, go 0.30 | draw 0.40 (0.60 over 400 units), settle 0.20, back 0.30 |
-| `time.project` | | bracket 0.10, draw 0.30, out 0.30 |
-| `time.establish_rise` | | 0.10 between a lens's elements |
-| `size.mono.value` | 35 | 35 in a caption; a subject lens's values are `flight`, 45 |
+| `layout.Split` | `band`, one rect across both columns | `band`, the drawing over the program column, and `view`, over the state column |
+| `layout.split.beside` | band 1792 by 152 | drawing 880 by 152; view 880 by 152, `dump_rows` 5; the rest as it is |
+| `layout.split.subject` | band 248; source 10 at 308, disasm 11 at 592; registers at 308, stack 4 at 760; `dump_rows` 9 | drawing 880 by 296; view 880 by 200, `dump_rows` 7; source 10 at 356, disasm 9 at 640; registers at 260, stack 6 at 712 |
+| `metric.insn.operand_chars` | 24 | removed: operands are whole |
+| `metric.insn.annotation_chars` | 25 | removed: the annotation is from 564 or a character after the operands; the row holds 50 characters from 264 |
+| `metric.calls` | none (`calls.zig`: radius 18, level 44, badge 24, pitch at most 81, digits mono 20 dim) | node 48 across, level 46, the root 48 under the tag, leaves spread over the drawing; badge 30, 12 right of the centre and 42 up, mono 25 primary; caller 64 by 28; edges 3 |
+| `metric.call_row` | none | `#n` 12 (gold plaque 40), name 60, arguments 384, file and line ranged right |
+| `metric.link_stub` | none | head 9 by 12 on the panel's rule; the count in faint mono 20, 6 past the head |
+| `time.pin` | none (`move` 0.40, `travel` 0.60 are used) | `after` 0.30; `node` 0.50, `nodes` 0.60; `row` 0.40 and `step_per_row` a further row, 0.60 at most; `in`, `out`, `names` 0.20; rising 8 |
+| `time.project.far` | none | 0.50, over 600 units |
+| `time.relayout_fade` | none | 0.20 before the move, 0.20 after |
+| `time.establish`, `establish_per_panel`, `establish_rise` | 1.00 + 0.50 a panel of stillness; 0.10 between elements | `establish` 0.90, everything on screen; a panel 0.30, 0.10 apart; elements `stagger` apart from 0.50, all begun by 0.70 |
+| `time.first_caption` | none | 1.00 |
+| `time.first_step` | none | 4.00 at the latest |
+| `time.caption_max` | none | 12.00 |
+| `time.clock` | none | the step's gold fades in over 0.20 (`run_ease` at a run) once the mark lands |
-Unchanged and already there: the palette, region inks, `time.cascade`,
-`strike`, `read`, `unroll`, `run`, `sprint`, `ramp`, the camera's scales.
+Unchanged and already there: the palette, region inks, the type sizes,
+`metric.bytes`, `metric.slot`, `metric.pin`, `metric.node`,
+`metric.tie` (the lanes keep 950 and 962; what each carries is now by
+direction, see [Routes](#4-ties)), `stroke.tie`, `color.veil_alpha`,
+`time.veil`, `time.strike` (`cool` 0.40 on `glide`, from the advance),
+`time.link`, `time.project`, `time.flight` (arc 0.25, 34 to 120),
+`time.caption` (1.5 + 0.06 a character), `caption_lead` and
+`caption_lead_first`, `time.run`, `sprint`, `ramp`, the camera's scales.
## Building it
@@ -813,5 +1008,5 @@ Export:
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
+ -g 600 -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4
```