summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md585
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 frame, mid-step](mock/10-context-step.png)
+![the frame on the 4K stage, mid-step](mock/17-subject.png)
## 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 …`.