From f0180748b19eac5fe99124142aea60eac78cf4bd Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 22:43:41 -0300 Subject: design: the dense stage is a map; the frame keeps its layout and gains a minimap From the user, on the 4K mocks: the space was not well used, and the dense view is better as where a scene starts or as a minimap than as the frame it works in. The map is the same moment with every panel at full length on 3840 by 2160, packed by content. The working frame is the 1920 stage again, each panel a window on its column of the map, with the map at a twentieth in the caption band: windows outlined, marks no window shows flashing there. dive and surface carry a scene between the two, each window travelling to its panel's place. The loupe hangs from its pointer in the working frame. Mocks 16 to 18 are withdrawn; 19 is the map, 20 the dive in four instants, 21 a loupe with the minimap. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- design/README.md | 628 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 335 insertions(+), 293 deletions(-) (limited to 'design/README.md') 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 frame on the 4K stage, mid-step](mock/17-subject.png) +![the working frame, mid-step, its minimap in the corner](mock/10-context-step.png) ## 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 | - -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. +| **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 | + +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). - -**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. - +`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** 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. - -- 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. +Seventeen `insn`s in address order: the pc's, eight above, eight below. +Nine (four, the pc, four) when the lens is the subject. + +- 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 | - -**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. +| 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.** 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 | - -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 +| 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 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 | - -No data below 1784: a player's controls cover it. Sides: 112. - -**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 (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 | - -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. +| 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 888 but the minimap, which the narration never depends on: +a player's controls may cover its foot. + +**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 | 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` | + +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. - -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`. - -**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. +(`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 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 the map**, with the tracer's options: + +- `--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 | - -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`. +| `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 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. -- cgit v1.3