diff options
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 585 |
1 files changed, 359 insertions, 226 deletions
diff --git a/design/README.md b/design/README.md index 71c1b81..c58dae2 100644 --- a/design/README.md +++ b/design/README.md @@ -11,7 +11,7 @@ scene that draws every block in every state is the test of this page. - The numbers are tokens in `anim/src/theme.zig`: [what to change there](#token-changes). - + ## The rules @@ -19,7 +19,7 @@ scene that draws every block in every state is the test of this page. execution is, vermilion for what just changed. 2. **Ink says what a thing is; paper says what happened to it.** The colour of a value's digits is where it points, or that it is a keyword or a - string. A fill, a frame, a tick beside it is an event. The two never + string. A fill, a frame, a turned corner is an event. The two never share a channel. 3. **Every mark has its own form.** Written is filled, read is framed, changed is ticked, freed is hollow, unknown is two dots. Nothing is told @@ -28,7 +28,7 @@ scene that draws every block in every state is the test of this page. 5. **Panels are acme windows.** A tag, a 2-unit rule, a body. Square corners, no shadows, no gradients, no glow. 6. **The whole context, always.** Every register followed as far as it - points, seventeen instructions round the pc, the source, the stack: in + points, the instructions round the pc, the source, the stack: in the same place in every frame, as pwndbg shows them. A lens (a list, a tree, an array) is drawn over that state and never instead of it. 7. **Panes are views of one machine, and the ties are drawn.** A source @@ -55,7 +55,7 @@ this table. | | [`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 | +| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop; opens a `loupe` | | | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) | | | [`slot`](#slot) | a word of the stack and its chain | pins; `free` | | | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` | @@ -67,34 +67,49 @@ this table. | | [`backtrace`](#backtrace) | the call chain as rows | in the `none` split; the view of `calls`; a lens's drawing | | | [`source`](#source) | a window on the file | 14, 8 or 10 lines | | | [`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 | typed or by `fields`; `more` rows; `seen`; `given` | +| | [`lens`](#lenses) | a drawing of some state over the program's two columns, and in the third the pane it is a view of | `beside`, `subject` | +| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `more` rows; `seen`; `given`; `memory` | +| | [`loupe`](#loupe) | the memory round a pointer's target, floating over the context | two at most, in depth | | | [`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`; 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` | +| 5 frame | [`stage`](#5-the-frame) | 3840 by 2160: the lens and four 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, 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 | | +| | [`open` `close`](#6-verbs) | what a loupe does | | | | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | ## 0. Tokens ### Grid -1920 by 1080 units; a 4K master is two pixels a unit, at 60 frames a second. +3840 by 2160 units, at 60 frames a second: the 4K master is a pixel a +unit, and 1440p and 1080p are its downscales. The context keeps its type +size (mono 20, rows of 24) and so holds four times what a 1920 stage held: +see [the frame](#5-the-frame). | Token | Value | | --- | --- | | context mono | 20: an advance of 12, rows of 24 | -| panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides | +| panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides. The last panel of a column runs to the stage's foot, less than a row of padding under its rows | | between panels | 12 | -| columns | two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties | -| strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames. 4: a tick | +| columns | four of 880, at x 112, 1024, 1936 and 2848; the gutters between them, 32 each, belong to the ties | +| strokes | 2: rules, frames, chain arrows. 3: a projection, a lens's frames at 1920 scale. 4: a link, the thread, a loupe's stem | + +**What reads where.** Mono 20 is 20 pixels at 4K, 13 at 1440p, 10 at +1080p. The context's code and digits read on a monitor from 1440p up, full +screen; at 1080p they are sharp on a still but not after a stream's +compression, and count as texture. So at 1080p the layout, the marks, the +ties, the lens's drawing and the caption carry the story, and anything the +narration needs read in the context is in the caption or under the camera +at x2, which shows a quarter of the stage at 1080p exactly as the 1920 +stage drew it. The caption, the clock's count and a lens's drawing are +drawn at twice the 1920 sizes for that reason. ### Colour @@ -109,6 +124,9 @@ this table. | dim | `9aa6d9` | 7.8 | register names, `loose` bytes, notes | | faint | `6a7ab8` | 4.5 | chain arrows, line numbers, a decimal beside its hex | | ink | `050a24` | | letters on a solid mark | +| wash | `212644` | 1.2 | the current row's band: bright a tenth of the way over the page, opaque | +| lift | `121c52` | 1.2 | a loupe's surface; its tag `22317a` | +| shade | `02061a` | | a loupe's shadow, the one shadow there is | **Regions: the ink of an address**, as pwndbg colours them. The legend is the registers' tag, always on screen. @@ -131,8 +149,8 @@ name; heap and data have only their digits. | Role | Solid | Ember | | --- | --- | --- | -| current | gold `e8c46a` | `4a3d1c`; trail `ae9350`, `746235`, `463b20` | -| write | vermilion `ff6a4a` | `5a2218` | +| current | gold `e8c46a`, on the plaque only; the row's band is `wash` | trail `ae9350`, `746235`, `463b20` | +| write | vermilion `ff6a4a`, for the arm, the turned corner, a projection; a strike's paper `b54f42` (vermilion 70% over the page), its digits bright | `5a2218` | | read | `6fd6e6` | `1c4652` | | allocated | `7fdc9a` | `1f4a33` | | kernel | vellum `eee6d2` | | @@ -159,17 +177,19 @@ stream. OFL and BSD; `/usr/share/fonts/TTF/`, `/usr/share/fonts/go/`. | Mono | Advance | For | | --- | --- | --- | -| **20** | 12 | the context, the dump, a lens beside | -| 25 | 15 | a lens's values; its labels and pins as subject | -| 30 | 18 | the context under the camera at x1.5 | -| 35 | 21 | code inside a caption | -| 45 | 27 | a subject lens's values; a value in flight | -| 60 | 36 | a title card | +| **20** | 12 | the context, the dumps, a loupe | +| 40 | 24 | the clock's count; a lens's labels and pins beside | +| 50 | 30 | a lens's values beside; its labels and pins as subject | +| 70 | 42 | code inside a caption | +| 90 | 54 | a subject lens's values; a value in flight | +| 120 | 72 | a title card | -Sans: 18 notes and legends, 20 tags, 40 on 54 the caption, 44 and 116 a -card. **Floor: mono 20, sans 18.** At 480p no digit at 20 can be trusted, -so: **nothing the narration depends on is only at 20.** It is also in the -caption at 35, or the camera goes to it. +A lens's drawing is specified below at the 1920 sizes (`nodes` 124 by 72, +values 45) and drawn twice that on the 4K stage; so are its strokes, lanes +and flights. Sans: 18 notes and legends, 20 tags, 80 on 108 the caption, 88 +and 232 a card. **Floor: mono 20, sans 18,** in 4K units: 10 and 9 pixels +at 1080p. **Nothing the narration depends on is only at 20:** it is also in +the caption at 70, or the camera goes to it. ## 1. Atoms @@ -185,7 +205,7 @@ Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros: | `rwx` | a 2-unit underline | States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each -side); `read` (a 2-unit frame, 6 out); `held` (a tick at its left). Data: +side); `read` (a 2-unit frame, 6 out); `held` (a turned corner at its top left). Data: a word and the mapping it lies in. Mocks 9 to 11, everywhere. ### value @@ -252,10 +272,10 @@ What happened, on paper and never in the letters. | State | In the context (mono 20) | In a lens's cell | | --- | --- | --- | -| `current` | a gold plaque on the label, gold ember across the row | the same | +| `current` | a gold plaque on the label, and across the row a white wash (`wash`) | the same | | `armed` | a 2-unit vermilion frame, the old value still in it | 3 units | -| `struck` | solid vermilion behind the value; digits bold, in ink | solid fill | -| `held` | a vermilion tick, 4 wide, the row less 6 tall, at the value's left, for three steps | a vermilion bar, 4 high, along the cell's bottom edge | +| `struck` | the softened vermilion (`b54f42`) behind the value, 5 out each side; digits bold, bright | the same, the cell's fill | +| `held` | a turned corner: a vermilion triangle 9 on its sides at the value's top left, for three steps | the same at the cell's top left, 12 (24 on the 4K stage) | | `read` | a 2-unit frame in read's colour, no fill | 2 units, 2 out | | `trail` | a 4-unit bar at the row's left edge: three tones, newest first | | | `allocated` | | ember block in a solid frame | @@ -265,8 +285,18 @@ What happened, on paper and never in the letters. | `unknown` | two dots | two dots | | `kernel` | the ground is solid vellum | the same | -One gold mark a panel. One step's writes in vermilion at a time. Mocks 9 -and 10 show current, struck, held, read, trail, unknown; 1 to 8 the rest. +One gold mark a panel. One step's writes in vermilion at a time. Gold is +kept for the plaque, the pc's marker, rip's name, the thread and the +trail: where execution is, as a sign and not as a band. + +The first videos drew `current` as a gold ember across the row, `struck` +as solid vermilion with ink digits, and `held` as a tick left of the +value: the band was the strongest thing in a dense frame, the solid strike +glared, and the tick read as a text cursor. [Mock 15](mock/15-marks.png) +sets those (A) beside these (B) and a whiter reading (C: a white plaque, a +white strike framed in vermilion, a bar under the held value) on the same +rows. Mocks 9 to 18 show current, struck, held, read, trail, unknown; 1 to +8 the rest. ### plaque @@ -339,7 +369,7 @@ its far end and says so. is taken from the middle. - **Marks** are per hop. If the first is struck the register was written and the rest are followed again ([`extend`](#6-verbs)); if a later one, - memory changed under a pointer that did not, and the tick sits before + memory changed under a pointer that did not, and the turned corner sits on that hop alone. - No lines to targets. Thirty chains would be a net; a chain is tied to its target by ink, by digits, and by the target's pin. @@ -348,21 +378,29 @@ its far end and says so. A name (dim) 12 in; its chain from 72; room to 12 from the edge. -`rip`: gold plaque on the name, ember across, the address in code's ink +`rip`: gold plaque on the name, the wash across, the address in code's ink and its name. Never struck. Its row carries **flags** at the right end: eight names on a pitch of 42. Set: upper case on a chip. Clear: lower -case, dim. Changed: a tick. (The value `0x206` is not drawn: the names are +case, dim. Changed: a turned corner. (The value `0x206` is not drawn: the names are the value.) ### slot -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. A span's name is never -cut for a chain: on the rows its name sits on (one, or the two it -straddles), the chain's room ends 12 before the name begins, and the -chain is cut there by its own rule (`sqlite3BtreeInsert` beside -`7fffffffe980 → 7fffffffeb90 → 7fffffffec60 → …`). +A word of the stack, pwndbg's way and a little more. + +| x | Column | | +| --- | --- | --- | +| 10 | pins | the `row` pin's lane, to 112: every register whose value is this word's address | +| 172 | offset | from rsp, hex, `+18`, faint, ranged right in four characters (`-8` above rsp) | +| 184 | address | stack ink, `lead`; then the chain, its first hop the word's content | +| right | role | what the word is, where the recording knows it, ranged right where the chain's room ends: `saved rbp`, `saved rbx` (dim); a local's name (primary); at the process's start `argc`, `argv[0]`, `argv end`, `envp end`, `auxv` (dim) | +| 14 from the right | span | the [`call`](#call) bracket, its name left of it | + +A return address needs no word: its chain is code, named (`10018b0 +main+80`), and its frame's bracket ends on it. Room runs out from the +right: a span's name is never cut, a role is never cut, and the chain on +the rows they sit on ends 12 before them, cut by its own rule +(`sqlite3BtreeInsert` beside `7fffffffe980 → 7fffffffeb90 → …`). `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 @@ -396,10 +434,10 @@ whole annotation do not fit, in this order: | State | Draws | | --- | --- | -| `current` | plaque, ember across; annotation in full ink | +| `current` | plaque, the wash across; annotation in full ink | | `ran` | trail bar, newest of three brightest; keeps the annotation of what it did | | `ahead` | plain; only static annotation (a callee's name) | -| `outside` | past the function's end: a rule above the row, everything faint, the next symbol's name in the annotation column | +| `outside` | another function's: plain, as `ahead`; over its first row a rule, and its name in that row's annotation column, dim. Past the program's text (padding, a section's end): faint | **The annotation**, by what the instruction does: @@ -422,7 +460,7 @@ syscall annotations are not drawn. The number ranged right in three characters, faint; the text from 64, in the four code inks; 67 characters, then a faint `…`. `current`: gold -plaque on the number, ember across. `trail`: the bar, for the last three +plaque on the number, the wash across. `trail`: the bar, for the last three other lines run. **Wide numbers.** The number column is as wide as the program's largest @@ -466,7 +504,7 @@ 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 +read. `held` is a turned corner at the top left of what was struck. A struct wider than a row spans rows, and its bracket spans them. ### call @@ -500,38 +538,40 @@ moment's registers and mappings. ### stack -`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). +`slot`s, low addresses on top, a column of its own the stage's height: +69 words, 552 bytes, in every split. `call` spans down its right edge for +every frame in view: the backtrace, drawn on the words that are each +frame. rsp and rbp are pins in its lane. Reads the stack words, each +frame's extent (the frame-pointer chain, or the unwinder's CFA), and for +the roles the saved registers (the frame-pointer chain; the call frame +information for the prologue's pushes), the locals' names and places (the +debug info at the pc), and the first stack pointer (argc, argv, envp, +auxv). -**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. +**The window** begins at rsp, and a small program's whole stack is in it: +its frames, main's, libc's, and the process's start. Where the newest +frame `[rsp, rbp+16)` is longer than the window, it scrolls down it by +whole slots ([`scroll`](#6-verbs)) to keep the slot a step touches in its +middle third, and stays there until a step touches a slot outside it; its +top never passes above rsp. -- 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. A window going farther than six slots (eight beside) fades - through instead ([`scroll`](#6-verbs)). + armed. A window going farther than its height fades through instead + ([`scroll`](#6-verbs)). - 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`. +Tag: `69 words from rsp`, or the range when scrolled (`rsp+20 to +rsp+240`), and `· the frames they belong to`. ### backtrace -`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; the drawing of a [`backtrace` lens](#lenses), eleven as -subject and five beside; in the other splits the stack's spans carry it. +`call` rows, newest on top: sixteen, under the registers, in every split; +the view of a [`calls`](#calls) lens (32, and the panel under the +registers is then `memory`); the drawing of a [`backtrace` +lens](#lenses), as long as the drawing is high. More frames than rows: the oldest go, and the tag's note counts them, `newest on top · 2 more`. @@ -545,33 +585,38 @@ identity: the slide is what says it is the same frame. ### source A window on the whole file, scrolled by whole lines to keep the current -line in its middle third. Fourteen lines; eight beside a lens (the loop -in hand); ten when the lens is the subject. Tag: the file, and `lines 19 -to 26 of 42`. A line farther than a window away (another function in a +line in its middle third: 69 lines in `none`, 56 beside a lens, 43 as its +subject; a file shorter than that is whole, the rows under its end empty. +Tag: the file, and `lines 19 to 61 of 262899`, or `lines 1 to 42 of 42`. A line farther than a window away (another function in a file of 262 899 lines) is not scrolled to: the window fades through ([`scroll`](#6-verbs)). Line numbers are as wide as the program's largest ([`line`](#line)). ### disasm -Seventeen `insn`s in address order: the pc's, eight above, eight below. -Nine (four, the pc, four) when the lens is the subject. +`insn`s in address order, a column's height: 69 rows in `none`, 56 +beside a lens, 43 as its 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 - from below. -- Past the function's end the rows are `outside`. +- The pc's row is in the window's middle third; the window is the + function's and as much of its neighbours as fits, above and below. At + this length a small function is whole, and its callers and callees + around it are context, not noise: they are `outside`, plain, each under + a rule and its name. +- The window moves only when the pc leaves its middle third, by whole + rows ([`scroll`](#6-verbs)), or fades through when the new pc is + farther than the window's height. - The rows that ran in the last three steps are `ran`, above or below the pc: with the jump lane they show how control came here. - Tag: the function's name. ### lenses -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)). +A lens is **a drawing, over the program's two columns, and in the third +column, beside it, 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. The +drawing is 300 high beside the context and 604 as its subject, and drawn +at twice the 1920 sizes given here; the view is 32 rows in both ([the +frame](#5-the-frame)). | Lens | Drawing | Its view | Mock | | --- | --- | --- | --- | @@ -584,6 +629,11 @@ drawing is 296 and its view 200 ([the frame](#5-the-frame)). | `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 | +`memory`, in the `none` split, is the third panel of the third column (32 +rows): a `hexdump` of the region the step touches, kept round what it +reads or writes, typed where the recording types it; with a lens, the +lens's view is this. + A scene may change its lens where it stands: the drawing fades out (12 f), then the next fades in (12 f) and its elements come in as at `establish`; a view the two share stays. The split does not move, so this @@ -592,10 +642,10 @@ row reaches `pwrite64`. **What a new lens must provide** to fit the frame: -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. +1. A drawing that fits 880 by 132 (`beside`) and by 284 (`subject`) at + the 1920 sizes, to be drawn twice that over the program's columns. +2. Its view, a pane of 32 rows that fits a column, 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 from its view arrive from above; pointers, and a frame from the stack, from below.** @@ -616,7 +666,8 @@ 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, seven as subject. Rows in address order. +the step touches: 32, 512 bytes, as a lens's view and as `memory`; nine in +a [`loupe`](#loupe). Rows in address order. Tag: `its bytes`, then what the bytes are and where (`the heap, 28b41050 to 28b410bf`; `pBuf: page 2 of t.db, at rsi`), and the legend of runs: each field's name in its bytes' ink, `malloc's`, `never read`. @@ -692,7 +743,8 @@ 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. +[`projection`](#4-ties) from the frame's row in the backtrace, the view, +to the node. **A larger tree.** The leaves share the drawing's width less the caller's box: about 680 units between the first leaf's centre and the last's. A @@ -742,6 +794,45 @@ A **crossing** is a step that makes one system call; its timetable is a crossing: the list takes them, oldest first, 2 f apart, each fading in; the newest is decoded; no arrow, no bytes. +### loupe + +The telescope's other form. A `chain` on a row says, flat, `rdi → +1004070 ◂ 9`; a **loupe** opens the place it points to: a panel floating +over the context with the memory round the target, the pointed thing +framed, read by its type where the recording has one. A pointer in it can +open the next, and a chain becomes panels in depth. + +| Part | Drawn | +| --- | --- | +| panel | 880 wide, a tag and nine `bytes` rows: the target's row in the middle, four before and four after (144 bytes), its runs typed (a node's value and next, malloc's words) or by `fields` | +| tag | `rdi → 1004070`, mono 20, the pointer it opens from and the target in its region's ink; ranged right, the region and the type, `heap · struct node, 16 bytes`, Go 18 dim | +| target | its run or its struct framed as `attention`: 2 units, bright | +| lift | its surface `lift` (`121c52`), its tag `22317a`, a 2-unit `dim` frame, and under it a solid shadow (`shade`) 12 right and 16 down; a loupe opened from a loupe, 20 and 26. This is the one place in canim with elevation: a loupe is not a panel of the frame but held over it | +| stem | the tie from the pointer to the loupe: a `link` (4 units, the target's region ink, head 12 on the loupe's tag), leaving the pointer where its row has room after the chain, or from a 3-unit bracket under a pointer inside a loupe | + +**Where it floats.** Beside what it opens from, its tag level with the +pointer's row: from the registers over the stack's column, from the stack +over the registers', from the disassembly or a dump over the column on its +right; a loupe opened from a loupe 120 to the right and just under the +pointer it opens from, over the older loupe's lower rows. It never covers +its own pointer, the current marks (the pc's row, the current line, +rip's row), the ends of a drawn tie, or a row the step changes; where the +first place would, it takes the other side, then the place under its +pointer; and it stays inside the stage. + +**How many.** Two at most. A third, followed from the second, closes the +first as it opens, so a chain of any length is walked two loupes at a +time. While two are open their stems are two of the frame's three lines +(the thread is the third): that step draws no other link and no +projection. + +**When the flat chain is right.** Always, as the standing form: every +register, slot and annotation keeps its chain, and a loupe never replaces +one. A loupe opens on a beat the narration names (a pointer followed, a +struct handed to a call) for a step or two; not at a run or a sprint; not +where the recording holds less than its nine rows round the target. It +opens and closes by its verbs ([`open`, `close`](#6-verbs)). Mock 18. + ## 4. Ties The panes are one machine at different levels. A tie says which thing in @@ -749,9 +840,9 @@ one pane a thing in another is. | Tie | Says | Between | When | Form | | --- | --- | --- | --- | --- | -| `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 | +| `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, 4 units: a `tie` bracket on the line at the source's right edge, one on each run at the disassembly's left, and between them a line down the gutter (x 1008), the two side by side | | `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; 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 | +| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; or the backtrace row of a frame made or ended (a `calls` lens's view); 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; a call's arguments on its span, its backtrace row and its node | always | no line | @@ -764,9 +855,10 @@ 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. rsp never -takes a link: its pin is on the window's top row by construction. +`projection`, or the stems of two [`loupe`s](#loupe) (a stem is a link). +Never more than three drawn lines in the frame; a second 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 @@ -777,85 +869,87 @@ 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): +projection). On the 4K stage the four columns leave three gutters: | Channel | Carries | | --- | --- | -| the left margin, x 54 | the thread | -| 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 | +| the gutter between source and disassembly, x 1008 | the thread | +| the gutter between the program and the third column, left lane x 1912 | a link from a register up to the pin under a node: it leaves the register's row at its left, climbs, and turns into the drawing's bottom lane | +| the same gutter, right lane x 1924 | a projection from the view to the drawing: it leaves the view's row at its left and climbs to the drawing's top lane, or for a call's node goes down to its bottom lane | +| the gutter between the third column and the stack, x 2832 | a link from a register to a slot: it leaves the register's row at its right edge and enters the slot's pin lane | | 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 | +| none | a loupe's stem: from its pointer straight to the loupe, over the row's empty end or the gap between a loupe's row and the loupe it opens | -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 +Ties into the drawing keep to the gutter beside it, links in the left lane +arriving from below, projections in the right lane; links to the stack +keep to the gutter beside the stack: so the ties of one step cannot cross. +A calls lens's projection leaves the frame's row in the backtrace, its +view (the frame the return address made), not the stack's slot, which is +two columns away. 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; 12 the projection to a call. +[`link` and `project`](#6-verbs). Mocks 16 to 18 show the ties on the 4K +stage: the thread across its gutter, a link and a projection, two stems. ## 5. The frame +The stage is 3840 by 2160 units, the 4K master's pixels. + | Band | y | | | --- | --- | --- | -| margin | 0 to 48 | page | -| stage | 48 to 888 | 840: the lens band and the two columns | -| clock | 898 to 902 | | -| caption | 912 to 1032 | | -| margin | 1032 to 1080 | page | +| margin | 0 to 96 | page | +| stage | 96 to 1784 | 1688, a panel of 69 rows: the lens and four columns | +| clock | 1796 to 1804 | | +| caption | 1824 to 2064 | | +| margin | 2064 to 2160 | page | -No data below 888: a player's controls cover it. +No data below 1784: a player's controls cover it. Sides: 112. -**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): 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. +**Four columns of 880**, at x 112, 1024, 1936 and 2848, 32 apart. **A**, +the source, and **B**, the disassembly, side by side: what was written, +what runs, the thread between them in their gutter. **C**: the registers, +the backtrace, and `memory` (or a lens's view). **D**: the stack, the +stage's height. **The lens**: its drawing over A and B, its view in C. The +split is the one thing about the layout a scene chooses, and it changes +only how high the drawing is. -| 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` | +| Split | Drawing (A and B) | Source (A) | Disassembly (B) | C | Stack (D) | +| --- | --- | --- | --- | --- | --- | +| `none` | | 69 lines, 96 to 1784 | 69 rows | registers 96 to 536; backtrace 16, 548 to 964; `memory` 32, 976 to 1784 | 69 slots, 96 to 1784 | +| `beside` | 1792 by 300, 96 to 396 | 56 lines, 408 to 1784 | 56 rows | the view 32, 96 to 896; registers 908 to 1348; backtrace 16, 1360 to 1784 | 69 slots | +| `subject` | 1792 by 604, 96 to 700 | 43 lines, 712 to 1784 | 43 rows | as `beside` | 69 slots | -**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 -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. +Against the 1920 stage: source 14, 8, 10 lines became 69, 56, 43; +instructions 17, 17, 9 became 69, 56, 43; the stack's 8, 8, 6 slots 69; +a dump's 5 or 7 rows 32. **What it costs**: the context's text is 10 +pixels at 1080p, where it is texture (see [the grid](#grid)); the camera +at x2 is how a 1080p viewer reads it, and the caption, the clock and the +lens's drawing are twice their 1920 sizes so that they read anywhere. A +file of more than 69 lines, and with a lens open any file, is still a +window: the trade with rule 6 stands, at four times the window. | Of the frame | `none` | `beside` | `subject` | | --- | --- | --- | --- | -| context | 68% | 56% | 48% | -| lens band (the drawing and its view) | | 13% | 21% | +| context | 72% | 56% | 50% | +| lens (the drawing and its view) | | 15% | 22% | | caption band | 10% | 10% | 10% | ### clock and caption -- **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4 +- **`clock`**: a 4-unit rule the width of the stage at y 1798; gold, 8 high, along it as far as the recording has run; `moment 72 of 95` in - mono 20, faint, under its right end. It says where the recording is, so + mono 40, 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 +- **`caption`**: one or two lines of at most 64 characters, Go 80 on 108, + ranged left on the margin; code in it is mono 70. Hex in it is unbroken too. What a scene author checks, characters counted as shown: | Rule | Number | @@ -873,9 +967,11 @@ allows is open. 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 - band), x2 (896 by 420: sixteen rows), x4 (448 by 210: one chain). It is - for reading, and always comes back. +- **Camera rests**: x1 (the frame), x1.5 (2560 by 1440: three columns' + upper half, or the lens), x2 (1920 by 1080: two columns, 45 rows, at + 1080p exactly the 1920 stage's density), x4 (960 by 540: one column's 20 + rows). It is for reading, and always comes back: on the 4K stage it is + also how a small screen reads the context. ## 6. Verbs @@ -888,12 +984,14 @@ 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 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 | +| `cool` | a struck value | starts with the advance: 24 f, `glide`, the paper to nothing, and the turned corner of `held` fades in over its last 6 f, for three steps (then out over 36 f); the same in a lens's cell. 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 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 | +| `open` | a loupe, from a pointer | the pointer's hop framed `read` (6 f); the stem draws from it to the loupe's place, head first, 18 f (30 f over 600 units), `standard`; the loupe rises with the stem's head: it fades in over 12 f from 8 units lower, its shadow growing from nothing to its offset (18 f, `standard`); the target's bright frame lands 6 f after. From a pointer inside a loupe the same, over it, and a third closes the first as it starts. In the slot of the level that read the pointer, or on a beat the caption names | +| `close` | a loupe | the deepest first: its stem draws back into its pointer (12 f) and the loupe sinks, fading out over 12 f as it falls 8 units and its shadow shrinks; with the advance of the step after the one it opened in, unless the narration holds it; 120 f at most without a change | | `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. A level with nothing on screen to change gives up its slot | | `continue` | a stop far from the last: a breakpoint, not a step | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change | @@ -913,8 +1011,9 @@ for a return across three levels, 2.7 s for a swap. **What may contain what.** -- 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, +- The stage holds the lens and four columns; the lens is two panels, its + drawing over the first two columns and its view in the third. 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 @@ -971,13 +1070,19 @@ for a return across three levels, 2.7 s for a swap. ## The mocks `mock/context.py` draws 9 to 14, one function a block under the block's -name; `mock/gen.py` draws 1 to 8. Each has a `-480.png` beside it. +name; `mock/dense.py` places those blocks on the 4K stage and draws 15 to +18; `mock/gen.py` draws 1 to 8. Look at 15 to 18 at full size: they are the +4K master's pixels. 9 to 14 were drawn on the 1920 stage, before the 4K +one: their blocks and marks are the catalogue's, their layout is not (two +columns; the calls tie from the stack), and the camera at x2 is the +nearest thing to them now. ```sh cd design/mock python3 -B context.py && for n in 09-context 10-context-step 11-context-lens 12-calls-subject \ 13-sqlite-row 14-sqlite-page; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done +python3 -B dense.py && for n in 15-marks 16-none 17-subject 18-loupes; do resvg $n.svg $n.png; done python3 -B gen.py # 1 to 8, then resvg the same way ``` @@ -989,6 +1094,10 @@ python3 -B gen.py # 1 to 8, then resvg the same way | [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 | | [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in | | [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the kernel's side in the band; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed | +| [15](mock/15-marks.png) | the marks sheet: `current`, `struck`, `held` as A (the first videos), B (the catalogue's) and C (a whiter reading), on rows of the list at the load and the store after it | the source's current line; the pc's row; rip; a struck and two held registers; a dump row struck on the one byte that changed and one held; a lens's cell held and struck; the same rows at 1.35 times | +| [16](mock/16-none.png) | `none` on the 4K stage, at rest: `targets/list` stopped at the load in `reverse` (a fresh recording, `mock/list-dbg.txt`) | four columns: 69 lines of source (the file whole), 69 instructions (`reverse` and its neighbours `outside`, under rules and names), the registers, the backtrace, `memory` of the heap by its words, the stack's 69 slots with offsets, roles and the spans of five frames down to the process's start; the thread across its gutter | +| [17](mock/17-subject.png) | `subject` on the 4K stage, mid-step: the load done | the list drawn twice the size over A and B; its view of 32 rows with the fieldless rows folded into `more`; 43 lines and 43 instructions; a link from rdi to its pin and a projection from the view; struck, held and current as B | +| [18](mock/18-loupes.png) | `none` on the 4K stage, mid-step, two loupes open | a `loupe` from rdi floating over the stack's column, its node framed; a second from that node's `next`, deeper, over the first's lower rows; their stems; the read in `memory` by `echo` | | [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` | @@ -1016,6 +1125,9 @@ the band. at stop 167, before the kernel took it). - A calls tree small or folded. - `array`, `heap`, `pages` in the band. +- A loupe opened from the stack, the disassembly or a dump; a loupe typed + by `fields`; a third closing the first. +- A local's name as a slot's role (the recording has none at these pcs). - `pin` with a count; `rwx`. - Every verb: the mocks are stills. `establish`, `link` and `project` have no chart from a render yet. @@ -1041,102 +1153,120 @@ still read. ## What this asks of the renderer What the documents say and `anim/src` does not do, as read on 10 November -after the sqlite scene (`theme.zig` as of 18:00, the views as of 20:18); -the tokens are under [Token changes](#token-changes). The first five are -wrong by the language, not merely unnamed. +(`theme.zig` as of 21:15); the tokens are under [Token changes](#token-changes). +Last round's `continue` and crossing stand as specified. + +1. **The 4K stage.** The design unit becomes the 4K master's pixel: + `canvas` 3840 by 2160, the stage 3616 by 1688 at (112, 96), the clock at + 1798, the caption band 1824 to 2064. Export at 3840 by 2160 natively + (`ui.scale` maps 1920 units to the scene now); 1440p and 1080p are + downscales of it (lanczos), never renders of their own. +2. **Four columns** (`layout`): source, disassembly, a third column + (registers, backtrace, `memory` or a lens's view), the stack; the + splits as [the frame's table](#5-the-frame): `Split` gains `memory`, + the view moves into the third column, the stack runs the stage's height + (69), `dump_rows` 32. The test "the splits fill the stage" changes with + it; a column's last panel runs to the stage's foot. +3. **The thread across a gutter**: the source and the disassembly are side + by side; the thread's brackets at the source's right edge and the + disassembly's left, its line down x 1008. +4. **Ties in three gutters** ([Routes](#4-ties)): links into the drawing at + 1912, projections from the view at 1924, links to the stack at 2832; a + calls lens's projection leaves the backtrace row (its view), not the + stack's slot. +5. **A lens's drawing twice the size**: nodes, cells, the calls tree, the + kernel's side, their labels, strokes, lanes and flights at twice the + 1920 numbers (`drawing_scale` 2), over the program's two columns. +6. **The slot's columns** ([`slot`](#slot)): pins 10 to 112, the offset + from rsp ranged right to 172, the address from 184, the role ranged + right where the chain's room ends; spans for every frame in view. +7. **The disassembly's window**: 69, 56 or 43 rows with the pc in its middle + third and the neighbouring functions `outside`, plain, under a rule and + their name; fade through beyond the window's height. +8. **`memory`** in `none`, and every dump 32 rows, its rows that hold no + field always folded into `more` (now only when the region is longer + than the window). +9. **Marks** ([`mark`](#mark)): `current` a white wash across the row + (`212644`) and the gold plaque; `struck` on `b54f42` with bright bold + digits (the arm, a projection and the corner stay full vermilion); + `held` a turned corner, a vermilion right triangle 9 on its sides at + the value's top left (12, at the drawing's scale, on a cell). The tick + and the bar go. +10. **`loupe`** ([`loupe`](#loupe)): the block, its placement and its + stems; `open` and `close` ([verbs](#6-verbs)); at most two; the one + elevation in the frame (`lift`, `shade`). +11. **Still from the last round**: the calls tree's small size and folds, + a frame name's 300 units, `time.caption_max` and `time.first_step`. -1. **A continue's registers strike in a wave** ([`continue`](#6-verbs)): - 2 f apart in pwndbg's order, the fill in over 6 f, no arm, no pulse. - Now every changed register arms on one frame and strikes on one frame - (sqlite, 0 to 8 s and each continue after): fourteen strikes at once. -2. **No marks on what arrived**: a window that faded to a new place, and - a dump that comes in after the step that changed it, show their values - plain. Now the stack's new window comes in struck at each continue, and - the row's dump arrives with a tick on every run. -3. **Far is a window's height**, for every window ([`scroll`](#6-verbs)): - the source (14, 8 or 10 lines), the disassembly (17 or 9), the stack (8 - or 6 slots) scroll when the new place is within their own height and - fade through (12 f out, 12 f in) beyond. Now the stack fades only - beyond 16 words (`context.zig`, `> 16`) and the source beyond two - windows (`source.zig`, `2 * fit`): sixteen rows in 24 f is a blur. -4. **The last stop's rsp pin** (sqlite at 64.6 s, stop 169): the stack's - lane has `rbp rsp` on `7fffffffe7e0`; rsp is `7fffffffe7a0`, above the - window. Only `rbp` is pinned there, and rsp, out of the window, has no - pin. -5. **The crossing's order** (`syscalls.zig` `Plan`): `returns` takes the - value 6 f before the arrow back leaves (`returns = back - 0.10`), rax is - armed while the arrow travels and struck as it lands (`struck = back + - cross`). Now `returns` fills as the arrow lands and rax strikes 0.20 s - after: the answer appears on the kernel's side after it has travelled. -6. **Names the code then follows**: - - `rows.Run.kind.allocator` and `hexdump.Kind.allocator` are `loose`: - any byte of no field (padding, past the struct), the allocator's - words among them; the chunk-size note stays. - - The scene's `split.backtrace = split.band` is the `backtrace` lens: - let the context place it (a lens choice, not a patched split), eleven - rows as subject, five beside. - - `hexdump.Dump`'s `of: Fields` is a dump by `fields`; `seen` and - `given` keep their names. -7. **Measures that change**: - - line numbers' width from the program's largest line - (`rows.numberRoom(rec.line_count)` in `source.zig` and `disasm.zig`), - not the window's; - - a dump's address room once per dump, from the widest address in its - window (`rows.addressRoom` is per row now); - - one reading for every dump, the list a character apart - (`hexdump.reading`, the typed dump's, still ranges numbers in three - characters; let `fieldReading` serve both); - - `fielded` keeps at most 16 rows and draws past the panel when the - rows holding fields outnumber the view's: keep the window round the - rows the step or a mark is on, and fold the others into `more` rows - with their counts; - - the stack's tag names the first and the last word shown, `rsp+20 to - rsp+48`, not the end past them (`rsp+50`); - - a frame's name is cut at 300 units with `…` (now never). -8. **The calls tree** past ten leaves: the small size, and folding past - thirteen leaves or six levels ([`calls`](#calls)). `calls.zig` has the - full size only. -9. **A visit and its ties**: a visit waits for a drawn tie to draw back, - or frames both its ends, before veiling a panel the tie starts or ends - in. `sort` no longer visits; this is the rule for the next scene that - does. +**What the recordings must hold** for these, which they do not now: + +- **Code round the pc**: 69 instructions with the pc in the middle third + means about 300 bytes of code before the pc and 300 after; simplest is + the program's text, symbols and line table once per recording, and for + a library 512 bytes either side of each pc in it, with its symbols. +- **The stack**: 69 words from rsp, 552 bytes, at every stop; with the + window's scroll down a long frame and `free` slots under the camera, + from rsp − 128 to rsp + 1024 (or the stack's top). The sqlite scene + records 512, `ztrace record`'s default is 128. +- **Round a loupe's target**: 80 bytes before and 80 after every chased + target the recording does not already watch (the recorded stack, the + tracked heap), clipped to its mapping: 160 where 32 are recorded today. +- **For the slot's roles**: the call frame information at each frame's pc + (which registers its prologue saved, where); the debug info's locals at + each frame's pc (name, and where: a frame offset or a location list); + the process's first stack pointer (argc, argv, envp, auxv sit at it). + Saved rbp and return addresses come from the frame chain, which the + recording has. +- **`memory`**: the 512 bytes round what a step reads or writes; the heap + is watched already, unwatched memory needs the 160 above at least. ## Token changes -Against `anim/src/theme.zig` as it is now (18:00): "In theme.zig" is what -is in the file, "Is" what the documents say. Numbers a view keeps for -itself (`calls.zig`'s `metric`, `stage.zig`'s fade) belong here too. +Against `anim/src/theme.zig` as it is now (21:15): "In theme.zig" is what +is in the file, "Is" what the documents say. | Token | In theme.zig | Is | | --- | --- | --- | -| `metric.insn.operand_chars`, `annotation_chars` | 24, 25 | removed: operands whole, the row 50 characters from 264 | -| `metric.bytes.first` | 132 | 132 at least, and 12 after the address's end (`address_gap` 12): 174 for twelve digits | -| `metric.bytes.reading` | 640 | 508 after the first byte: 640, or 682 for twelve digits | -| `metric.context.line_number_end`, `line_text`, `metric.plaque.line` | 46, 64, 50 | each plus 12 a digit past three, by the program's largest line number | -| `metric.calls` | none (`calls.zig`: radius 24, level 46, badge 30, caller 64 by 28) | full: disc 48, level 46, badge 30 at 12 right and 42 up, mono 25, a leaf 72; small: disc 36, level 38, root 60 under the tag, badge 24 at 6 right and 32 up, mono 20, a leaf 54; small past 10 leaves or 5 levels, folding past 13 or 6; a fold's count in faint mono 20 | -| `metric.span.name_max` | none | 300 | -| `time.continue_wave` | none | 2 f (`stagger`) between registers; fill 0.10; no arm, no pulse | -| `time.far` | none (16 words; two windows) | a window's own height; out 0.20, in 0.20 | -| `time.relayout_fade` | none (`stage.zig`: 12 f) | 0.20 before the move and after | -| `time.pin` | none | `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 | -| syscalls `Plan.returns`, `struck` | `back + cross`, `returns + strike.arm` | `back - 0.10`, `back + cross` | -| `time.caption_max` | none | 12.00 | -| `time.first_step` | none | 4.00 at the latest | +| `canvas.width`, `height` | 1920, 1080 | 3840, 2160 | +| `canvas.margin_x`, `margin_y` | 64, 48 | 112, 96 | +| `canvas.columns`, `column`, `gutter` | 12 of 120, gutters 32 | 4 of 880, gutters 32 | +| `canvas.stage` | 64, 48, 1792 by 840 | 112, 96, 3616 by 1688 | +| `canvas.clock_y` | 900 | 1798 (the rule 4, the gold 8) | +| `canvas.caption`, `caption_baseline`, `caption_max_width` | 64, 912, 1792 by 120; 990, 964, 1018; 1400 | 112, 1824, 3616 by 240; 1980, 1928, 2036; 2800 | +| `layout.program`, `state` | two columns of 880 | four: `source` 112, `disasm` 1024, `third` 1936, `stack` 2848 | +| `layout.Split` | band, view, source, disasm, registers, stack, backtrace, `dump_rows` | the same and `memory`; the view in the third column; `dump_rows` 32 | +| `layout.split.none` | source 14, disasm 17; registers, stack 8, backtrace 4 | source 69, disasm 69; registers, backtrace 16, `memory` 32; stack 69 | +| `layout.split.beside` | drawing 152 by 880, view 152 (5); source 8, disasm 17; registers at 212, stack 8 | drawing 300 by 1792; view 32 at 96; source 56, disasm 56; registers at 908, backtrace 16; stack 69 | +| `layout.split.subject` | drawing 296, view 200 (7); source 10, disasm 9; registers at 260, stack 6 | drawing 604 by 1792; view 32; source 43, disasm 43; registers at 908, backtrace 16; stack 69 | +| `size.sans.caption`, `caption_leading` | 40, 54 | 80, 108 | +| `size.mono.value` (code in a caption) | 35 | 70 | +| a lens's drawing | `metric.node`, `calls`, the array's cells at their sizes | the same numbers, drawn at `drawing_scale` 2 | +| the clock's count | mono 20 | mono 40 | +| `stroke.tie` | thread 3, link 3, projection 2 | 4, 4, 3 | +| `metric.tie` | `thread_x` 54, lanes 950 and 962 | `thread_x` 1008; lanes 1912 (link), 1924 (projection), 2832 (to the stack) | +| `metric.slot` | lane 10 to 112, chain 122, room 136 | lane 10 to 112, `offset` ranged right to 172, `address` 184, the role ranged right at the room's end | +| `mark(.current)` | ember `4a3d1c` across the row | `color.wash` `212644` across the row; the plaque stays gold | +| `mark(.write)`, a strike's paper | `ff6a4a`, digits in ink | `b54f42`, digits bright; `ff6a4a` stays for the arm, a projection and the corner | +| `held` | a tick 4 wide (`metric.context.tick`); a bar 4 high (`metric.ember_bar`) | a turned corner, 9; on a cell 12 | +| `color.lift`, `lift_tag`, `shade` | none | `121c52`, `22317a`, `02061a` | +| `metric.loupe` | none | 880 wide, 9 rows; shadow 12 right and 16 down, 20 and 26 for a deeper one; a deeper one 120 to the right; stem 4, head 12 | +| `time.loupe` | none | `read` 0.10; `stem` 0.30 (0.50 over 600 units); `rise` 0.20, shadow 0.30; `frame` after 0.10; `close` 0.20 | +| `camera.scales` | 1, 1.5, 2, 4 | the same; at x2 the frame is 1920 by 1080 of the 4K stage | +| from the last round | | `metric.calls` small (36, 38, badge 24) and folds; `metric.span.name_max` 300; `time.caption_max` 12.00; `time.first_step` 4.00 | -Unchanged and already there: the palette, region inks, the type sizes, -`layout.split` (the band as drawing and view; subject 296 and 200, nine -instructions, six slots), `metric.slot`, `metric.pin`, `metric.node`, -`metric.tie`, `stroke.tie`, `color.veil_alpha`, `time.veil`, -`time.strike`, `time.link`, `time.project` (with `far` 0.50), -`time.flight`, `time.caption`, `caption_lead`, `caption_lead_first`, -`time.establish` (the first caption at 1.0 s), `establish_rise`, -`time.run`, `sprint`, `ramp`, the camera's scales. +Unchanged and already there: the palette but for the marks above, region +inks, the context's type sizes (mono 20, rows 24, tags 24, padding 4), +`metric.bytes`, `metric.pin`, `metric.node` and `metric.calls` (drawn +twice), `color.veil_alpha`, `time.veil`, `time.strike`, `time.link`, +`time.project`, `time.pin`, `time.continue_wave`, `time.relayout_fade`, +`time.flight`, `time.caption`, `caption_lead`, `time.run`, `sprint`, +`ramp`. ## Building it 1. Atoms: `address` (unbroken, `lead`), `arrow`, `value`, `mark`, `pin`, `bracket`. The gallery starts here. -2. `chain`, then `reg` and `slot`: the state column at rest. +2. `chain`, then `reg` and `slot`: the registers and the stack at rest. 3. `insn` with its columns and annotations; `line`; `thread`. 4. `bytes` and `hexdump`; `nodes` in the band; quiet brackets. 5. `strike`, `cool`, `read`, `extend` at density; the `cascade`. @@ -1147,8 +1277,11 @@ instructions, six slots), `metric.slot`, `metric.pin`, `metric.node`, Export: ```sh -canim --export - --size 3840x2160 --fps 60 --frames N | +canim --export - --size 3840x2160 --fps 60 --frames N | # the 4K stage's own pixels ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - \ -c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \ -g 600 -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4 ``` + +1440p and 1080p are the master downscaled, never rendered at their own +size: `ffmpeg -i out.mp4 -vf scale=2560:1440:flags=lanczos …`. |
