diff options
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 600 |
1 files changed, 321 insertions, 279 deletions
diff --git a/design/README.md b/design/README.md index c58dae2..02d5960 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 @@ -75,41 +75,38 @@ this table. | | [`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) | 3840 by 2160: the lens and four columns | split `none`, `beside`, `subject` | +| 5 frame | [`stage`](#5-the-frame) | the working frame: the band and the two columns | split `none`, `beside`, `subject` | +| | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key | +| | [`minimap`](#the-map-and-the-minimap) | the map at a twentieth, in the working frame's corner | windows, marks, `flash` | | | [`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 | | +| | [`dive` `surface` `flash`](#6-verbs) | between the map and the working frame | | | | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | ## 0. Tokens ### Grid -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). +**The working frame** is 1920 by 1080 units, at 60 frames a second; a 4K +master is two pixels a unit. It is where a scene is told, and everything +in it reads at 1080p. **The map** is 3840 by 2160 units at the same type +size: the working frame unfolded, every panel at its full length. It is +shown filling the frame (at half its size, so at 1080p its text is +texture), and small in the corner of the working frame as the +[`minimap`](#the-map-and-the-minimap). The working frame's panels are +windows onto the map's columns. | 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. The last panel of a column runs to the stage's foot, less than a row of padding under its rows | +| context mono | 20: an advance of 12, rows of 24, in the working frame and on the map alike | +| panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides | | between panels | 12 | -| 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. +| columns | working frame: two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties. Map: four of 880, at x 112, 1024, 1936 and 2848, 32 apart | +| strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames, a loupe's stem | ### Colour @@ -177,19 +174,19 @@ stream. OFL and BSD; `/usr/share/fonts/TTF/`, `/usr/share/fonts/go/`. | Mono | Advance | For | | --- | --- | --- | -| **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 | +| **20** | 12 | the context, the dumps, a loupe, the map | +| 25 | 15 | a lens's values beside; 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 | -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. +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. On the map, filling a 1080p +frame, mono 20 is 10 pixels: texture, which the caption carries; in a 4K +export it is 20 pixels and reads. ## 1. Atoms @@ -275,7 +272,7 @@ What happened, on paper and never in the letters. | `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` | 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) | +| `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 | | `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 | @@ -538,23 +535,26 @@ moment's registers and mappings. ### stack -`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). +`slot`s from rsp, low addresses on top: eight; six when the lens is the +subject. `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** 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. +**The window** is on the newest frame: the words from rsp to its return +address, `[rsp, rbp+16)`. It is a window onto the map's stack column, which +runs from 16 words above rsp to the stack's top. +- 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 its height fades through instead @@ -563,17 +563,17 @@ top never passes above rsp. ([`visit`](#6-verbs)): pushes fill `free` slots in the middle of the frame, and rsp's pin climbs to them. -Tag: `69 words from rsp`, or the range when scrolled (`rsp+20 to -rsp+240`), and `· the frames they belong to`. +Tag: `six words from rsp`, or the range when scrolled (`rsp+20 to +rsp+48`), and `· the frames they belong to`. ### backtrace -`call` rows, newest on top: 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. +`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. More frames than rows: the oldest go, and the tag's note counts them, -`newest on top · 2 more`. +`newest on top · 2 more`. On the map it is whole. On a stop far from the last (a [`continue`](#6-verbs)) the chain changes as rows making room: the frames that end fade out (12 f); the frames both @@ -585,38 +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: 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 +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 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)). +largest ([`line`](#line)). On the map the file is whole, or 69 lines round +the current one when it is longer. ### disasm -`insn`s in address order, a column's height: 69 rows in `none`, 56 -beside a lens, 43 as its subject. +Seventeen `insn`s in address order: the pc's, eight above, eight below. +Nine (four, the pc, four) when the lens is the subject. -- 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. +- Rows above the pc are the function's own instructions where it has + them; near its start the window stays full from below. +- Rows of another function are `outside`: plain, under a rule and its + name. - 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. +On the map the column is 69 rows: the function whole when it fits, with +its neighbours round it. + ### lenses -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)). +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)). On the map +the drawing keeps its subject size and the view is its region whole. | Lens | Drawing | Its view | Mock | | --- | --- | --- | --- | @@ -629,10 +629,9 @@ 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. +`memory`, on the map, is the column of the regions the scene's steps +touch, each a `hexdump` kept round what was read or written, typed where +the recording types it; a lens's view is a window onto it. 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 @@ -642,9 +641,9 @@ row reaches `pwrite64`. **What a new lens must provide** to fit the frame: -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 +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; the region whole on the map), 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 @@ -666,8 +665,9 @@ 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: 32, 512 bytes, as a lens's view and as `memory`; nine in -a [`loupe`](#loupe). Rows in address order. +the step touches: five beside, seven as subject, five in a +[`loupe`](#loupe), the region whole (to 32 rows round what the step +touched) on the map. 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`. @@ -743,8 +743,7 @@ 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 row in the backtrace, the view, -to the node. +[`projection`](#4-ties) from the frame's return address 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 @@ -804,21 +803,24 @@ 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` | +| panel | 880 wide, a tag and five `bytes` rows (152 high): the target's row in the middle, two before and two after (80 bytes), its runs typed (a node's value and next, malloc's words) or by `fields`. On the map it has nine rows (144 bytes), as everything there is longer | | 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 | +| stem | the tie from the pointer to the loupe: a `link` (3 units, the target's region ink, head 10 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. +**Where it floats.** In the working frame it hangs from its pointer: its +tag's top on the foot of the pointer's row, its left edge 92 left of the +pointer's digits (so the tag's address sits under them), clamped to the +stage, and a 4-unit bracket under the digits lying on the tag: the stem, +as short as a stem can be; it covers the rows under its pointer, whole. A loupe opened from a loupe hangs the same +way from its field, 120 to the right, over the older one'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 moves down past +them, then to the other side; it stays inside the stage. On the map it is +a panel of its own beside the memory it shows (the map has room), and on +the minimap a lifted box there, its target's row outlined in its region's +ink. **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 @@ -831,7 +833,7 @@ 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. +opens and closes by its verbs ([`open`, `close`](#6-verbs)). Mocks 19 and 21. ## 4. Ties @@ -840,9 +842,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, 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 | +| `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. On the map, where source and disassembly are side by side, across their gutter (x 1008) | | `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 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 | +| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; or the return address of a frame made or ended, on the stack; the part of the drawing made of them (a node's address, a cell, a call's node) | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket at the part (over a node's address; under a call's node); and the mark itself on the run and on the part | | `echo` | these are one event | the same mark at the same instant in two panels: the annotation's address and the dump's run | for that step | no line | | ink, digits | these are one thing | an address anywhere and its row, node or name; a call's arguments on its span, its backtrace row and its node | always | no line | @@ -869,87 +871,150 @@ 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). On the 4K stage the four columns leave three gutters: +projection): | Channel | Carries | | --- | --- | -| 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 | +| 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 | | 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 | +| 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 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 +Ties that climb from the state column take the left lane and arrive from +below; the view's projections keep to the band in the right lane and +arrive from above. A link down to a slot takes the right lane under the +band and ends above the frame's return address, where a calls +projection leaves for the left lane: so the ties of one step cannot +cross. A tie may cross a panel's rule; it never crosses a letter, a digit or another tie. A projection climbing to a call node crosses no edge: under a node that has just been made there is only room for its own -children. +children. The map draws the thread and no other tie: a link or a +projection is a step's, and steps are told in the working frame. **Order.** A tie arrives before the thing it points to reacts: see -[`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. +[`link` and `project`](#6-verbs). Mock 9 shows the standing ties; 10 and +11 all four; 12 the projection to a call; 21 a loupe's stem. ## 5. The frame -The stage is 3840 by 2160 units, the 4K master's pixels. +The working frame: where a scene is told. | Band | y | | | --- | --- | --- | -| 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 | +| 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; the minimap at its right end, 1664 to 1856 by 912 to 1020 | | +| margin | 1032 to 1080 | page | -No data below 1784: a player's controls cover it. Sides: 112. +No data below 888 but the minimap, which the narration never depends on: +a player's controls may cover its foot. -**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. +**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. -| 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 | +| 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` | -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. +Each panel is a window onto a column of the [map](#the-map-and-the-minimap), +and the minimap shows where. **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, the source gets two back, and the view stops two rows short +of the drawing so that the stack keeps six slots. With a lens open the +source is a window of eight or ten lines on the file: the map holds the +rest, and the minimap shows it. | Of the frame | `none` | `beside` | `subject` | | --- | --- | --- | --- | -| context | 72% | 56% | 50% | -| lens (the drawing and its view) | | 15% | 22% | -| caption band | 10% | 10% | 10% | +| context | 68% | 56% | 48% | +| lens band (the drawing and its view) | | 13% | 21% | +| caption band, with the minimap | 10% | 10% | 10% | + +### The map and the minimap + +**The map** is the working frame unfolded: every panel at its full length, +on a stage of 3840 by 2160 units (sides 112, top 96, the stage 3616 by +1688), at the context's type size. It is one picture of the program at a +moment: the whole of a short file, the function round the pc and its +neighbours, all seventeen registers, the whole backtrace, the stack from +16 words above rsp to its top, the regions the scene's steps touch, the +lens's drawing, and the loupes open. + +- **Columns by content.** Four columns of 880, 32 apart, in the working + frame's order: the drawing and the program's panels in the first two, + the state's in the last two. Panels are packed: each as long as its + content (a file of 42 lines is 42 rows, a backtrace of five frames five), + the next under it with 12 between; a panel longer than what is left of + its column continues at the top of the next column's free space, as a + second column of itself under the same tag, `continued`. Nothing is + stretched and nothing is centred to fill: a column's foot that is left + holds the map's key (the scene, the moment, the marks' legend), or is + page. +- **Its lengths.** The source: the file whole, or 69 lines round the + current line. The disassembly: 69 rows, the function whole where it + fits. The stack: from 16 words above rsp (the 128 bytes the recording + keeps under it) to the stack's top, folded into `more` after the + process's start. Memory: each region the scene touches, 32 rows round + what was touched, fieldless rows folded. The drawing: its subject size, + 880 by 296. A loupe: nine rows, beside the memory it shows. +- **What it draws.** The rows as the working frame draws them, the marks + of the moment (current, struck, read, held, trail), the thread across the + gutter between source and disassembly, and an outline round each of the + working frame's windows: a 2-unit `dim` frame, 4 out. No link and no + projection: a step's ties are the working frame's. +- **What reads where.** In a 4K export the map filling the frame is 20 + pixels to a row's text and reads; at 1440p 13 and reads on a monitor; at + 1080p 10, a texture of shapes and inks in which the windows, the gold + rows and the vermilion of a write are what is seen. The caption carries + it there, and the map is never on screen for reading at 1080p: it is + for where, not for what. + +**The minimap** is the map at a twentieth, 192 by 108, in the working +frame's corner: the caption band's right end, 1664 to 1856 across and 912 +to 1020 down, under the clock's right end. The caption keeps its 1400 (it +ends at 1464); the clock's count moves left of the minimap, ranged right +at 1648. + +| Part | Drawn | +| --- | --- | +| ground | the page, framed 1 in `rule` | +| panels | each map panel's outline, 1 in `rule`; a lens's drawing a `raised` block; a loupe a `lift` block | +| rows | each row of text a stroke 1 high, from where its text starts as long as it is (a twentieth of its characters' width), in its dominant ink at 45% toward the page: the file's shape, the stack's chains, a dump's bytes | +| windows | each working panel's window, 1 in primary, the panel in focus 2 | +| marks | the current row a gold stroke across its column, 2 high; a strike a vermilion block 3 by 3 at the row's start; a read a 3 by 3 frame in read's colour; held a vermilion pixel; the thread a gold stroke across the gutter | + +A mark outside every window is on the minimap and nowhere else: when the +step strikes a word the stack's window does not show, its block on the +minimap strikes with it, and `flash`es (a ring 8 across drawing out to +14 and gone, 12 f) so the eye goes there once. That is how nothing is +hidden at the working frame's size: it is only small. The minimap is +secondary action: it never starts on a primary onset's frame, it fades +and never travels, except its windows, which glide with their scrolls. ### clock and caption -- **`clock`**: a 4-unit rule the width of the stage at y 1798; gold, 8 +- **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4 high, along it as far as the recording has run; `moment 72 of 95` in - mono 40, faint, under its right end. It says where the recording is, so + mono 20, faint, ranged right at 1648, left of the minimap. 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 80 on 108, - ranged left on the margin; code in it is mono 70. Hex in it is unbroken +- **`caption`**: one or two lines of at most 64 characters, Go 40 on 54, + ranged left on the margin; code in it is mono 35. Hex in it is unbroken too. What a scene author checks, characters counted as shown: | Rule | Number | @@ -957,7 +1022,7 @@ window: the trade with rule 6 stands, at four times the window. | on screen, from arrived to leaving | at least 1.5 s + 0.06 s a character (90 f + 3.6 f) | | on screen | at most 12 s; a longer stretch wants a second caption or a shorter scene | | before the first step it describes fires | 60 f after it has arrived; 120 f for a scene's first | - | a scene's first | arrives at 1.0 s; the first step fires by 4.0 s | + | a scene's first | arrives at 1.0 s; the first step fires by 4.0 s (5.0 s when the scene opens on the map and dives) | | changes | only in a rest, never under a moving thing | | longer than two lines | two captions, split at a phrase rest | | the last | its reading time before the cut, and 2 s on the finished picture; the scene grows to fit | @@ -967,11 +1032,9 @@ window: the trade with rule 6 stands, at four times the window. 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 (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. +- **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. ## 6. Verbs @@ -992,13 +1055,16 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: | `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 | +| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and the map becomes the minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; the map, veiled, goes the same 72 f to the minimap's place, its scale from a half to a twentieth, so the windows rise out of it as it falls away; their outlines stay on it and land as the minimap's windows. 72 to 96: the drawing, whose sizes differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: the frame's tags, rules and lanes fade in; the veil on the map lifts as it lands. 96 to 132: still | +| `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out; 12 to 84, `glide`, the panels shrink into their windows as the minimap grows to fill the frame; 84 to 96 its veil lifts; then the map is still 36 f before anything plays on it | +| `flash` | the minimap, at a mark no window shows | a ring 8 across in the mark's colour draws out to 14 and is gone, 12 f, with the mark's own strike or read | | `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 | -| `run` | steps that need not be read | 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; values change with an ember, never a solid; no ties but the thread. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most | -| `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before | +| `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `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 | +| `run` | steps that need not be read | 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; values change with an ember, never a solid; no ties but the thread. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most. A run longer than a phrase may `surface` and play on the map | +| `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before. A sprint plays on the map: `surface` before it, `dive` after it, at the stop it reaches; the windows glide with the pc, the minimap's marks flash and fade | | `establish` | a scene's opening | done by 54 f: the panels fade in, 18 f each, 6 f apart (registers, stack, source, disassembly, the band's view, the drawing's panel: 0 to 48); from 30 f the drawing's elements fade in rising 8 units, 12 f each, 2 f apart in address order and all begun by 42 f, each with its row's quiet bracket (an `echo`: no lines). The first caption arrives at 60 f | -| `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows. A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before. A window going farther than its own height (ten lines, nine instructions, six slots) does not scroll, which would only blur: it fades out (12 f) and in at its new place (12 f), and what it brings comes in with no marks | +| `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows; the window's outline on the minimap glides with it, the same 24 f. A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before. A window going farther than its own height (ten lines, nine instructions, six slots) does not scroll, which would only blur: it fades out (12 f) and in at its new place (12 f), and what it brings comes in with no marks | | `relayout` | a change of split | the drawing fades out (12 f); every panel moves to its new box, clipped to the box as it moves (48 f, `glide`); the drawing fades in at its new size (12 f). Nothing else moves under it | | `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`. The panel's tag and whole rows in frame, the rows the visit's steps change in its middle third, never at its edge; a stack visited holds its window still. A visit never veils or clears a panel a drawn tie starts or ends in: it waits until the tie has drawn back, or frames both ends. 120 f at most without a change; back | | `say` | the caption | out 12 f, gap 6 f, in 18 f; the numbers are under [caption](#clock-and-caption) | @@ -1011,9 +1077,9 @@ for a return across three levels, 2.7 s for a swap. **What may contain what.** -- 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, +- The working frame holds the band and two columns; the band is two + panels, one over each column. The map holds the same panels, whole, in + four columns. A column holds panels. A panel holds a tag and rows, or (a lens) a tag and a drawing. A row holds atoms. Nothing nests deeper. - Every panel shows the same moment. A register from one stop beside a @@ -1069,35 +1135,35 @@ 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/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. +`mock/context.py` draws 12 to 14, one function a block under the block's +name; `mock/map.py` draws the working frame from a fresh recording of +`targets/list` (9 to 11, 21), the map (19) and the dive (20); +`mock/dense.py` holds that recording's data and draws the marks sheet +(15); `mock/gen.py` draws 1 to 8. Each working frame has a `-480.png` +beside it; the map has its 1080p (`19-map-1080.png`). ```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 +python3 -B context.py && for n in 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 dense.py && resvg 15-marks.svg 15-marks.png +python3 -B map.py && for n in 09-context 10-context-step 11-context-lens 21-loupe 19-map; do + resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done # 20-dive.png it composes itself python3 -B gen.py # 1 to 8, then resvg the same way ``` | Mock | Is | Blocks it shows | | --- | --- | --- | -| [9](mock/09-context.png) | `beside`, at rest: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot`, `pin` row; `call` spans; `insn` current, ran, ahead, outside, with the jump lane; `line`; `bytes` with number, pointer, loose (the allocator's), unread and `pad`; `nodes` with pins under, two names on one; `thread`; marks current, held, trail | -| [10](mock/10-context-step.png) | the same, mid-step | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin, rax's name kept on its side; `projection` | -| [11](mock/11-context-lens.png) | `subject` | the drawing 296 high and a size up, its view a dump of seven, nine instructions, six slots | -| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments; `call` spans with arguments; the stack's window from rsp, six slots; a `projection` from the return address to the new node; `insn` with a call and its argument, a write, and operands of 27 characters whole | +| [9](mock/09-context.png) | `beside`, at rest: `targets/list` stopped at the load in `reverse` (`mock/list-dbg.txt`, moment 2) | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot` with offsets and roles, `pin` row; `call` spans; `insn` current, ahead, outside under a rule and its name; `line`; `bytes` by fields with number, pointer, loose; `nodes` with pins under, two names on one; `thread`; marks current, held; the minimap, its windows | +| [10](mock/10-context-step.png) | the same, mid-step: the load done (moment 3) | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection`; the minimap | +| [11](mock/11-context-lens.png) | `subject`, mid-step | the band at 296 and 200, the drawing a size up, a dump of seven, nine instructions, six slots; the minimap with the subject's windows | +| [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 row with offsets and a role; a `projection` from the return address to the new node; 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` | +| [19](mock/19-map.png) | the map, mid-step with a loupe open: the same moment unfolded on 3840 by 2160 ([at 1080p](mock/19-map-1080.png)) | the file whole; 69 instructions; memory, the registers, the backtrace whole; the stack from 16 words above rsp, continued at the third column's foot and folded into `more` at the process's start; the loupe as a panel beside memory; the key; the thread across the gutter; the working frame's windows outlined | +| [20](mock/20-dive.png) | `dive`, four instants on one sheet, each at the working frame's size | frame 0 the map; 24 the windows bright, the rest veiled; 60 halfway, the panels rising out of the map as it falls to the corner; 96 the working frame with its minimap | +| [21](mock/21-loupe.png) | the working frame mid-step with a `loupe` open | the loupe hanging from rdi over the registers under it, its node framed; the minimap with the loupe at its place on the map, outlined bright | | [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` | @@ -1126,13 +1192,16 @@ the band. - 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. + by `fields`; two in the working frame; a third closing the first. +- The minimaps of 12 to 14: their recordings hold a stack of 64 words or + less and no bytes round targets, so their maps would be mostly gaps. +- `surface`, `flash`, a window's outline gliding on the minimap. - 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. -**The data in 9 to 14** is the recordings': registers, chains, stack, the +**The data in 9 to 21** is the recordings': registers, chains, stack, the instructions and their lines (12: `ztrace show` on `anim/zig-out/recordings/steps.ztrace`, lines from its binary by `addr2line`; 13 and 14: `ztrace show` on the sqlite scene's recording, @@ -1153,114 +1222,84 @@ still read. ## What this asks of the renderer What the documents say and `anim/src` does not do, as read on 10 November -(`theme.zig` as of 21:15); the tokens are under [Token changes](#token-changes). -Last round's `continue` and crossing stand as specified. +(`theme.zig` as of 22:37: the marks and the stack's row are in; the 4K +stage of the last round was never built, and is withdrawn); the tokens are +under [Token changes](#token-changes). -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. **The map**: a second layout at 3840 by 2160 units, the same panels and + rows, each panel at its full length ([the map](#the-map-and-the-minimap)): + the source whole or 69 lines, the disassembly 69 rows, the registers, + the backtrace whole, memory per region touched (32 rows, fieldless rows + folded), the stack from rsp − 128 to its top, the drawing at its subject + size, loupes at nine rows; packed into four columns by content, a panel + continuing in the next column's free space under `continued`, the key + in a column's left foot. It draws the thread and the marks, no link and + no projection, and outlines the working frame's windows. +2. **The minimap**: the map drawn at a twentieth in the caption band's + right end (1664, 912, 192 by 108): text runs as strokes, blocks for tags, + paper and loupes, the marks over them, the windows outlined; the clock's + count moves left of it. `flash` for a mark no window shows. A window's + outline glides with its scroll. The camera never takes it. +3. **`dive` and `surface`**: a transition that draws each working panel + in its own transform (scale and offset), from its window on the map to + its place, while the map, veiled, is drawn in one transform from + filling the frame to the minimap's rect; scales on their logarithms, + `glide`; the panels 6 f apart in the frame's reading order (drawing, + view, source, registers, disassembly, stack), each later one over the + earlier, so that none crosses another mid-flight unseen. The camera + moves one transform for the whole stage and `relayout` lerps boxes at + one text size: neither does this. A sprint, a long run and a far + `continue` are played on the map between a `surface` and a `dive`. +4. **The loupe** at the working frame's measures ([`loupe`](#loupe)): + five rows, hanging from its pointer, the lift and the shadow; nine rows + as a panel on the map; on the minimap a lift block, its target + outlined. +5. **Still from before**: the calls tree's small size and folds, + `metric.span.name_max` 300, `time.caption_max` 12 s and `time.first_step` + 4 s (5 s when a scene opens on the map). -**What the recordings must hold** for these, which they do not now: +**What the recordings must hold for the map**, with the tracer's options: -- **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. +- `--stack 1024`: the stack from rsp to 1024 above it, at every stop, and + the 128 bytes under rsp the tracer now keeps; the map's stack column is + 69 slots and its continuation (about 90), the rest folded. +- `--disasm 69`: 34 instructions above the pc and 34 below, with their + lines; a function the window holds whole needs no more. +- `--around 256`: 256 bytes either side of every telescope target and + every touched address, clipped to its mapping: the map's memory column + is 32 rows round what a step touched, and a loupe's nine rows (80 either + side) fit inside it. +- Unchanged: the source file, the frame chain, the allocations; for the + stack's roles, the call frame information, the locals' places at each + frame's pc, and the first stack pointer, as the last round asked. ## Token changes -Against `anim/src/theme.zig` as it is now (21:15): "In theme.zig" is what +Against `anim/src/theme.zig` as it is now (22:37): "In theme.zig" is what is in the file, "Is" what the documents say. | Token | In theme.zig | Is | | --- | --- | --- | -| `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 | +| `map` | none | `canvas` 3840 by 2160; sides 112, top 96; the stage 3616 by 1688; four columns of 880 at 112, 1024, 1936, 2848; the thread at 1008; the window outline 2 in `dim`, 4 out; panel lengths as listed | +| `minimap` | none | at (1664, 912), 192 by 108, a twentieth of the map; strokes 1 high at 45% toward the page; marks at least 1.5; windows 1 in primary, 1.5 bright for the one in focus; frame 1 in `rule` | +| `canvas.clock_count` | at the stage's right end | ranged right at 1648, left of the minimap | | `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 | +| `metric.loupe` | none | 880 wide; 5 rows in the working frame, 9 on the map; hangs from the foot of its pointer's row, its left edge 92 left of the pointer's digits; shadow 12 and 16, a deeper one 20 and 26 and 120 to the right; stem 3 | +| `time.loupe` | none | `read` 0.10; `stem` 0.30; `rise` 0.20, shadow 0.30; `frame` after 0.10; `close` 0.20 | +| `time.dive` | none | `bright` 0.10, `veil` 0.30, `move` 1.20 (`glide`, 0.10 between panels), `fade` 0.20 at its end, `still` 0.60; `surface` the same, the move first | +| `time.flash` | none | 0.20: a ring from 8 to 14 | +| `time.caption_max`, `first_step` | none | 12.00; 4.00, 5.00 when a scene opens on the map | +| `metric.span.name_max` | none | 300 | +| `metric.calls` small, folds | full only | disc 36, level 38, badge 24 at 6 and 32, mono 20; fold past 13 leaves or 6 levels | -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`. +Unchanged and already there: the 1920 stage and its splits, the palette +with the marks of the last round (`wash`, `struck` `b54f42`, the corner), +`metric.slot` with its offset and role, `metric.bytes`, `metric.pin`, +`metric.node`, `metric.calls` (full), `metric.tie` (54, 950, 962), +`stroke.tie`, `time.strike` (with `corner`), `time.link`, `time.project`, +`time.pin`, `time.continue_wave`, `time.relayout_fade`, `time.flight`, +`time.caption`, `caption_lead`, `time.run`, `sprint`, `ramp`, the +camera's scales. ## Building it @@ -1273,15 +1312,18 @@ twice), `color.veil_alpha`, `time.veil`, `time.strike`, `time.link`, 6. `link` and `pin`; `project`; `echo`. 7. `call` spans; the three splits and `relayout`; the camera at x1.5. 8. The other lenses in the band. +9. The map and the minimap; `dive` and `surface`; the loupe. Export: ```sh -canim --export - --size 3840x2160 --fps 60 --frames N | # the 4K stage's own pixels +canim --export - --size 3840x2160 --fps 60 --frames N | ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - \ -c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \ -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 …`. +size: `ffmpeg -i out.mp4 -vf scale=2560:1440:flags=lanczos …`. The map, +filling the frame, is drawn at half its units: 20 pixels a row's text in +the 4K master. |
