diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 17:16:50 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 17:56:05 -0300 |
| commit | 74c45474f7e3e1b3539eb88484e6749082c6addf (patch) | |
| tree | 29be105369df0b9f5bb92adb50360fd99fd664b8 /design/README.md | |
| parent | 47f43f0f26b08901c1ddd16aacbe50c2c843ab8a (diff) | |
| download | computeranim-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.md | 571 |
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 ``` |
