summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md600
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 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 |
+| **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.