diff options
Diffstat (limited to 'anim')
28 files changed, 682 insertions, 304 deletions
diff --git a/anim/README.md b/anim/README.md index 7f963fe..8b04975 100644 --- a/anim/README.md +++ b/anim/README.md @@ -108,20 +108,29 @@ its touch from the row to the word, the word, rsp's or rbp's pin travelling with the amount on it, the window following last. `.whole` is pwndbg's chain, offsets from rsp and the old cascade, for a scene whose story is the address itself (heap, sqlite, the gallery). `at.levels.carry` (`.off` by -default, `.arrow`, `.value`) is read at each step, so a beat can set it -before a walk and put it back after: +default, `.arrow`, `.value`, `.after_touch`: the arrow after the +instruction's touch, a store's too) is read at each step, so a beat can set +it before a walk and put it back after. `at.levels.introduction` (read when +the context is made) says what the working frame leaves to the eye: the +stack's offsets and a pin's amount with `0x` where hex and decimal differ +(`-8`, `+0x10`), a return address's role (`the way back`), a store of the +value its word held struck as any write: ```zig at.levels = .{ .idea = .calls, .source_rows = 8, .annotation = .whole }; // before canim.context at.levels.carry = .arrow; at.walk(s, .moment, to); at.levels.carry = .off; // the value's way, for one beat at.aim(s, .standing); /* ... */ at.aim(s, .off); // a word holding a code address tied to its row, for some beats +at.aim(s, .drawn); /* ... */ at.aim(s, .standing); // drawn as a step's, at full ink, then down to 60% ``` `aim` is off by default everywhere (design/README.md, "4. Ties": the author's to turn on, never the budget's): `.standing` draws, for the words on screen in memory that hold the address of an instruction whose row is shown, one tie to that row, in and out with the knob (18 f, over what -follows); `.step` the one of the word a walked step writes or reads. +follows); `.step` the one of the word a walked step writes or reads; +`.drawn` stands it drawn as a step's is (head first at full ink, 18 f, the +row's address framed as it lands, 6 f), a `.standing` after it falling to +60% (18 f). Its head is 10 by 10. **The text column** (`src/column.zig`, design/README.md "column"). A scene can tell its beats with the panes a beat @@ -182,9 +191,9 @@ canim.descent.step(cur, s, .moment); | `gallery` | every block in its states, a page or a state each 3 s; at 21 s the `blocks` lens (sort's rings at rest, `leave` mid-way, a `turn` landing with its ring's count struck; libc's `open` in `layers` at its `syscall`, what it has not reached folded), at 24 s the moves of a first time (sort's first swap `reach`ed, its pill filling; `open` stepped past its `syscall`, its fold mid-`unfold`; sort in `layers` panned to the pc; the fold open, at rest). Its context pages fold the registers its one step does not change | all three, `blocks` | `gallery`, and for the graph pages `test/gallery/sort.ztrace` and `hello.ztrace` (the second page's picture keeps the old name `graph-map.png`) | | `column` | the text column (design/motion.md, "A scene in the column"): `syscalls`' story on the same recording and steps, beat by beat as the storyboard's table C1 to C12 has it, its texts as it cuts them (C4's 57 characters): the opening `below` (the working frame whole, its caption); the arguments beside the source and the disassembly over the registers; the call and the stub's jmp beside the descent over a stack of twenty words (the touch from the call row down the gutter to the free word, rsp's pin climbing); the wrapper at a run over a source of two lines, the text level with open's head; its last three beside the registers; the crossing beside a descent of twenty-four rows, the text level with the kernel's floor; back up, the text at main's call row; `read`, `close`, `write` stepped over, the bytes over the source, each text beside its call row; the close `below`. Every other pane on the shelf, the registers' strikes on their tag | the column (`column.zig`), the working frame `beside` at the opening and the close | `hello` | | `column_sort` | the column's wide placements on sort's first trip: the opening `below`, then the rings across both columns twice their size, the others on the shelf (`sort.c line 12`, `disassembly jne …`), a text `on` the drawing in the corner the rings leave free with its stem round the drawing's top to the pc's block; then a text `above` it; then the working frame again | `blocks`, then the drawing across both columns (`Stage.zoom`) | `sort` | -| `intro_memory` | the introduction's first chapter (design/motion.md, "A scene: the introduction", I1 to I10): the 128 bytes at the top of the stack under the camera at x2; `regroup`, sixteen a row to eight (the return address walked: the top row, so its bytes fly under it and its offsets stand over it; the rest at a run); three words that hold addresses framed; into the column, the dump folded to a tag; the address space to scale (`segments`, mock 34: a slim bar, then `enlarge` a cluster at a time, the stack, the libraries, the program by segment, start, end and size on every band), texts beside; back to the working frame: the dump's `tie` and `link` onto the stack's box (mock 30), a visit at x4, `ink`, three chains | the working frame (`below`), the column for I4 to I6 | `intro`, reverse's first instruction (`push rbp`) | -| `intro_stack` | chapter II (II1 to II4, mock 31), from I's last picture: the words glide into the stack panel's rows (sixteen and two `free` over rsp) and become it; rsp's row arrives over the stack, its pin on the top word; `push rbp` walked (the touch, the word, rsp's pin climbing); the way back framed, main's three rows round its call arriving in the program column and the word aimed at the row it returns to (`aim`, this beat only), the offsets a `column`; rbp's row and pin, `mov rbp, rsp` and `sub rsp` walked, the roles and the spans a `column` each, the panel's tag last (`frame up`); the registers built row by row, their tag last; texts beside on the left, in the program column | the working frame without a backtrace, texts on the left | `intro`, reverse's first three instructions | -| `intro_code` | chapter III (III1 to III5, mocks 32, 33, 36), from II's last picture (it gives way): the code's bytes as a dump row in code's ink, an instruction's four framed; `decode` into `aligned` (`interleaved`, mock 33: lines and addresses in one column, a rule over every group, the load's row annotated), the neighbours at a run; `align` to `columns` (mock 36); `stack` to the working frame (the lines glide to the source panel's rows, the instructions down and into the disassembly's, the panels come in under them); the list's nodes from the heap's bytes; each pane's minimap last; `surface` to the map, its text on it | `aligned`, texts above; then `subject`, `nodes`; the map | `intro`, the load on line 21 | +| `intro_memory` | the introduction's first chapter (design/motion.md, "A scene: the introduction", I1 to I10): the 128 bytes at the top of the stack under the camera at x2, arriving as the first text lands (`128 bytes at 7fffffffebc8`); `regroup`, sixteen a row to eight (the return address walked: the top row, so its offsets stand over it in the header's row, `low byte` and `high byte` outside them, and its bytes fly over that row, one in the air at a time, each with its offset; the rest at a run; a plain number with `0x`); three words that hold addresses framed; into the column, the rows gliding up into the header, which becomes the tag (`the 128 bytes`) and goes to the shelf; the address space to scale (`segments`, mock 34: a slim bar, then `enlarge` a cluster at a time, the stack, the libraries, the program by segment, start, end and size on every band), texts beside; back to the working frame: the dump's `tie` and `link` onto the stack's box (mock 30), its addresses in the stack's ink as the box lights; a visit at x2 framing the box and the dump's top rows, the place marked `128 bytes` on the box; `ink`, three chains (`→` and `←` said) | the working frame (`below`), the column for I4 to I6 | `intro`, reverse's first instruction (`push rbp`) | +| `intro_stack` | chapter II (six beats, mock 31), from I's last picture: the words glide into the stack panel's rows (sixteen and four `free` over rsp, the window held: nothing in the panel moves) and become it, the convention said there (lower addresses drawn higher) as the offsets come down its rows (a `column`); rsp's and rbp's rows arrive over the stack, rsp's pin on the top word, rsp's link down to it (`Context.tiesWith`); the call first: the way back framed, main's three rows round its call arriving in the program column and the word aimed at the row it returns to (`aim`, drawn head first at full ink, 60% through the push); reverse's first rows (the disassembly, seven rows) under main's, `push rbp` walked (the touch from its row, rbp's value carried to the word, struck though it held it, rsp's pin climbing); `mov rbp, rsp` and `sub rsp` walked, the roles (`the way back`) and the spans a `column` each, the panels' tags last (`frame up`); the registers built row by row, their tag last; texts beside on the left, in the program column | the working frame without a backtrace, texts on the left | `intro`, reverse's first three instructions | +| `intro_code` | chapter III (III1 to III5, mocks 32, 33, 36), from II's last picture (its texts and code give way, its state column stays veiled at 50% until the decoded code spans it): the code's bytes as a dump row in code's ink, an instruction's four framed; `decode` into `aligned` (`interleaved`, mock 33: lines and addresses in one column, a rule over every group, the load's row annotated), the neighbours at a run; `align` to `columns` (mock 36; the width squares said); `stack` to the working frame (the lines glide to the source panel's rows, the instructions down and into the disassembly's, the panels come in under them), `Later, at line 21`; the list's nodes from the heap's bytes (node 9's pin `head cur rax` in full, its row `9 → 405030`), rax's link up to it; each pane's minimap last (said); the map's text lands, then `surface` under it | `aligned`, texts above (two lines of 80); then `subject`, `nodes`; the map | `intro`, the load on line 21 | | `asan` | plain against AddressSanitizer on `overflow.c` (design/motion.md, "A scene: ASan against a plain build", A1 to A16): a `pair` (A1 to A9, A14 to A16: the shared source, each run's disassembly, registers and frame as bytes eight a row with ASan's shadow byte beside each row, `only here` and `differs` bars, the parting framed `attention`, ASan's stderr in place of its registers once stopped) and the column for A10 to A13 (ASan folded to one shelf tag, its report's first line on it; plain's disassembly a descent, main's window over fill's whole; plain's frame the column's rest; each text level with the field the letter lands in; `aim = .standing`: the return address aims at main's row after the call, glides to `fill+1` at i = 24 and frays at i = 25); i = 27 held 4.9 s (mock 38, the poster); the fault at `ret` (SIGSEGV, rip stays) | `pair.split`, then the column | `overflow`, `overflow_asan`, `overflow_report` | ## The blocks @@ -206,17 +215,17 @@ every state the code has in the `gallery` scene. | | `disasm` | `src/disasm.zig` | under the source in every split: 17 rows (11 as subject and with `blocks`), fewer above near a function's start; on the map 69 from the function's start where the pc is in its first three quarters (a strip's column stays still while the pc walks it), else round the pc; the line column as wide as the source's, a row's number where its line is of the file the source panel shows (libc's rows open64.c's while it shows open64.c, main's none then); two windows that overlap scroll, others fade out and in; its tag's function (a descent's tag too) crossfading with the advance; a 2-unit `rule` across over each block's first row (not its function's), and the block's visits by the moment shown ranged right, faint (`×3`), where the row's annotation leaves room, crossfading with the advance (`graph.Rules`, a descent's windows too); the rows clipped above the panel's padding (a row scrolling out takes its rule with it) | | | `graph` | `src/graph.zig` (`read`, `layout`, `place`, `Blocks`, `Rules`, `leave`) | the function's blocks from the recording (`zt.telescope.blocks`; a block of `nop` padding nothing goes to left out), their edges by how each ends, and the run over them by the moment shown and nothing after (design/README.md, Forbidden): each block's visits, each edge's count, the last three edges taken, the pc's block, counted where one stop in the function follows another across an edge (`exact`: by instruction; by line, visits only). Laid out from the code alone (`place`: never the run's counts), in two forms (`Blocks.form`): `rings` wherever the function has a loop (natural loops merged by header, back edges by the walk from the entry in address order; each a ring, its pills upright at their centres clockwise from the header at 9 o'clock, radius as its pills need, 12 apart and 24 of arc between two; a nested loop a smaller ring outside its parent touching it at its header, the parent's 3 o'clock; an edge to the next pill an arc of its ring cut at the pills' frames, the back edge round the ring's foot, a fork inside a loop an arc 30 inside, a way out along the tangent out of the pill's foot 30 in from its far end, then quarter circles of 16; outside every loop the blocks as `layers` lays them, the entry left of the header, the blocks after under it; `3 turns` 30 under the ring's centre, from the first) and `layers` (layers by the longest path, a block under its fall-through predecessor, a taken target right of it, back edges up lanes on the left, every corner a quarter circle of 12; panning by thirds round the pc's pill where it is taller than its pane). A block a pill 24 high: its offset, the program's callees after it, faint (the tracer's `__zt_*` left out), its visits ranged right, room kept for `×99` so it never widens as the run counts; not reached yet on the page, `rule` framed, faint, no count; the pc's framed gold 3. Edges not taken yet `rule`, taken `dim`, the trail's golds, the newest 3. Too big for its pane (`layout`), the blocks not reached by the scene's first moment fold (`cursor.first`: the code beyond each way the run had not taken, `+5b … · 7`), keeping a fold's room; a fold opens when the run reaches a block of it and never closes (`unfold`: the pills beyond make room 24 f, `glide`, the fold's blocks fade in quiet 12 f, 2 f apart, then the mark lands). `leave` and `turn` along the curves (12 f and 2 f a 100 units, 12 to 42 f; the turn's count at the ring's centre armed as the mark leaves the latch, struck as it lands); `reach` (the edge from `rule` to gold under the mark, the pill filling page to `raised` 12 f, `×1` in 6 f and struck). Kept per function, form, room, first moment and open folds (`memo`), counted again each frame. On the map the drawing is the lens's at its size over the source, the disassembly linear beside it (`Rules`) | | | `blocks` lens | `src/graph.zig` (`Blocks`), `theme.layout.split.blocks` | its drawing the graph, 880 by 344 over the program column (`rings`, or `layers` for a function with no loop: `Blocks.form`); no view: its rows are the disassembly under the source (eleven), each block's first row ruled with its visits, the thread from the source's line to them; the state column the registers and a stack of twenty from its top | -| | `hexdump` | `src/hexdump.zig` | malloc's words: a field read as `size` (`0x20 a m P`, the bits as rip's flags) or `protected` (`→ 405050 ^ 405`, `NULL ^ 405`, its arc to the pointer it protects), and a field's `note` (Go 18 faint: `key`, `top`, `slots left`); a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; a row whose bytes the step changed where the recording saw no write (memory nothing watches, read anew at a stop), or that became known, crossfading over 12 f (`rowPasses`); one reading for every dump (`hexdump.reading`), a list a character apart, a typed number as its type reads (`char` quoted, `bool` by name); the address room once a dump, by its widest; `Dump`, a view of a region by the fields a scene gives it (`Field`: where, how long, read as a number, big-endian or not, a pointer, text, or left to the eye), the rows that hold a field and a `more` row for each stretch left out, and where those rows outnumber the window, a window kept round the first row a mark or the step is on, the rest folded into `more` rows; marks the scene plays, and the step's only from the stop it came in at (`since`); the bytes a syscall was given as the kernel took them (`given`), and only what the debugger read at the stop (`seen`) | +| | `hexdump` | `src/hexdump.zig` | malloc's words: a field read as `size` (`0x20 a m P`, the bits as rip's flags) or `protected` (`→ 405050 ^ 405`, `NULL ^ 405`, its arc to the pointer it protects), and a field's `note` (Go 18 faint: `key`, `top`, `slots left`); a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; a row whose bytes the step changed where the recording saw no write (memory nothing watches, read anew at a stop), or that became known, crossfading over 12 f (`rowPasses`); one reading for every dump (`hexdump.reading`), a list a character apart (a pointer's arrow keeps its own room, no character before it, as in a chain), a typed number as its type reads (`char` quoted, `bool` by name); the address room once a dump, by its widest; `Dump`, a view of a region by the fields a scene gives it (`Field`: where, how long, read as a number, big-endian or not, a pointer, text, or left to the eye), the rows that hold a field and a `more` row for each stretch left out, and where those rows outnumber the window, a window kept round the first row a mark or the step is on, the rest folded into `more` rows; marks the scene plays, and the step's only from the stop it came in at (`since`); the bytes a syscall was given as the kernel took them (`given`), and only what the debugger read at the stop (`seen`) | | | `loupe` | `src/loupe.zig` (`canim.loupe`, `Loupe.open`, `.close`) | from a register, a loupe's field, or a dump's row read by the scene's fields (`.row`: malloc's tcache, `num_slots[0]` and `entries[0]`, the rest `more`); five rows round a pointer's target, lifted (`color.lift`, `lift_tag`, `shade` 12 and 16; 20 and 26 deeper), hanging from its pointer (its tag on the row's foot, 92 left of the digits, clamped to the stage), a 4-high bracket under the digits its stem, the target's fields framed bright; one opened from the band's view lies over the stack, never the registers, its stem down the gutter's right lane (x 962), its fields struck once it has opened (6 f after, 6 f apart: `Fields.struck`); a deeper one with no room to the right hangs under the one it opens from, its stem down to its tag; a note that does not fit is cut at a word with `…`; `open` 36 f (read 6, stem and rise 18 with the shadow, the frame 6 f after), `close` 12 f; it opens again after a close | -| | lenses: `nodes`, `array`, `calls`, `syscalls`, `backtrace` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`), `src/context.zig` (`Backtrace`, `lens`) | the drawing in `band` (over the program column), its view in `view` (over the state column): `nodes` and `array` a dump (`hexdump.panel`), `calls` the backtrace with arguments, `syscalls` the calls so far as strace writes them (oldest on top, the newest coming in once it is back, held; the rows make room for it, a full log scrolling a row, 24 f, `glide`, but from rest at least a pixel a frame (the rows are drawn on whole pixels), the count above crossfading; out of room a row gives up its faint names first, then its arguments from the right, and keeps what it returned; a path by its string, the kernel's capture where the stop did not read it) over the bytes the call crossing in the step is given or fills (in with the argument framing, 12 f out and 12 f in; what a read fills landing a byte every 2 f, struck, the stack's words with them; a write's buffer framed as read while the kernel takes it; cleared with the log's new row: between crossings `no call crossing now`), `backtrace` (eleven rows as subject, five beside) a `Dump` the scene gives; an `under` pin's names in the order they came, the first left, faded out through the middle of a register's joining or leaving (`Pins.text`); a call node's look (gold, ringed, done) crossfading as the tree's moment changes (6 f), and at a sprint a new node coming in over its step; a left child's result on its left shoulder, off its parent; a view's row a register points into carries the register's `pin` at the row's end (`hexdump` `rowPin`; 48 to the left in a pane, its strip at the right), the reading ending before it; at a sprint the array's pins hold and move where a phrase ends | -| 4 tie | the relations: `thread`, `link` (and its `pin`), `projection`, `touch`, `carry`, `aim`, `echo` | `src/relations.zig` (the tables and the pure passes), `src/ties.zig` (`Ties`, the resolver; `anchor`, `show`, `find`, `of`) | the relations are one data problem (design/README.md, "4. Ties"): each frame's tables are in the frame's own scratch (`sk.Frame.user`, made at its first place: no process globals, two players at once each have theirs): `places` (a key, the place's kind in its top byte and its address below, its box, its pane; struct of arrays) that panels say as they draw (`anchor`), `values` (what a pane shows that may be an address: the value, its box, its pane, the word holding it, a register's index, its panel's rules: `show`, from the registers, the stack's words, a pair's frame), and the facts the panels publish beside them (the stack's window, the touch's row, the thread waiting); both sorted once by key (or value) after a change, a lookup a binary search (`find`), a join a merge of the two sorted sides (`relations.join`). `Ties`, added last, is the resolver, six passes, each a loop over one table: candidates (each kind's join, or the step's events against the places), the knobs (`relations.filter`: a kind whose default is off, `carry` and `aim`, only where the scene turned it on; the budget never turns one on), priority (`byPriority`), the budget (`cut`: the thread; one beat; a link, a projection and a touch, two of them, the touch giving way first; a carry; one aim), then each kind's route and drawing. The kinds are one table of data (`relations.specs`: knob, class, priority, most). Map panels say their places into the map's own tables. `CANIM_RELATIONS=1` says each frame's counts and times on stderr; `zig build bench -- relations` times the passes on a working frame's tables and a map's. The kinds' pictures and timings are as they were: fib, list, zoom, sqlite and column render identical frames before and after (every frame compared). `aim` (`Cursor.aim(s, .standing | .step | .off)`, off by default): a word in memory holding a code address whose row is on screen, out of its panel's rule nearer the gutter, up the left lane (x 950), onto the disassembly's right rule, the row's address framed in code's ink; standing at 60% toward the page, in and out with the knob over 18 f; the step's full ink after the word's strike, back with the advance; written again, its head glides to the new row 24 f after the strike, or it frays (dashed over 12 f, gone over 18 more) where the new value is no code. Draws in the channels: a link climbs to a node by the gutter's left lane and goes down to a slot by the right, its name riding its head, a target past the stack's window a stub and a row count; to a view's row (`dump_pin`) by the left lane, into the row's edge; on a beat the narration names (`Context.tiesWith`, `ties.Beat`): the register framed as read, then its link, held, drawn back with the frame; a projection from the view's bytes, or from a frame's return address to its call's node. Under `tied`, `touch` (`Plan.touch`): from the row's right rule along the gutter's middle lane (x 956) to the word, onto the stack's rule nearer the lane (its right one where the stack stands under the disassembly, a column's beat), in read's or write's colour, the first of the three lines to give way; `carry` (`Levels.carry`, `Plan.carry`): the value's way between a stack word and a register along x 962, primary, an open chevron, `.value` its digits on a raised chip. Places a column's text is level with: `row` (a disassembly's row by its address, a descent's head by `descent.headKey`), `floor`, `block` | +| | lenses: `nodes`, `array`, `calls`, `syscalls`, `backtrace` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`), `src/context.zig` (`Backtrace`, `lens`) | the drawing in `band` (over the program column), its view in `view` (over the state column): `nodes` and `array` a dump (`hexdump.panel`), `calls` the backtrace with arguments, `syscalls` the calls so far as strace writes them (oldest on top, the newest coming in once it is back, held; the rows make room for it, a full log scrolling a row, 24 f, `glide`, but from rest at least a pixel a frame (the rows are drawn on whole pixels), the count above crossfading; out of room a row gives up its faint names first, then its arguments from the right, and keeps what it returned; a path by its string, the kernel's capture where the stop did not read it) over the bytes the call crossing in the step is given or fills (in with the argument framing, 12 f out and 12 f in; what a read fills landing a byte every 2 f, struck, the stack's words with them; a write's buffer framed as read while the kernel takes it; cleared with the log's new row: between crossings `no call crossing now`), `backtrace` (eleven rows as subject, five beside) a `Dump` the scene gives; an `under` pin's names in the order they came, the first left (past the second a count, or with `Nodes.named` by name where they fit before the next node), faded out through the middle of a register's joining or leaving (`Pins.text`); a call node's look (gold, ringed, done) crossfading as the tree's moment changes (6 f), and at a sprint a new node coming in over its step; a left child's result on its left shoulder, off its parent; a view's row a register points into carries the register's `pin` at the row's end (`hexdump` `rowPin`; 48 to the left in a pane, its strip at the right), the reading ending before it; at a sprint the array's pins hold and move where a phrase ends | +| 4 tie | the relations: `thread`, `link` (and its `pin`), `projection`, `touch`, `carry`, `aim`, `echo` | `src/relations.zig` (the tables and the pure passes), `src/ties.zig` (`Ties`, the resolver; `anchor`, `show`, `find`, `of`) | the relations are one data problem (design/README.md, "4. Ties"): each frame's tables are in the frame's own scratch (`sk.Frame.user`, made at its first place: no process globals, two players at once each have theirs): `places` (a key, the place's kind in its top byte and its address below, its box, its pane; struct of arrays) that panels say as they draw (`anchor`), `values` (what a pane shows that may be an address: the value, its box, its pane, the word holding it, a register's index, its panel's rules: `show`, from the registers, the stack's words, a pair's frame), and the facts the panels publish beside them (the stack's window, the touch's row, the thread waiting); both sorted once by key (or value) after a change, a lookup a binary search (`find`), a join a merge of the two sorted sides (`relations.join`). `Ties`, added last, is the resolver, six passes, each a loop over one table: candidates (each kind's join, or the step's events against the places), the knobs (`relations.filter`: a kind whose default is off, `carry` and `aim`, only where the scene turned it on; the budget never turns one on), priority (`byPriority`), the budget (`cut`: the thread; one beat; a link, a projection and a touch, two of them, the touch giving way first; a carry; one aim), then each kind's route and drawing. The kinds are one table of data (`relations.specs`: knob, class, priority, most). Map panels say their places into the map's own tables. `CANIM_RELATIONS=1` says each frame's counts and times on stderr; `zig build bench -- relations` times the passes on a working frame's tables and a map's. The kinds' pictures and timings are as they were: fib, list, zoom, sqlite and column render identical frames before and after (every frame compared). `aim` (`Cursor.aim(s, .standing | .step | .drawn | .off)`, off by default): a word in memory holding a code address whose row is on screen, out of its panel's rule nearer the gutter, up the left lane (x 950), onto the disassembly's right rule, the row's address framed in code's ink, its head 10 by 10; standing at 60% toward the page, in and out with the knob over 18 f (`.drawn`: head first at full ink, 18 f, the address framed as it lands, 6 f); the step's full ink after the word's strike, back with the advance; written again, its head glides to the new row 24 f after the strike, or it frays (dashed over 12 f, gone over 18 more) where the new value is no code. Draws in the channels: a link climbs to a node by the gutter's left lane and goes down to a slot by the right, its name riding its head, a target past the stack's window a stub and a row count; to a view's row (`dump_pin`) by the left lane, into the row's edge; on a beat the narration names (`Context.tiesWith`, `ties.Beat`): the register framed as read, then its link, held, drawn back with the frame, its head fading over the draw-back's last third; a projection from the view's bytes, or from a frame's return address to its call's node. Under `tied`, `touch` (`Plan.touch`): from the row's right rule along the gutter's middle lane (x 956) to the word, onto the stack's rule nearer the lane (its right one where the stack stands under the disassembly, a column's beat), in read's or write's colour, the first of the three lines to give way; `carry` (`Levels.carry`, `Plan.carry`): the value's way between a stack word and a register along x 962, primary, an open chevron, `.value` its digits on a raised chip, `.after_touch` after the instruction's touch to the word (a store's too). Places a column's text is level with: `row` (a disassembly's row by its address, a descent's head by `descent.headKey`), `floor`, `block` | | 5 frame | `map`, `minimap`, `dive`, `surface` | `src/map.zig` (`Map`, `split`, `strip`, `Map.strips`), `Context.map` | the working frame's panels bound to a stage of 3840 by 2160 (`map.split`, packed by content: each box as long as the most rows its panel has wanted, `measure`, the backtrace's as long as the deepest call chain of the scene's way, so that it is packed once; the drawing, the source and under it the backtrace; the disassembly; the view (none where nothing draws one), the registers, and in the column's rest the stack going on, `stack, continued`; the stack from 16 words above rsp; and the first two columns' rest (`Split.spare`) given, in the catalogue's order, to `map.Spare`: a five-row dump round each place the registers (pwndbg's order, not rsp or rbp) and the 64 words up from rsp point at outside the stack and the code, none within another's rows, then the loupes open (`Map.loupes`, lifted, nine rows), then the key (the recording and the moment, the marks as drawn, the inks); only then page); its rows published while `ui.mapping` (the dumps' too); the working windows outlined (2 `dim`, 4 out), each window published with where its step took it from and how far its scroll has gone, so its outline glides; the thread across the gutter (x 1008), gold; a scene without a band can put a drawing on its map (`Map.drawing`); with `Context.Options.graph` the map's drawing is the `blocks` lens's (`graph.Blocks` at its size, 880 by 344, over the source: `split`'s band is the working frame's), the disassembly linear beside it with its blocks ruled. Each pane's minimap (`map.strip`): a strip 40 wide inside its frame at its right, under the tag, on `well` (`theme.strip`), drawn from its column of the map (the source's boxes, the stack's with `stack, continued`, the view's dump; the disassembly's the linear rows round the pc, drawn for the strips alone where the map has a graph or a descent: `Map.In.strips`) at 4 units a row and 36 of 880 across, from what the map drawn for it collects (`ui.strokes`, `ui.collected`: each run of text a stroke 3 high in its ink 65% from the page, the marks 4 by 4 at a row's left in the catalogue's order, an arc with an end off the window a 2-unit line down the left edge, a block's first row ticked); a column longer than the strip the rows round its window, the window in the middle, clamped to the ends, three faint dots where it goes on (fading in over its first row's scroll); the window framed 2 in primary; a mark no working window shows (a word struck or read on the stack or in the view's dump) flashing on its row (a ring 8 to 14 in the mark's colour, 12 f). The strips are one image a frame (`Map.strips`): the map drawn for them six times, each from the cursor's mirror a frame later (6 to 11 f behind: `Cursor.lagInto`) with the panes' windows as long ago (`past`), every strip drawn as it shows (its rows, dots and window in place) and the six averaged, so that every change on a strip fades in over 6 f from 6 f after its onset and nothing on it moves a pixel in a frame; the panes blit their part (source, disassembly and its descent and the `blocks` lens's view, stack, a dump's view: not the registers, a drawing, a loupe, the backtrace, the `syscalls` lens's log). A pane with a strip has 48 less for its rows (`map.content`). `Map.show`, `.dive` (outlines bright 6 f, veil to 24, each panel from its window to its place 60 f, 6 f apart, a panel drawn over another setting off first (drawing, view, disassembly, stack, source, registers) so that none in its place is crossed by one on its way, opaque on the way, its rows on the window's rows, its tag and rules in from 84 f; with each, the rest of its column (the rows its strip shows) squeezing from its place on the map into the strip, its width and height each on its logarithm (to 36 of 880, 4 of 24 a row), its window's outline riding on it, gone into the strip's own drawing over the 12 f before its pane lands (`Map.squeeze`, `stripShows`); the map's other parts fading where they are, 24 to 72; 120 f and 30 f still), `.surface` (the dive back, 84 f, then 30 f still); per-panel transforms through `context.at` (`context.zoomed`); the clock's count ranged right at 1856. `unroll` and `roll` (`Map.unroll`, `.roll`, `map.Unroll`, added over everything by `Context.ties`): the panes veiled and the strip's window framed bright (18 f), the pane's whole column growing out of its strip (36 f, `glide`) to as many rows as the stage holds (24 a row at most; right on the strip's edge, the window's rows level with the pane's where the stage allows), its scale on the logarithm from the strip's, the window's outline riding from the strip to the pane's rows in it; held as the scene says; `roll` the reverse (36 f), the veil lifting (18 f). A far jump in the same column at a walk (the source's window farther than its height to lines the map's column of the file holds too, `source.unrolling`, `inColumn`: no step said faster in a hurry) is `unroll`, the window travelling along the column (24 f, `glide`, the mark lighting gold at its new line as the window gets there, the tag's note changing then), `roll` (96 f: `Cursor.travel`), the pane going into the column and coming out of it at its new place, never a fade. Out of the column (another function, a long file) the map's column goes over as the advance starts, so the strip (6 to 11 f behind, a 6 f crossfade) shows where the pane goes before the pane fades through (`over`, `far` on the map at half its height); a window going farther than the column holds keeps its place on the strip until the column goes over (`spanOf2`); the tag's line range changes with the pane's fade; the map's disassembly is measured by the moment the pane shows (a continue repacks the map as the pane gets there), and a recording of breakpoints has its deepest chain read at every stop (`deepest`: the backtrace's box packed once) | | | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject`, `blocks` (`theme.layout.split`, layout A: the disassembly under the source in every split; the source 14, 8, 8 and 6 lines, the disassembly 17, 17, 11 and 11 rows; `blocks` a drawing of 880 by 344 over the program column and no view, the state column the registers' and the stack's from the top), each for a registers panel of eleven rows; `layout.fit` gives the scene's registers their rows and the stack the rest above the backtrace, whole slots, any rest above it (`Stage.registers_rows`: every split a `relayout` goes to keeps them); the band is `band` (the drawing) and `view`; `relayout` fades the drawing round its move; `holdStack` holds the stack's window for the camera, with `free` slots; `glide` (a column's moves: no fit, no fade), `column` (the clock under the text column), `zoom` (the band's drawing drawn larger, its tag not: `graph.Blocks`) | | | `column` | `src/column.zig` (`Column`, `canim.column`, `beat`) | the shelf (y 48: each folded pane's tag in the frame's order, its note: the scene's, or computed for the registers (those the step changed, the first's value struck as on its row, crossfading with the strike), the source (`line 12`) and the disassembly (`jne 4011af`), crossfading with the advance); the panes from 84 to 1032, 12 apart; texts: `beside` (Go 40 on 54, at most 40 characters a line, 16 of padding, on `raised` while newest, dimming to `dim` without paper, three at most, level with their row, riding it until the panes change or the row goes, an older one gliding above the newest's place or under it), `below` (the caption band), `above` (a band over the drawing), `on` (where the scene puts it, its stem round the drawing's top lane); the change between beats (`change`: fade 6 f, fold where it stands and the tag to the shelf 18 f, glide 24 f (a pane crossing to the other column going down its own first, then across, 24 f each), unfold 18 f, fade in 6 f; a pane that changes its height keeps its rows: `Stage.resizing`, the descent's two layouts glided between, the source's window glided); a stem about a folded pane to its tag; `Beat.held`, and a bubble read past its beat flagged on stderr | -| | `segments` | `src/segments.zig` (`read`, `Segments`, `Place`) | the address space to true scale from the recording's mappings (permissions, file offsets), the tracer's own (its ring, its preloaded agent and the agent's bss) left out: a slim bar the column's height, its ends' addresses and its size; clusters split at gaps of 16 MiB or more, and a band eight times the rest of its cluster in a box of its own; `enlarge` a box at a time (its bands with start, end and size, leaders to the bar), 108 wide; an edge's address in the ink of the band that starts there; a file name past the column's edge cut with `…`; kept above y 888 under the camera (`clipStage`) | -| | the introduction's dump | `src/regroup.zig` (`Words`) | 128 bytes sixteen a row, no ink, the addresses faint; `regroup` to eight a row (bytes become words, low byte last; a word in the top four rows has no room over it at x2, so its bytes fly under it, over the veiled rows, and its offsets and labels stand over it, the header veiled with the rest), `ink`, `extend`, `become` (the bytes go, then the words and addresses glide into the stack panel's rows); with no heap word in the bytes, the first other address is framed | +| | `segments` | `src/segments.zig` (`read`, `Segments`, `Place`) | the address space to true scale from the recording's mappings (permissions, file offsets), the tracer's own (its ring, its preloaded agent and the agent's bss) left out: a slim bar the column's height, its ends' addresses and its size; clusters split at gaps of 16 MiB or more, and a band eight times the rest of its cluster in a box of its own; `enlarge` a box at a time (its bands with start, end and size, leaders to the bar), 108 wide; an edge's address in the ink of the band that starts there; a file name past the column's edge cut with `…`; kept above y 888 under the camera (`clipStage`); `Place`, a dump's place on it (the `tie` and the `link`), and for a camera's visit the place marked on its box (`tick`: a 2-unit line across the box in the stack's ink, `128 bytes` over it) | +| | the introduction's dump | `src/regroup.zig` (`Words`) | 128 bytes sixteen a row, no ink, the addresses faint, its header the address it starts at; `regroup` to eight a row (bytes become words, low byte last, a word that is no address with `0x`; a word in the top four rows has its offsets over it in the header's row (veiled with the rest), `low byte` left of `+0` and `high byte` right of `+7`, and its bytes fly over that row, 40 up, each with its offset over it, one in the air at a time (24 f each, 18 f apart: the 36 f of motion.md, 6 f apart, crossed in the air there), a label going as its byte lifts and coming as it lands; nothing printed over a row), `fold` (the rows glide up into the header, 24 f, the header becomes the tag, which goes to the shelf, 24 f), `ink`, `extend`, `become` (the bytes go, then the words and addresses glide into the stack panel's rows); with no heap word in the bytes, the first other address is framed | | | `aligned` | `src/aligned.zig` | the source and its instructions in one panel, each line level with its code: `interleaved` and `columns`; the lines without their indent; the mnemonics after the longest instruction's bytes; the pc's row annotated (what it reads, its chain); `decode` (an instruction's bytes to its row), `align` (one form to the other: the bytes go first, then the columns glide) and `stack` (to the working frame: the heads' paper, rules and tag out 12 f, the lines to the source panel's rows 36 f, the instructions down their column 24 f and into the disassembly's rows 24 f, those its window does not show fading past its edge; the scene fades the panels in under them) | -| | a text standing alone | `src/aside.zig` (`Aside`, `Asides`) | a column's bubble where no `Column` stands (the introduction's texts beside, and the one on the map); a newline breaks where the author says; one the new text would stand on leaves first, then a gap; `shortcut:` it repeats `column.zig`'s bubble drawing | +| | a text standing alone | `src/aside.zig` (`Aside`, `Asides`) | a column's bubble where no `Column` stands (the introduction's texts beside, and above its aligned code, two lines of 80 characters there: `Asides.wrap`); a newline breaks where the author says; one the new text would stand on leaves first, then a gap; `shortcut:` it repeats `column.zig`'s bubble drawing | | | a caller's rows alone, a stack built a column at a time | `src/descent.zig` (`Caller`), `src/context.zig` (`Stack.reveal`) | `Caller`: a descent's head row over a call, the row it returns to and the next, each a `row` place for an `aim` (chapter II's main); `reveal`: the stack's offsets, roles and spans each under the page until the scene's clock lets them in top down (`column`, 2 f apart, 12 f each) | | | `pair` | `src/pair.zig` (`split`, `Frame`, `Report`, `Marks`, `Clock`, `Shelf`) | two runs on either side of the seam (design/README.md, `pair`): `split` each side's stage; `Frame` a frame as bytes eight a row read by its fields (`hexdump` `eight`: fields live from a moment, the letters keeping a string's ink in a pointer's field, the shadow byte of each row beside it, tall in the column, its words said as values for the relations); `Report` a stopped run's stderr in place of its registers; `Marks` `only here`, `differs`, `attention` and the `fault` (hazard bands round an ink plaque, SIGSEGV); `Clock` one rule and each run's moment; `Shelf` a folded side's tag | | | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the clock still while a step plays, its piece fading in once the mark lands; a caption stays its reading time; the title card is `scenes/title.zig` | @@ -279,7 +288,7 @@ before. The source panel follows the pc into any file it has | `musl` | `hello.c` again, built by Zig for `x86_64-linux-musl`, static, `-O0 -g` (musl compiled from its sources with it: no PLT, its lines its own) | every instruction, `--from main`, `--steps 166` (to main's return) | 173, 55 KB | reads `tools/note` | | `gallery` | the old `list` by line, kept in `test/gallery/list.ztrace`; for the graph pages `sort` and `hello` as recorded on 11 November (with blocks), kept in `test/gallery/sort.ztrace` and `hello.ztrace` (`gallery_sort`, `gallery_hello`) | | 134, 88 KB; 776 KB; 87 KB | the gallery's pictures depend on the drawing only | | `sqlite` | `sqlite.c` (three rows into a table, committed) with SQLite 3.50.4's amalgamation, system clang `-O2 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector -Wl,-z,now`, glibc | `--by break`: `sqlite3_step`, `sqlite3BtreeInsert`, `unixWrite`, and the instruction after its `pwrite64` (found by objdump); every syscall recorded, `-s 4096` | 181 (42 stops, 138 syscalls), 494 KB | made only with `-Dsqlite=DIR` (default `~/05-genizah/sqlite/sqlite-amalgamation-3500400`), in a new temporary directory each time; `sqlite3.c` is embedded as the source | -| `intro` | `list.c` again, as `list` is built | every instruction, `--from list.c:41` (main's call of reverse), `--until list.c:22` (past the load); run as `./list` | 588 (70 of them the loader's and the agent's syscalls before main), 187 KB | as `list`: `--alloc --preload`, `--ring` | +| `intro` | `list.c` again, as the compiler alone makes it: the system's clang `-O0 -g -mno-red-zone -no-pie -fno-stack-protector -Wl,-z,now`, glibc, no instrumentation (no red zone: reverse's prologue is `push rbp; mov rbp, rsp; sub rsp, 0x18`, its locals at `rbp-8`, `-0x10`, `-0x18`) | every instruction, `--from list.c:41` (main's call of reverse), `--until list.c:22` (past the load); run as `./list` | 74 (60 of them the loader's and the agent's syscalls before main), 54 KB | `--alloc --preload` (the allocations), `-w head`; its locals named by the debug info (`zt.telescope.slots`); the types the nodes lens needs (`head`, `struct node`) declared by chapter III (`Recording.declare`): the tracer reads none from the debug info | | `overflow` | `overflow.c` (design/mock/overflow.c: a loop writing 32 bytes into `char buf[16]`), the system's clang `-O0 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector`, glibc | every instruction, `--from main`, to the fault | 298, 60 KB | the recorder says `exit 139`; the SIGSEGV on the moment after `ret`, rip unchanged | | `overflow_asan` | the same with `-fsanitize=address`, `ASAN_OPTIONS=detect_leaks=0` | every instruction, `--from main`, `--until __asan_report_store1` (its first stop there: past its `endbr64; push rbp; mov rbp, rsp`, as `-b` places a function's breakpoint) | 788, 257 KB | `--asan` (the shadow); the fake frame's header parsed by the scene from memory; the scene finds its moments by what the instructions are (the parting turn's load, `je`, the partial check's `cmp` and branch, the call), none by a count | | `overflow_report` | the same run | `--by syscall --stack 0 --telescope 0 -s 4096` | 707, 401 KB | the report: its `write(2, …)`s, shown from their capture; `exit 1` | @@ -289,10 +298,18 @@ Zig's build (`addExecutable`, musl, static); `hello.c` for `hello`, `heap.c` and `sqlite.c`, the system's clang against the system's glibc, dynamically (`hello`'s PLT and GOT are the scene, as a C programmer's build lays them; the heap scene is glibc's own allocator; `sqlite` is -built as the bench builds it, and its scene is glibc's `pwrite64`); +built as the bench builds it, and its scene is glibc's `pwrite64`; `list.c` +for `intro` likewise, with its own flags: `Recording.cc`); `list.c` and `sort.c`, `ztrace cc`, the system's clang with the instrumentation pass, a plugin of that clang's LLVM. +A recording of a program built without the pass tells no variables: a +scene declares the globals and named types it draws in the pass's notation +(``Recording.declare("head", "*`struct node`")``), a global found at the +address the recording names `head+0`; `Recording.variable` gives a local +of the newest frame by the debug info (its slot's name), assigned once a +store has touched it since its call began. + Every recording the build makes carries each function's blocks (`zt.telescope.blocks`, at the first stop in it) and a `branch` event at each stop on a jump: the graph and the linear rows' block rules read them. @@ -354,37 +371,77 @@ list's dive (150 to 300 f) as a caption's change. | | fib | list | sort | syscalls | musl | zoom | sqlite | heap | gallery | title | column | column_sort | asan | intro_memory | intro_stack | intro_code | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| POP, before / after | 3 / 3 | 10 / 10 | 4 / 4 | 14 / 13 | 7 / 7 | 2 / 2 | 6 / 6 | 15 / 15 | 9 / 9 | 0 / 0 | 4 / 4 | 6 / 6 | 29 / 16 | 1 / 1 | 0 / 0 | 0 / 0 | -| of them the strips', before / after | 1 / 1 | 4 / 4 | 3 / 3 | 9 / 9 | 1 / 1 | 1 / 1 | 0 / 0 | 5 / 4 | 3 / 3 | 0 / 0 | 2 / 2 | 3 / 3 | 0 / 0 | – | – | – | +| POP, before / after | 3 / 3 | 10 / 10 | 4 / 4 | 13 / 13 | 7 / 7 | 2 / 2 | 6 / 6 | 15 / 15 | 9 / 9 | 0 / 0 | 4 / 4 | 6 / 6 | 16 / 16 | 1 / 1 | 0 / 0 | 0 / 0 | +| of them the strips', before / after | 1 / 1 | 4 / 4 | 3 / 3 | 9 / 9 | 1 / 1 | 1 / 1 | 0 / 0 | 4 / 4 | 3 / 3 | 0 / 0 | 2 / 2 | 3 / 3 | 0 / 0 | – | – | – | | POP exempt, before / after | | keyframe 1 / keyframe 1 | | | | | | | cut 5 / cut 5 | | | | | | | | -| CROWD, before / after | 3 / 3 | 7 / 7 | 8 / 8 | 4 / 4 | 6 / 6 | 3 / 3 | 2 / 2 | 17 / 16 | 5 / 5 | 0 / 0 | 0 / 0 | 0 / 0 | 15 / 15 | 0 / 0 | 0 / 0 | 0 / 0 | +| CROWD, before / after | 3 / 3 | 7 / 7 | 8 / 8 | 4 / 4 | 6 / 6 | 3 / 3 | 2 / 2 | 16 / 16 | 5 / 5 | 0 / 0 | 0 / 0 | 0 / 0 | 15 / 15 | 0 / 0 | 0 / 1 | 0 / 0 | | METRONOME, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | CAPTION up over 720 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | 0 / 0 | 1 / 1 | 1 / 1 | 1 / 1 | 0 / 0 | 0 / 0 | | CAPTION under its reading time, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | | not checked | not checked | not checked | not checked | not checked | not checked | -| CAPTION picture moving within 60 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | not checked | 1 / 1 | not checked | 1 / 1 | 0 / 0 | 1 / 1 | -| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 | -| seconds, before / after | 48.2 / 48.2 | 83.9 / 83.9 | 74.5 / 74.5 | 85.4 / 85.4 | 66.8 / 66.8 | 34.9 / 34.9 | 62.9 / 62.9 | 80.2 / 80.2 | 27.0 / 27.0 | 12.3 / 12.3 | 95.3 / 95.3 | 29.5 / 29.5 | 120.0 / 120.0 | 67.2 / 67.2 | 31.8 / 31.8 | 40.8 / 40.8 | +| CAPTION picture moving within 60 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | not checked | 1 / 1 | not checked | 1 / 1 | 0 / 0 | 1 / 0 | +| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 1 | 1 / 1 | 1 / 0 | +| seconds, before / after | 48.2 / 48.2 | 83.9 / 83.9 | 74.5 / 74.5 | 85.4 / 85.4 | 66.8 / 66.8 | 34.9 / 34.9 | 62.9 / 62.9 | 80.2 / 80.2 | 27.0 / 27.0 | 12.3 / 12.3 | 95.3 / 95.3 | 29.5 / 29.5 | 120.0 / 120.0 | 67.2 / 70.0 | 31.8 / 42.5 | 40.8 / 44.8 | -"Before" is the last pass's "after". This pass exported again (at 1080, -and at 2160 where a scene has one) asan, fib, zoom, syscalls, the column, -musl, list, sort, heap, the gallery and the title; sqlite, column_sort and -the introduction's three (`intro_memory`, `intro_stack`, `intro_code`) -were not, and their cells repeat the last pass's. The column's, column_sort's and asan's "caption" regions are not a -caption's (the text column, a drawing's band), so their CAPTION lines are -not a caption's; the column's own check is the renderer's (`column: bubble N -is still read …`): C2's bubble (74 characters) 1.8 s past its three steps. +"Before" is the last pass's "after". This pass exported again (at 1080 +and 2160) the introduction's three (`intro_memory`, `intro_stack`, +`intro_code`) alone; every other scene's cells repeat the last pass's. The +column's, column_sort's and asan's "caption" regions are not a caption's +(the text column, a drawing's band), so their CAPTION lines are not a +caption's; the column's own check is the renderer's (`column: bubble N is +still read …`): C2's bubble (74 characters) 1.8 s past its three steps. The introduction's texts beside are not in the caption band either: in -`intro_memory` the band is empty for the column part (21.7 to 43.4 s), which -the instrument reads as one caption up 22 s with the picture moving; in -`intro_code` the caption leaving before `surface` (33.1 s) is read as one -arriving; the reading times are the scenes' own (`Narrator`, `Asides`: each -text waits until the last is read). `intro_memory`'s POP (31.20) is the -first `enlarge`'s line framed bright, 2 units over its 6 f (looked at, frame -by frame: it comes in over the 6 f; the instrument counts 75 pixels, then -36). The two AIRs are the chapters' last pictures, II4's and III5's texts -read and the 2 s before the cut. +`intro_memory` the band is empty for the column part (from 21.6 s), which +the instrument reads as one caption up 22 s with the picture moving; the +reading times are the scenes' own (`Narrator`, `Asides`: each text waits +until the last is read). `intro_memory`'s POP (38.70) is the program's +`enlarge`, its line framed bright at the stage's foot (looked at, frame by +frame: it changes from 38.62, 12 pixels, growing). `intro_stack`'s CROWD +(23.32) is the push's advance: the pc's mark moving down reverse's rows, +the registers' marks and the stack's cooling, as every walked step's +advance does where the three panels stand (the last pass's II showed no +code). I's and II's AIR is the chapter's last picture, the last text read +and the 2 s before the cut (III ends as the map surfaces under its text). + +This pass changed (the introduction, a correction round after a review of +its three chapters frame by frame): + +- The recording `intro` is the plain build (`-O0 -g -mno-red-zone`, no + instrumentation; `Recording.cc`), so II walks reverse's own `push rbp; mov + rbp, rsp; sub rsp, 0x18` and III's map has no tracer's calls; the nodes + lens reads the types the scene declares and the locals the debug info + names (`Recording.declare`, `Recording.variables`, `Recording.variable`). +- I: the first text names only what will be on screen (`here are 128 of + them`; the header `128 bytes at 7fffffffebc8`; the tag `the 128 bytes`), + the bytes come a lead after it, 18 f apart; the walked word's bytes fly + over it, one in the air at a time, nothing printed over a row of memory; + the fold glides the rows into the header, which becomes the tag; the + rows' addresses take the stack's ink as the box lights; the visit is at + x2 framing the box and the dump's top rows, the place ticked `128 bytes` + (`Place.tick`), no label cut at the frame's edge; `0x` on a word that is + no address; I5 says each file, I10 the arrows. +- II: the convention said where the stack first stands (lower addresses + drawn higher), four `free` words over rsp held (no row moves); the call + before the push, rsp's link to its word as II2 names it; the aim drawn head first at full ink (`Cursor.aim(.drawn)`, + its head 10), then 60%; reverse's first rows a disassembly under main's, + the push walked with its touch and rbp's value carried to the word + (`Levels.carry = .after_touch`) and struck though unchanged; rbp's row with + rsp's; `the way back` on return addresses, `0x` on offsets of 10 and more + (`Levels.introduction`); `rbp marks the frame's base`. +- III: II's state column stays, veiled, until the decoded code spans it; + `Later, at line 21`, rax's link to its node; III2 says each line heads its instructions; the width + squares and the minimaps said; node 9's pin `head cur rax` in full + (`Nodes.named`), its row `9 → 405030` (a dump's pointer reading lost the + character before its arrow, every dump: the gallery's pictures drawn + anew); the map's text lands before `surface`, a caption. +- What reaches past the introduction (those scenes not exported again): an + aim's head is 10 by 10 (asan's was 8); a beat's link (`tiesWith`) fades + its head over its draw-back's last third (sqlite's went in a frame); a + dump's pointer reading has no character before its arrow (list, heap, + sqlite, the gallery); `Cursor.jumpWalked` (a cut that leaves the steps' + history), `Asides.wrap`, `Stack.Reveal.apart`, `Nodes.named` and + `Place.tick` are new and off by default. -This pass changed: +The pass before changed: - The ASan run is recorded `--until __asan_report_store1` (no count), and the scene finds its moments by what the instructions are; the pair's @@ -418,7 +475,7 @@ This pass changed: it is inside a step by line, so rbp lands on the saved rbp's row, not rsp's (f586 to f623, smooth). fib's and zoom's counts are unchanged. -The pass before (the introduction) changed, outside its three scenes: a pin +The pass before that (the introduction) changed, outside its three scenes: a pin joining another's row in front of its names (`mov rbp, rsp`: rbp onto rsp) lets its own head go as it lands, not in the advance's frame (`Stack`); the pc's triangle on `aligned`'s plaque is drawn where it is (it was transformed @@ -561,29 +618,47 @@ What fires still (the finals; located where it says so): header is parsed by the scene from memory, plain's fields from the instructions' rbp offsets, and the two runs' stops are matched by pc. - The introduction (`intro_memory`, `intro_stack`, `intro_code`), exported: - where it differs from its storyboard and mocks. The recording is `intro` - (main's call of reverse to past the load), so the push II walks is - reverse's own `push rbp` and I's 128 bytes are at rsp at that push (the - return address the top word); the return address is `main+50` - (`402412`), not the storyboard's `main+80`. I (67 s against 66): the - walked word is the top row, with no room over it at x2, so its bytes fly - under it (mock 37 flies them over); a library's file name past the - column's edge is cut (`ld-linux-x86-64…`; mock 34 says `ld.so`); the - instrument's one POP (31.2 s) is the first `enlarge`'s line framed - bright, 2 units over 6 f, looked at. II (32 s against 26.5): `mov rbp, - rsp` and `sub rsp` are walked too, so rbp's pin and the frame's span come - from the recording, not drawn on; its registers are canim's folded - layout at x1 (mock 31: seventeen rows at x1.25), so the stack keeps its - eighteen rows; main's rows fade at III's opening rather than staying - under III's disassembly (III's code is reverse's). III (41 s against - 30.3): it opens on II's last picture, which gives way (the held corners - of II's last step are not on it); `columns` (mock 36) is a beat of its - own after `interleaved`; no camera (at x1.5 the band's nodes and its - dump do not both fit, and the storyboard's "out to x1" has no "in"); the - minimaps draw themselves 48 f apart (the long text would stand still - over 3 s); the map's text is a bubble on the map's empty middle foot. - The caption checks cannot pair the texts beside with the caption band, - so their reading times are the scenes' own (`Asides`, `Narrator`). + where it differs from its storyboard and mocks. The recording is `intro`, + the plain build (main's call of reverse to past the load), so the push II + walks is reverse's own `push rbp`, I's 128 bytes are at rsp at that push + (the return address the top word, `main+50`, `401272`, not the + storyboard's `main+80`), and the frame is `sub rsp, 0x18`. The types + chapter III's nodes are drawn by are declared by the scene from `list.c` + (`Recording.declare`): the tracer reads no types from the debug info, + only the locals' names and places. I (70 s against 66): the walked word + is the top row, with two rows of room over it at x2: its offsets stand in + the header's row, `low byte` and `high byte` outside them, and its bytes + fly over that row (40 up) one at a time (24 f each, 18 f apart; motion.md's 36 f, + 6 f apart, crossed in the air there), each label going as its byte lifts + and coming as it lands; a library's file name past the column's edge is + cut (`ld-linux-x86-64…`; mock 34 says `ld.so`); the visit is at x2 (the + storyboard's x4 showed the box alone, cut its names), the dump's rows + running on past the frame's right edge at a byte's edge. II (42.5 s + against 26.5): six beats (the convention, rsp, the call, the push, the + frame, the registers), the call before the push; reverse's rows are a + disassembly panel of seven rows under main's three (its tag with the + stack's, `frame up`); its registers canim's folded layout at x1 (mock 31: + seventeen rows at x1.25), so the stack keeps twenty rows, four of them + `free` over rsp and held; the push's store of the value its word held is + struck (the catalogue arms it alone); a return address's role is `the way + back` (II4's words; `return address` would cut `main+50`); main's rows go + at III's opening (III's code is reverse's). III (44.8 s against 30.3): it + opens on II's last picture (as II walked it: `Cursor.jumpWalked`), its + state column veiled until the decoded code spans it (the review said until + `align`: the interleaved panel spans the state column, and its code + printed over the veiled stack); `columns` (mock 36) is a beat of its own; + no camera (at x1.5 the band's nodes and its dump do not both fit); the + texts above take two lines of 80 characters (the band of 120); node 9's + row in the dump reads `9 → 405030` beside `◂rax`, which stays at the row's + end (the review asked for it in the address gutter, where the arcs' lanes + leave no room), node 12's still `12 …` beside `◂rcx`; the minimaps draw + themselves 72 f apart, the decoded rows come 4 f apart and `align` takes + 120 f (the texts are long, and would stand still over 3 s); II's offsets + and roles come down the rows 4 f apart (`Stack.Reveal.apart`); the map's text is a caption, landing before + `surface`. The strips fill in over III's first 10 frames (no lagged + windows yet), as before. The caption checks cannot pair the texts beside + with the caption band, so their reading times are the scenes' own + (`Asides`, `Narrator`). - The relations: arcs within a panel (the stack's, a dump's, a loupe's) are still each panel's own (`rows.Arcs`, lanes per panel), not rows of the frame's tables; the column's stems are drawn by the column, their diff --git a/anim/build.zig b/anim/build.zig index 7022caa..2263c61 100644 --- a/anim/build.zig +++ b/anim/build.zig @@ -105,6 +105,8 @@ pub fn build(b: *std.Build) void { /// code to follow down): `-no-pie` for short addresses, bound at /// load (`-z now`: no resolver), with the canary the compiler puts in. glibc: bool = false, + /// The compiler's command for a `glibc` build, in place of its own. + cc: ?[]const []const u8 = null, /// Stops after `from` before the recording ends: main's return, not the exit's. steps: ?[]const u8 = null, /// Ends the recording at the first stop here (`--until`). @@ -134,9 +136,12 @@ pub fn build(b: *std.Build) void { // (the agent's and the runtime's first calls) run through. .{ .name = "sort", .source = "sort.c", .by = "insn", .instr = "vars", .only = "sort,a", .from = "main" }, .{ .name = "list", .source = "list.c", .by = "insn", .instr = "vars", .only = "push,reverse,head", .from = "reverse", .alloc = true }, - // The introduction's: the same program from main's call of reverse - // (its push of the way back, reverse's prologue) to line 22, past the load. - .{ .name = "intro", .source = "list.c", .by = "insn", .instr = "vars", .only = "push,reverse,head", .from = "list.c:41", .until = "list.c:22", .alloc = true, .program = "list" }, + // The introduction's: the same program as the compiler alone makes it + // (no tracer's calls in reverse; no red zone, so its prologue makes + // room for its locals: `push rbp; mov rbp, rsp; sub rsp, 0x18`; its + // locals named by the debug info), from main's call of reverse to + // line 22, past the load; `head` watched, the global the list hangs from. + .{ .name = "intro", .source = "list.c", .by = "insn", .glibc = true, .cc = &.{ "clang", "-O0", "-g", "-mno-red-zone", "-no-pie", "-fno-stack-protector", "-Wl,-z,now" }, .from = "list.c:41", .until = "list.c:22", .alloc = true, .watch = &.{"head"}, .program = "list" }, // `hello` again, built by Zig against musl, static: no PLT; musl's // own source (`open.c`, `syscall_cp`) on the way down to the kernel. .{ .name = "musl", .source = "hello.c", .by = "insn", .from = "main", .steps = "166", .reads = "note" }, @@ -158,7 +163,7 @@ pub fn build(b: *std.Build) void { cc.addArg("-o"); program = cc.addOutputFileArg(r.name); } else if (r.glibc) { - const cc = b.addSystemCommand(&.{ "clang", "-O0", "-g", "-no-pie", "-fstack-protector-strong", "-Wl,-z,now" }); + const cc = b.addSystemCommand(r.cc orelse &.{ "clang", "-O0", "-g", "-no-pie", "-fstack-protector-strong", "-Wl,-z,now" }); cc.addFileArg(source); cc.addArg("-o"); program = cc.addOutputFileArg(r.name); diff --git a/anim/scenes/intro_code.zig b/anim/scenes/intro_code.zig index b50c971..cbfa36b 100644 --- a/anim/scenes/intro_code.zig +++ b/anim/scenes/intro_code.zig @@ -6,13 +6,16 @@ //! of `aligned` (`interleaved`), its neighbours at a run, each line level //! with its run; then `align` to `columns`; then the working frame with the //! nodes drawn from the heap's bytes, each pane's minimap drawing itself -//! last; then the map (`surface`). The texts `above` the aligned panel, -//! then below the working frame, and the last one on the map. +//! last; then the map (`surface`). It opens on chapter II's last picture, +//! its state column staying veiled until the decoded code spans it. The +//! texts `above` the aligned panel, then below the working frame, the +//! last landing before the map surfaces under it. const std = @import("std"); const anim = @import("anim"); const sk = @import("sketch"); const canim = @import("canim"); const recordings = @import("recordings"); +const two = @import("intro_stack.zig"); pub const background = canim.background; pub const scene = anim.Live(frame, struct {}); @@ -45,43 +48,33 @@ const Page = struct { /// Chapter II's last picture (scenes/intro_stack.zig, its layout and texts /// as there): its registers and stack, a context of their own at II's last -/// moment; main's rows, faint; II3's text dimmed and II4's. -fn lastOfTwo(s: *anim.Frame, rec: *canim.Recording) struct { panels: [3]anim.Obj, texts: [2]anim.Obj } { +/// moment, the window held as II holds it; main's rows, faint, and reverse's +/// first rows under them; II4's text dimmed and II5's. +fn lastOfTwo(s: *anim.Frame, rec: *canim.Recording) struct { state: [2]anim.Obj, code: [2]anim.Obj, texts: [2]anim.Obj } { const enter = rec.call("reverse", 0).enter; const last = enter + 3; - const row = canim.theme.metric.context.row; - const head = canim.theme.metric.context.tag + canim.theme.metric.context.pad; var at = canim.cursor(s, rec, enter); at.journey(.moment, last); - at.levels = .{ .fire = .disasm, .source_rows = 14 }; - at.jump(s, last); + at.levels = .{ .fire = .disasm, .source_rows = 14, .introduction = true }; + // As II walked it: its push, `mov` and `sub` the steps behind its last moment. + at.jumpWalked(s, enter, last); var split = canim.layout.split.none; split.backtrace.h = 0; const ctx = canim.context(s, at, .{ .split = split }); - const rb = ctx.stage.first.registers; - ctx.stage.first.stack.h = canim.layout.panelH(18); - ctx.stage.first.stack.y = rb.y + rb.h + canim.theme.canvas.row_gap; - const top = ctx.stage.first.stack.y + head; - const rsp = rec.register(enter, "rsp"); - const window = rec.register(last, "rsp") - 16; - const rowY = struct { - fn y(t0: f32, from: u64, addr: u64) f32 { - return t0 + row * @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% from)) >> 3)); - } - }.y; + const g = two.layout(ctx.stage, rec, enter); + two.hold(s, ctx.stage, enter); const stack = canim.add(s, canim.Stack{ .cursor = ctx.cursor, .stage = ctx.stage }); - const back_y = rowY(top, rsp - 8 - 16, rsp); // (Placed at the origin: it draws at its own box.) - const caller = s.custom(s.new(canim.descent.Caller{ .rec = rec, .at = enter, .call = rec.register(enter - 1, "rip"), .box = .{ .x = canim.theme.layout.program.x, .y = back_y + row / 2 + 176, .w = canim.theme.layout.program.w, .h = 4 * row }, .in = s.value(999), .faint = s.value(1) }), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); + const caller = s.custom(s.new(canim.descent.Caller{ .rec = rec, .at = enter, .call = rec.register(enter - 1, "rip"), .box = g.caller, .in = s.value(999), .faint = s.value(1) }), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); const left = canim.theme.canvas.margin_x; const said = [2]canim.Aside{ - .{ .text = "A function's words are its frame: the saved rbp, its locals, the way back.", .x = left, .level = (rowY(top, window, window + 16) + rowY(top, window, rsp + 8)) / 2, .dim = s.value(1) }, - .{ .text = "The registers are the other place values live: seventeen of them.", .x = left, .level = rb.y + head + row * 2.5, .dim = s.value(0) }, + .{ .text = two.texts[two.texts.len - 2], .x = left, .level = g.span_y, .dim = s.value(1) }, + .{ .text = two.texts[two.texts.len - 1], .x = left, .level = g.registers_y, .dim = s.value(0) }, }; var texts: [2]anim.Obj = undefined; for (said, &texts) |a, *o| o.* = s.custom(s.new(a), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); - for ([_]anim.Obj{ ctx.registers, stack, caller, texts[0], texts[1] }) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - return .{ .panels = .{ ctx.registers, stack, caller }, .texts = texts }; + for ([_]anim.Obj{ ctx.registers, stack, caller, ctx.disasm, texts[0], texts[1] }) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + return .{ .state = .{ ctx.registers, stack }, .code = .{ caller, ctx.disasm }, .texts = texts }; } /// The variables whose tags the nodes carry, as the list scene's. @@ -89,6 +82,10 @@ const tracked = [_][]const u8{ "prev", "cur", "next", "head" }; fn frame(s: *anim.Frame) void { const rec = canim.open(recordings.intro); + // list.c's types as the pass would tell them: the recording is of the + // plain build, which tells none (its locals are the debug info's). + rec.declare("head", "*`struct node`"); + rec.declare("`struct node`", "struct(16){value@0:i64;next@8:*`struct node`;}"); const reverse = rec.call("reverse", 0); // The load: `cur->next` read, line 21's second instruction. const moment = on(rec, rec.lineMoment(21, reverse.enter), "[rax + 8]"); @@ -109,11 +106,12 @@ fn frame(s: *anim.Frame) void { var at = canim.cursor(s, rec, moment); at.journey(.moment, moment + 1); - at.levels = .{ .idea = .data, .follow = t.move, .source_rows = 8 }; + at.levels = .{ .idea = .data, .follow = t.move, .source_rows = 8, .introduction = true }; const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject }); - const list = canim.nodes(s, .{ .cursor = at, .stage = ctx.stage, .root = "head", .track = &tracked }); - ctx.map.add(s, canim.Nodes{ .cursor = at, .stage = ctx.map.stage, .root = "head", .track = &tracked }); - const joins = ctx.ties(s); + const list = canim.nodes(s, .{ .cursor = at, .stage = ctx.stage, .root = "head", .track = &tracked, .named = true }); + ctx.map.add(s, canim.Nodes{ .cursor = at, .stage = ctx.map.stage, .root = "head", .track = &tracked, .named = true }); + // The relations, and rax's link to the node as III3 names it. + const joins, const rax_link = ctx.tiesWith(s, "rax", 1.0); // Each pane's minimap under the page until III4, where they draw themselves last, top down // (over the panels, under the aligned rows landing on them; on from the panels' first frame). @@ -125,15 +123,17 @@ fn frame(s: *anim.Frame) void { const al = s.new(canim.Aligned.init(s, rec, moment)); const panel = s.custom(al, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); s.play(.{panel.fadeIn()}, .{ .seconds = 0 }); - var asides: canim.Asides = .{}; + // Texts above the panel that spans both columns: twice a beside's line (two lines in the band of 120). + var asides: canim.Asides = .{ .wrap = 2 * 40 }; const left = canim.theme.canvas.margin_x; const above = canim.theme.canvas.stage.y + 40; - // From II's last picture: it gives way (its texts 12 f, the rest 18 f), the stage clear for the code. + // From II's last picture: its texts and code give way (12 f, 18 f); its + // state column stays, veiled at 50%, until the decoded code takes both columns. s.wait(t.beat); s.play(.{ opening.texts[0].fadeOut(), opening.texts[1].fadeOut() }, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); s.cursor -= t.caption_out; - s.play(.{ opening.panels[0].fadeOut(), opening.panels[1].fadeOut(), opening.panels[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear }); + s.play(.{ opening.code[0].fadeOut(), opening.code[1].fadeOut(), opening.state[0].move(.{ .opacity = 0.5 }), opening.state[1].move(.{ .opacity = 0.5 }) }, .{ .seconds = f(18), .ease = anim.ease.linear }); s.wait(t.beat); // III1: the code's bytes, one instruction's framed. @@ -142,16 +142,23 @@ fn frame(s: *anim.Frame) void { run(s, al.bytes, 12 + 2 * 15 + 12 + 6); s.wait(t.beat); - // III2: decoded into its row, its neighbours at a run, each line level with its run. - asides.say(s, std.fmt.allocPrint(s.arena, "Decoded: `{s}`, from line {d}. Each line sits level with its code.", .{ text, insn.line orelse 0 }) catch "", left, above); + // III2: decoded into its row, its neighbours at a run, each line heading its run. + asides.say(s, std.fmt.allocPrint(s.arena, "Decoded: `{s}`, from line {d}. Each line heads the instructions it compiled to.", .{ text, insn.line orelse 0 }) catch "", left, above); + // II's state column goes as the decoded rows come to span it (12 f). + s.play(.{ opening.state[0].fadeOut(), opening.state[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.cursor -= f(12); run(s, al.decode, 60); - run(s, al.rows_in, 2 * 32 + 8); + // The neighbours at half the run's pace (rows 4 f apart): they come while the text is read. + s.play(.{al.rows_in.to(0)}, .{ .seconds = 0 }); + s.play(.{al.rows_in.to(2 * 32 + 8)}, .{ .seconds = 2 * f(2 * 32 + 8), .ease = anim.ease.linear }); run(s, al.chrome, 24); s.wait(t.beat); // III2, the other form: two columns, each line level with the first of its instructions. - asides.say(s, "Two columns: each line level with its first instruction.", left, above); - run(s, al.form, 80); + asides.say(s, "Two columns: each line by its first instruction. A square after `]`: a byte it touches.", left, above); + // `align` at two thirds of its pace (120 f for 80): the two columns come while the text is read. + s.play(.{al.form.to(0)}, .{ .seconds = 0 }); + s.play(.{al.form.to(80)}, .{ .seconds = f(120), .ease = anim.ease.linear }); s.wait(t.beat); // Into the working frame: the texts above leave; `stack`: the lines glide to @@ -168,7 +175,7 @@ fn frame(s: *anim.Frame) void { // III3: the node it reads, as bytes and drawn: the band comes in, its // elements rising from their bytes. No camera: at x1.5 the drawing's // nodes and its bytes do not both fit the frame, and the band is whole at x1. - says.line(s, "`rax` points at a list node on the heap:\nits bytes, and drawn, the node."); + says.line(s, "Later, at line 21, `rax` points at a list node on the heap:\nits bytes, and drawn, the node."); // The heap's dump first, in the band's right half (18 f); then the nodes drawn from it, rising (`establish`). s.play(.{ctx.stage.drawing.to(0)}, .{ .seconds = 0 }); s.play(.{list.fadeIn()}, .{ .seconds = f(18), .ease = anim.ease.linear }); @@ -177,20 +184,21 @@ fn frame(s: *anim.Frame) void { s.cursor -= f(12); ctx.establish(s, .{}, 3); s.wait(t.beat); - // III4: the whole frame; each pane's minimap draws itself, last, top down (24 f, 48 f apart). - says.line(s, "This is the whole frame.\nEvery view in it is these same bytes."); + // rax framed as read, its link up to the node it points at, held, drawn back. + rax_link.play(s); + s.wait(rax_link.total()); + s.wait(t.beat); + // III4: the whole frame; each pane's minimap draws itself, last, top down (24 f, 72 f apart: while the text is read). + says.line(s, "This is the whole frame. Every view in it is these same bytes;\neach strip, the whole of its pane."); const strips_from = s.cursor; for (strips, 0..) |o, k| { - s.cursor = strips_from + f(48 * @as(f32, @floatFromInt(k))); + s.cursor = strips_from + f(72 * @as(f32, @floatFromInt(k))); s.play(.{o.fadeOut()}, .{ .seconds = f(24), .ease = anim.ease.linear }); } s.wait(t.beat); - // III5: the map, and its text on it, in the key's corner (the middle column's foot, empty on this map). - s.wait(@max(says.read_by - s.cursor, 0)); - s.play(.{says.current.?.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); - s.wait(t.caption_gap); + // III5: its text lands before the move, under the map as under the frame; then `surface`. + says.line(s, "And all of it at once: the map."); ctx.map.surface(s); - asides.say(s, "And all of it at once:\nthe map.", 528, 720); - s.wait(@max(asides.read_by - s.cursor, 0)); + s.wait(@max(says.read_by - s.cursor, 0)); s.wait(t.before_cut); } diff --git a/anim/scenes/intro_memory.zig b/anim/scenes/intro_memory.zig index 7aec267..2dfda5e 100644 --- a/anim/scenes/intro_memory.zig +++ b/anim/scenes/intro_memory.zig @@ -8,7 +8,8 @@ //! made words (`regroup`); three of them addresses; then the address space //! to scale in the program column (`segments`), each cluster enlarged, its //! text beside it; back to the working frame, the dump tied to its place, -//! a visit at x4, `ink`, and three chains. +//! a visit at x2 framing the stack's box and the dump's top rows together +//! (the place marked `128 bytes` on the box), `ink`, and three chains. const std = @import("std"); const anim = @import("anim"); const canim = @import("canim"); @@ -45,7 +46,7 @@ fn frame(s: *anim.Frame) void { const space = s.new(canim.Segments.init(s, rec, moment)); const dump = s.new(canim.Words.init(s, rec, moment)); - const place = s.new(canim.segments.Place{ .segments = space, .addr = rec.register(moment, "rsp"), .x = at.bracket, .y0 = at.top + 2, .y1 = at.top + 16 * 24 - 2, .clock = s.value(-1), .quiet = s.value(0) }); + const place = s.new(canim.segments.Place{ .segments = space, .addr = rec.register(moment, "rsp"), .x = at.bracket, .y0 = at.top + 2, .y1 = at.top + 16 * 24 - 2, .clock = s.value(-1), .quiet = s.value(0), .tick = s.value(0) }); // `ink`'s echoes: the walked word's band first, then the rest at a run, 2 f apart. const values = canim.Words.read(rec, moment); @@ -64,8 +65,10 @@ fn frame(s: *anim.Frame) void { const objs = .{ s.custom(space, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(dump, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(place, .{ .x = -640, .y = -360, .scale = ui.scale }) }; inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - // The camera at x2 on the dump from the first frame (I1 to I3). - const near = ui.framing(.{ .x = 888, .y = 72, .w = 896, .h = 408 }, 2); + // The camera at x2 on the dump from the first frame (I1 to I3), with the + // room over it that the walked word's bytes and offsets fly in, and its + // sixteen rows over the stage's foot. + const near = ui.framing(.{ .x = 888, .y = 66, .w = 896, .h = 408 }, 2); var cam: canim.Camera = .{}; cam.moves[0] = .{ .from = near, .to = near, .p = s.value(1) }; cam.count = 1; @@ -73,15 +76,20 @@ fn frame(s: *anim.Frame) void { var says: canim.Narrator = .{}; var asides: canim.Asides = .{}; - // I1: the bytes, a row at a time. + // I1: the bytes, a row at a time (18 f apart), a text's lead (60 f) after it lands, not + // the first's 120: little "here" over an empty stage, and they come while it is read. s.wait(1.0); - says.line(s, "A running program is bytes in memory:\nhere, 128 of them at the top of the stack."); - run(s, dump.in, 7 * 12 + 18); + const said_at = s.cursor; + says.line(s, "A running program is bytes in memory:\nhere are 128 of them."); + const lead_end = s.cursor; + s.cursor = said_at + t.caption_in + t.caption_lead; + run(s, dump.in, 7 * canim.regroup.rows_apart + 18); + s.cursor = @max(s.cursor, lead_end); s.wait(t.beat); // I2: eight a row; the return address walked, the other fifteen at a run. says.line(s, "Eight bytes make a word, stored low byte first:\nthe lowest byte is its last two digits."); - run(s, dump.regroup, 386); + run(s, dump.regroup, canim.regroup.regroup_frames); s.wait(t.beat); // I3: three words that hold addresses, framed as read. @@ -94,7 +102,7 @@ fn frame(s: *anim.Frame) void { says.current = canim.caption(s, ""); s.wait(t.caption_gap); cam.back(s, .{}); - run(s, dump.fold, 30); + run(s, dump.fold, 48); // Folded, the three frames go with the rows: unfolded, the dump is plain words again. s.play(.{dump.framed.to(-1)}, .{ .seconds = 0 }); @@ -109,7 +117,7 @@ fn frame(s: *anim.Frame) void { const clusters = @min(l.space.clusters.len, 6); var top_end: usize = 0; while (top_end < clusters and l.space.clusters[top_end].lo > canim.segments.user_end / 2) top_end += 1; - asides.say(s, "Enlarged, the top end: the stack, then the libraries, each band with its addresses and size.", column_x, l.boxes[0].y + 12); + asides.say(s, "Enlarged, the top end: the stack, then the libraries, each file with its addresses and size.", column_x, l.boxes[0].y + 12); for (0..top_end) |i| { start(s, space.rides[i], 6 + 72 + 90 + 2 * 12 + 12); s.wait(f(78)); @@ -125,21 +133,28 @@ fn frame(s: *anim.Frame) void { // Back to the working frame: the texts leave, the drawing to the stage's height, the dump unfolds. asides.leave(s); s.play(.{space.form.to(1)}, .{ .seconds = f(24), .ease = anim.ease.linear }); - s.play(.{dump.fold.to(0)}, .{ .seconds = f(30), .ease = anim.ease.linear }); + s.play(.{dump.fold.to(0)}, .{ .seconds = f(48), .ease = anim.ease.linear }); // I7: the dump's place: the tie bracket, the link onto the stack's box. says.line(s, "These 128 bytes are here,\nat the very top of the stack."); - s.play(.{dump.placed.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); - s.cursor -= f(12); + // The rows' addresses take the stack's ink as the link's head lands and its band is framed (42), 12 f. + const placing = s.cursor; run(s, place.clock, 60); + const placed_at = s.cursor; + s.cursor = placing + f(42); + s.play(.{dump.placed.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.cursor = placed_at; s.wait(t.beat); // I8: a visit at x4 to where the link lands, and back. says.line(s, "Were the bar the Eiffel Tower,\nthey would be an atom thick, at its top."); + // At x2: the stack's box with its names, the link, and the dump's top rows to a byte's edge, + // the place marked on the box (`128 bytes`), nothing cut at the frame's edge but the rows running on. const landed = space.layout(1, s.arena); - const head = canim.Segments.place(landed, place.addr) orelse .{ 0, 0 }; - cam.go(s, .{ .x = head[0] - 112, .y = 48, .w = 224, .h = 104 }, 4, .{}); - s.wait(t.beat); + cam.go(s, .{ .x = 280, .y = 44, .w = 960, .h = 448 }, 2, .{}); + s.play(.{place.tick.?.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.wait(1.0); + s.play(.{place.tick.?.to(0)}, .{ .seconds = f(12), .ease = anim.ease.linear }); cam.back(s, .{}); // I9: `ink`: the return address walked, its band framed; the rest at a run; the link quiets. @@ -164,7 +179,7 @@ fn frame(s: *anim.Frame) void { s.wait(t.beat); // I10: the words to their field's left, then three chains, walked. - says.line(s, "Follow an address and you reach another word:\na chain."); + says.line(s, "Follow an address and you reach another word: a chain.\n`→` points to a word, `←` holds a value."); run(s, dump.left, 24); run(s, dump.chains, 36 * 2 + 30); s.wait(t.beat); diff --git a/anim/scenes/intro_stack.zig b/anim/scenes/intro_stack.zig index 49162e6..378d624 100644 --- a/anim/scenes/intro_stack.zig +++ b/anim/scenes/intro_stack.zig @@ -1,18 +1,23 @@ //! The introduction, chapter II: the stack (design/motion.md, "A scene: the -//! introduction", II1 to II4; mock 31). It opens on chapter I's last -//! picture, at the same moment of the `intro` recording (reverse's first -//! instruction, its `push rbp`): the address space and the dump's link +//! introduction", II1 to II4, here six beats; mock 31). It opens on chapter +//! I's last picture, at the same moment of the `intro` recording (reverse's +//! first instruction, its `push rbp`): the address space and the dump's link //! fade, the words glide into the stack panel's rows where it stands in the -//! working frame (sixteen of them and two `free` over rsp) and become it. -//! rsp's row arrives over the stack and its pin lands on the top word; the -//! push walked from the recording (rsp's pin climbing onto the saved rbp). -//! The way back main left framed, main's three rows round its call arriving -//! in the program column, the word aimed at the row it returns to (`aim`, -//! this beat only), the offsets a `column`. rbp's row and pin, `mov rbp, -//! rsp` and `sub rsp` walked: the frame; its roles and spans, a `column` -//! each, the panel's tag last (`frame up`). Then the registers built over -//! it a row at a time, their tag last. The text stands beside on the left, -//! in the program column, empty until chapter III but for main's rows. +//! working frame (sixteen of them and four `free` over rsp, the window held +//! there so that nothing in the panel moves while the frame is made) and +//! become it; the convention said there (lower addresses drawn higher), the +//! offsets coming down the rows. rsp's and rbp's rows arrive over the stack, +//! rsp's pin landing on the top word. The call first: the way back main +//! left framed, main's three rows round its call arriving in the program +//! column, the word aimed at the row it returns to (`aim`, drawn head first, +//! standing at 60% through the push). Then reverse's first rows under +//! main's (the disassembly) and `push rbp` walked: the pc's mark on its +//! row, the touch to the word, rbp's value carried to it and struck, rsp's +//! pin climbing. `mov rbp, rsp` and `sub rsp` walked: the frame; its roles +//! (the way back named) and spans, a `column` each, the panels' tags last +//! (`frame up`). Then the registers built over it a row at a time, their +//! tag last. The text stands beside on the left, in the program column, +//! over the code. //! //! What a beat has not reached yet is under the page (`Cover`, and the //! stack's own `reveal`), lifted as the beat says it: the context's panels @@ -99,36 +104,30 @@ fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { fn frame(s: *anim.Frame) void { const rec = canim.open(recordings.intro); const reverse = rec.call("reverse", 0); - // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x20`. + // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x18`. const moment = reverse.enter; const framed = moment + 3; var at = canim.cursor(s, rec, moment); at.journey(.moment, framed); - at.levels = .{ .fire = .disasm, .source_rows = 14 }; + at.levels = .{ .fire = .disasm, .source_rows = 14, .introduction = true }; var split = canim.layout.split.none; split.backtrace.h = 0; const ctx = canim.context(s, at, .{ .split = split }); - // Sixteen slots and the headroom under the registers' box (the words - // become them where they stand), not the column's rest. + const g = layout(ctx.stage, rec, moment); + const sb = g.stack; const rb = ctx.stage.first.registers; - ctx.stage.first.stack.h = canim.layout.panelH(18); - ctx.stage.first.stack.y = rb.y + rb.h + canim.theme.canvas.row_gap; - const sb = ctx.stage.first.stack; - const rsp = rec.register(moment, "rsp"); - // The window has two `free` words over rsp; rows from the panel's tag and padding. - const first = rsp - 16; - const top = sb.y + tag + pad; + const rsp = g.rsp; + const first = g.first; + const top = g.top; const slots = canim.layout.rowsIn(sb.h); - const rowY = struct { - fn y(t0: f32, from: u64, addr: u64) f32 { - return t0 + row * @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% from)) >> 3)); - } - }.y; + // The window held where it is, four `free` words over rsp: the push and `sub rsp` fill them. + hold(s, ctx.stage, moment); // The panels and the page over what they have not said yet, first: chapter I's // picture, the words gliding into the stack among them, draws over them. // The stack, its offsets, roles and spans under the page until their beats. - const reveal: canim.Stack.Reveal = .{ .offsets = s.value(-1), .roles = s.value(-1), .spans = s.value(-1) }; + // (Rows 4 f apart: the offsets come down while the convention is read.) + const reveal: canim.Stack.Reveal = .{ .offsets = s.value(-1), .roles = s.value(-1), .spans = s.value(-1), .apart = 4 }; const stack = canim.add(s, canim.Stack{ .cursor = ctx.cursor, .stage = ctx.stage, .reveal = reveal }); // The registers, under the page: rbp's and rsp's rows (the scene's two, the first two), the rest, the chrome. s.play(.{ctx.registers.fadeIn()}, .{ .seconds = 0 }); @@ -137,10 +136,13 @@ fn frame(s: *anim.Frame) void { // (From the third row on 2 higher: the rule over the folded rows goes with them.) regs_rows[k] = cover(s, .{ .x = rb.x + 2, .y = rb.y + tag + pad + row * @as(f32, @floatFromInt(k)) - @as(f32, if (k >= 2) 2 else 0), .w = rb.w - 4, .h = row + @as(f32, if (k >= 2) 2 else 0) }); const regs_chrome = chrome(s, rb, false); - // The pins' lane under the free words: rsp's row's lifted with rsp, the rest with rbp. + // The pins' lane: rsp's row's lifted with rsp, the rest (rbp's pin) with the push. var lane: [32]?anim.Obj = @splat(null); - for (2..@min(slots, 32)) |k| lane[k] = cover(s, .{ .x = sb.x + 2, .y = top + row * @as(f32, @floatFromInt(k)), .w = 116, .h = row }); + const rsp_row: usize = held_free; + for (0..@min(slots, 32)) |k| lane[k] = cover(s, .{ .x = sb.x + 2, .y = top + row * @as(f32, @floatFromInt(k)), .w = canim.theme.metric.slot.lane_end - 2, .h = row }); const stack_chrome = chrome(s, sb, true); + // Reverse's first rows, the disassembly under main's: its rows with the push, its tag and strip last. + const disasm_chrome = chrome(s, ctx.stage.first.disasm, true); // Chapter I's last picture: the address space, the words with their chains, the link standing. const space = s.new(canim.Segments.init(s, rec, moment)); @@ -152,69 +154,92 @@ fn frame(s: *anim.Frame) void { set(s, space.whole, 999); for (space.rides) |v| set(s, v, 999); for ([_]anim.Value{ dump.in, dump.ink, dump.chains }) |v| set(s, v, 999); - set(s, dump.regroup, 386); + set(s, dump.regroup, canim.regroup.regroup_frames); set(s, dump.left, 24); const objs = .{ place(s, space), place(s, dump), place(s, tie) }; inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - // main's rows, in the program column under II2's text; the aim joins them to the word. - const rsp_after = rec.register(moment + 1, "rsp"); - const back_y = rowY(top, rsp_after - 16, rsp); - const main_rows = s.new(canim.descent.Caller{ .rec = rec, .at = moment, .call = rec.register(moment - 1, "rip"), .box = .{ .x = canim.theme.layout.program.x, .y = back_y + row / 2 + 176, .w = canim.theme.layout.program.w, .h = 4 * row }, .in = s.value(-1), .faint = s.value(0) }); + // main's rows, in the program column over reverse's; the aim joins them to the word. + const back_y = rowY(top, first, rsp); + const main_rows = s.new(canim.descent.Caller{ .rec = rec, .at = moment, .call = rec.register(moment - 1, "rip"), .box = g.caller, .in = s.value(-1), .faint = s.value(0) }); s.play(.{place(s, main_rows).fadeIn()}, .{ .seconds = 0 }); const main_word: canim.Rect = .{ .x = sb.x + canim.theme.metric.slot.address + 12 * 12 + canim.theme.metric.context.arrow_w, .y = back_y, .w = @as(f32, @floatFromInt(canim.ui.digits(rec.register(moment - 1, "rip") + 5))) * 12, .h = row }; const word_frame = place(s, s.new(Read{ .box = main_word })); - const joins = ctx.ties(s); + // The relations, and rsp's link to its word as II2 names it. + const joins, const rsp_link = ctx.tiesWith(s, "rsp", 1.0); s.play(.{joins.fadeIn()}, .{ .seconds = 0 }); var asides: canim.Asides = .{}; const left = canim.theme.canvas.margin_x; // II1: the address space and the link fade (18 f); the words glide into - // the stack's rows (36 f) and become the panel (12 f). + // the stack's rows (36 f) and become the panel (12 f). Where it first + // stands, its convention said, unlike the bar's: the offsets come down + // its rows (a column, 4 f apart), growing as the addresses do. s.wait(t.beat); s.play(.{ objs[0].fadeOut(), objs[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear }); s.play(.{dump.become.to(1)}, .{ .seconds = f(36), .ease = anim.ease.linear }); s.play(.{ stack.fadeIn(), objs[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); - asides.say(s, "`rsp` holds the address of the top of the stack. A push moves it down a word.", left, rowY(top, first, rsp) + row / 2); - // rsp's row arrives over the stack (12 f), then its pin lands on the top word (12 f). - lift(s, &.{regs_rows[1]}, 0, 12); - lift(s, &.{lane[2]}, 0, 12); + asides.say(s, texts[0], left, rowY(top, first, first) + row / 2); + const column = reveal.apart * @as(f32, @floatFromInt(slots)) + 12; + run(s, reveal.offsets, column); + s.wait(t.beat); + + // II2: rsp's and rbp's rows arrive over the stack (12 f), rsp's pin lands on the top word (12 f), + // then rsp's link from its row down to the word, held, drawn back. + asides.say(s, texts[1], left, back_y + row / 2); + lift(s, &.{ regs_rows[0], regs_rows[1] }, 0, 12); + lift(s, &.{lane[rsp_row]}, 0, 12); + rsp_link.play(s); + s.wait(rsp_link.total()); s.wait(f(18)); - at.walk(s, .moment, moment + 1); s.wait(t.beat); - // II2: the way back main left, framed; main's rows; the aim; the offsets, a column. - asides.say(s, "A call pushes the address to come back to: here, `main+50`.", left, back_y + row / 2); + // II3: the call, first: the way back main left, framed; main's rows; the aim drawn to its row. + asides.say(s, texts[2], left, back_y + row / 2); s.play(.{word_frame.fadeIn()}, .{ .seconds = f(6), .ease = anim.ease.linear }); s.wait(f(12)); run(s, main_rows.in, 12 + 2 * 2 + 12); s.wait(f(6)); - at.aim(s, .standing); - s.wait(f(30)); - run(s, reveal.offsets, 2 * @as(f32, @floatFromInt(slots)) + 12); + at.aim(s, .drawn); + s.wait(f(24 + 30)); s.wait(t.beat); - // II3: rbp's row and its pin; the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tag last. - const rsp_framed = rec.register(framed, "rsp"); - const span_y = (rowY(top, rsp_framed - 16, rsp_framed) + rowY(top, rsp_framed - 16, rsp + 8)) / 2; - asides.say(s, "A function's words are its frame: the saved rbp, its locals, the way back.", left, span_y); - at.aim(s, .off); + // II4: the push: reverse's first rows under main's, rbp's pin; `push rbp` walked + // (its row fires, the touch to the word, rbp's value carried there and struck, rsp's pin climbing). + asides.say(s, texts[3], left, rowY(top, first, rsp - 8) + row / 2); + at.aim(s, .standing); s.play(.{ word_frame.fadeOut(), main_rows.faint.to(1) }, .{ .seconds = f(18), .ease = anim.ease.linear }); - lift(s, &.{regs_rows[0]}, 0, 12); - lift(s, lane[3..], 2, 12); + s.play(.{ctx.disasm.fadeIn()}, .{ .seconds = f(12), .ease = anim.ease.linear }); + var lanes: [32]?anim.Obj = lane; + lanes[rsp_row] = null; + lift(s, &lanes, 0, 12); s.wait(f(12)); + at.levels.carry = .after_touch; + at.walk(s, .moment, moment + 1); + at.levels.carry = .off; + s.wait(t.beat); + + // II5: the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tags last. + asides.say(s, texts[4], left, g.span_y); + at.aim(s, .off); at.walk(s, .moment, moment + 2); at.walk(s, .moment, framed); - run(s, reveal.roles, 2 * @as(f32, @floatFromInt(slots)) + 12); - run(s, reveal.spans, 2 * 4 + 12); + run(s, reveal.roles, column); + run(s, reveal.spans, reveal.apart * 4 + 12); s.wait(t.beat); - // `frame up`: its rules (12 f), then its tag and strip (12 f). + // `frame up`: the rules (12 f), then the tags and strips (12 f). + const at_rules = s.cursor; + lift(s, disasm_chrome[1..4], 0, 12); + s.cursor = at_rules; lift(s, stack_chrome[1..4], 0, 12); + const at_tags = s.cursor; + lift(s, &.{ disasm_chrome[0], disasm_chrome[4] }, 0, 12); + s.cursor = at_tags; lift(s, &.{ stack_chrome[0], stack_chrome[4] }, 0, 12); s.wait(t.beat); - // II4: the registers built over the stack, a row at a time, their tag last. - asides.say(s, "The registers are the other place values live: seventeen of them.", left, rb.y + tag + pad + row * 2.5); + // II6: the registers built over the stack, a row at a time, their tag last. + asides.say(s, texts[5], left, g.registers_y); lift(s, regs_rows[2..], 12, 12); lift(s, regs_chrome[1..4], 0, 12); lift(s, &.{regs_chrome[0]}, 0, 12); @@ -222,3 +247,46 @@ fn frame(s: *anim.Frame) void { s.wait(@max(asides.read_by - s.cursor, 0)); s.wait(t.before_cut); } + +/// The chapter's texts, in order (chapter III opens on the last two). +pub const texts = [_][]const u8{ + "Here lower addresses are drawn higher: down a word is up a row.", + "`rsp` holds the address of the top of the stack.", + "A call pushes the address to come back to: here, `main+50`.", + "A push moves `rsp` down a word and stores there: `push rbp` keeps the caller's `rbp`.", + "`rbp` marks the frame's base. A function's words are its frame: the saved rbp, its locals, the way back.", + "The registers are the other place values live: seventeen of them.", +}; + +/// Free words over rsp in the held window. +pub const held_free = 4; + +/// The stack's window held from the first frame (no scroll to it), `held_free` words over rsp at `moment`. +pub fn hold(s: *anim.Frame, stage: *canim.Stage, moment: u64) void { + s.play(.{ stage.hold.to(@floatFromInt(moment)), stage.hold_free.to(held_free), stage.hold_in.to(1) }, .{ .seconds = 0 }); +} + +/// Where the chapter's parts stand (chapter III opens on its last picture, +/// laid out the same): the stack under the registers, its window from +/// `first` (four free words over rsp), its rows from `top`; main's rows +/// in the program column level with the lower stack, reverse's under them. +pub fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { stack: canim.Rect, rsp: u64, first: u64, top: f32, caller: canim.Rect, span_y: f32, registers_y: f32 } { + const rb = stage.first.registers; + // Sixteen slots and the headroom under the registers' box (the words + // become them where they stand), not the column's rest. + stage.first.stack.h = canim.layout.panelH(16 + held_free); + stage.first.stack.y = rb.y + rb.h + canim.theme.canvas.row_gap; + const sb = stage.first.stack; + const rsp = rec.register(moment, "rsp"); + const first = rsp - 8 * held_free; + const top = sb.y + tag + pad; + const caller: canim.Rect = .{ .x = canim.theme.layout.program.x, .y = rowY(top, first, rsp) + row / 2 + 152, .w = canim.theme.layout.program.w, .h = 4 * row }; + // Seven rows: reverse's from its first, which none of the chapter's steps scrolls away. + stage.first.disasm = .{ .x = caller.x, .y = caller.y + caller.h + canim.theme.canvas.row_gap, .w = caller.w, .h = canim.layout.panelH(7) }; + const rsp_framed = rec.register(moment + 3, "rsp"); + return .{ .stack = sb, .rsp = rsp, .first = first, .top = top, .caller = caller, .span_y = (rowY(top, first, rsp_framed) + rowY(top, first, rsp + 8)) / 2, .registers_y = rb.y + tag + pad + row * 2.5 }; +} + +fn rowY(t0: f32, from: u64, addr: u64) f32 { + return t0 + row * @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% from)) >> 3)); +} diff --git a/anim/src/Recording.zig b/anim/src/Recording.zig index 4bc9c1b..bcc8903 100644 --- a/anim/src/Recording.zig +++ b/anim/src/Recording.zig @@ -143,6 +143,11 @@ locals: []Declared = &.{}, /// The variables declared outside the stack (globals): bytes a lens draws. globals: []Span = &.{}, strings: std.AutoHashMapUnmanaged(u64, []const u8) = .empty, +/// What a program built without the pass does not tell of itself (the +/// introduction's plain build): its globals' types and its named types, in +/// the pass's notation (`types`), by name (`declare`); its locals are the +/// debug info's (`zt.telescope.slots`), untyped. +declared: std.StringHashMapUnmanaged(u64) = .empty, arena: std.heap.ArenaAllocator, const gpa = std.heap.smp_allocator; @@ -694,7 +699,55 @@ pub fn variable(r: *const Recording, scratch: std.mem.Allocator, m: Moment, text for (all) |v| { if (std.mem.eql(u8, r.name(v.name), text) and (found == null or v.depth > found.?.depth)) found = v; } - return found; + return found orelse if (r.declared.count() > 0) r.plain(m, text) else null; +} + +/// The live variables: the recording's, or a plain build's declared globals. +pub fn variables(r: *const Recording, scratch: std.mem.Allocator, m: Moment) []Variable { + const all = m.variables(scratch) catch return &.{}; + if (all.len > 0 or r.declared.count() == 0) return all; + var out: std.ArrayList(Variable) = .empty; + var it = r.declared.keyIterator(); + while (it.next()) |key| if (key.*[0] != '`') if (r.plain(m, key.*)) |v| out.append(scratch, v) catch break; + return out.items; +} + +/// Declares, for a program built without the pass, global `what`'s type +/// (`text`, in the pass's notation), or a named type's description +/// (`what` in backticks, as a type names it). Once each. +/// shortcut: a scene writes them from the source, as the tracer reads no types from the debug info; upgrade when it does. +pub fn declare(r: *Recording, what: []const u8, text: []const u8) void { + if (r.declared.contains(what)) return; + const a = r.arena.allocator(); + const named = what[0] == '`'; + const id = if (named) types.defId(what[1 .. what.len - 1]) else r.intern(text) catch return; + if (named) r.strings.put(a, id, a.dupe(u8, text) catch return) catch return; + r.declared.put(a, a.dupe(u8, what) catch return, id) catch {}; +} + +/// A plain build's variable `text` at `m`: a declared global, at the +/// address the recording names `text+0` (a word: what a lens hangs from is +/// a pointer); or a local of the newest frame, by the debug info. Its +/// `name` is 0: the recording has no id for it. +fn plain(r: *const Recording, m: Moment, text: []const u8) ?Variable { + if (r.declared.get(text)) |ty| { + var it = r.strings.iterator(); + while (it.next()) |e| { + const s = e.value_ptr.*; + if (e.key_ptr.* >> 63 == 0 and s.len == text.len + 2 and std.mem.startsWith(u8, s, text) and std.mem.endsWith(u8, s, "+0")) + return .{ .addr = e.key_ptr.*, .size = 8, .name = 0, .type = ty, .tid = r.tid, .depth = 0 }; + } + return null; + } + const regs = (m.regs(r.tid) catch null) orelse return null; + var buf: [32]zt.telescope.Slot = undefined; + const slots = zt.telescope.slots(m, ®s, regs.rsp, &buf) catch return null; + for (slots, 0..) |slot, k| if (slot.frame == 0 and slot.role == .local) { + const l = slot.role.local; + if (l.offset == 0 and std.mem.eql(u8, l.name, text)) + return .{ .addr = regs.rsp + 8 * k, .size = l.size, .name = 0, .type = 0, .tid = r.tid, .depth = r.depths[@min(m.index, r.end())] }; + }; + return null; } /// A variable's type, as the compiler pass described it, with a named type @@ -735,7 +788,8 @@ pub fn assigned(r: *const Recording, v: Variable, i: u64) bool { if (c.enter > i) break; if (c.active(i) and c.depth + 1 == v.depth) enter = c.enter; } - return touches(r.written(enter -| 1, i), v.addr, v.size); + // A plain build's local (`plain`): a store of the value its stretch of stack held assigns it too. + return touches(r.written(enter -| 1, i), v.addr, v.size) or (v.name == 0 and touches(r.store_spans.of(enter -| 1, i), v.addr, v.size)); } /// Which allocation ever made holds `addr` at moment `m`: the same number diff --git a/anim/src/array.zig b/anim/src/array.zig index fad10c5..e40c0d2 100644 --- a/anim/src/array.zig +++ b/anim/src/array.zig @@ -248,7 +248,7 @@ pub const Array = struct { for (inks[0..@min(indices, inks.len)]) |*i_ink| i_ink.* = theme.color.region.stack; const pv = u.faded(shows * ties.rise(rising, k, count).element); pv.pinUnderInked(x, top + cell[1], &.{}, &.{}, if (names.items.len > indices) ink else t.primary, label); - pv.faded(text).pinNames(x, top + cell[1], names.items, inks[0..@min(names.items.len, inks.len)], label); + pv.faded(text).pinNames(x, top + cell[1], names.items, inks[0..@min(names.items.len, inks.len)], label, 0); } } diff --git a/anim/src/aside.zig b/anim/src/aside.zig index 5400da5..c2c0ef8 100644 --- a/anim/src/aside.zig +++ b/anim/src/aside.zig @@ -1,7 +1,8 @@ //! A text beside what it speaks of, for a scene that builds its parts in //! place rather than in the column's panes (the introduction): the //! column's `bubble` (design/README.md, "column"), standing alone. Go 40 -//! on 54, code in mono 35, at most 40 characters a line, 16 of padding; +//! on 54, code in mono 35, at most 40 characters a line (twice as many +//! for a text `above` a subject across both columns: `Asides.wrap`), 16 of padding; //! the newest on `raised` paper, primary; an older one loses its paper and //! dims to `dim` (`dim`, 18 f). It arrives rising 8 (its object's fade, //! 18 f, `enter`) and leaves with its fade (12 f, `exit`). No stem: its @@ -28,10 +29,12 @@ pub const Aside = struct { level: f32, /// 0 newest, 1 the account (no paper, `dim`). dim: anim.Value, + /// Characters a line, at most. + wrap: usize = chars, pub fn draw(a: *const Aside, f: *sk.Frame, placed: anim.Placed) void { const u = (ui.Ui{ .f = f, .at = placed }).moved(0, (1 - placed.pose.opacity) * theme.time.caption_rise); - const wrapped = wrap(u, a.text); + const wrapped = wrap(u, a.text, a.wrap); const top = a.level - first; const h = first * 2 + @as(f32, @floatFromInt(wrapped.len - 1)) * line_pitch; var w: f32 = 0; @@ -54,13 +57,15 @@ pub const Asides = struct { spans: [8][2]f32 = undefined, n: usize = 0, read_by: f32 = 0, + /// Characters a line, at most, of the texts it says. + wrap: usize = chars, pub fn say(a: *Asides, s: *anim.Frame, text: []const u8, x: f32, level: f32) void { s.wait(@max(a.read_by - s.cursor, 0)); const dim = s.value(0); - const made = s.new(Aside{ .text = text, .x = x, .level = level, .dim = dim }); + const made = s.new(Aside{ .text = text, .x = x, .level = level, .dim = dim, .wrap = a.wrap }); const obj = s.custom(made, .{ .x = -640, .y = -360, .scale = ui.scale }); - const span = [2]f32{ level - first, level + first + @as(f32, @floatFromInt(lines(text) - 1)) * line_pitch }; + const span = [2]f32{ level - first, level + first + @as(f32, @floatFromInt(lines(text, a.wrap) - 1)) * line_pitch }; const at = s.cursor; var in_the_way = false; for (a.shown[0..a.n], a.dims[0..a.n], a.spans[0..a.n]) |*o, d, other| { @@ -105,7 +110,7 @@ fn easeGlide(x: f32) f32 { } /// How many lines `wrap` makes of `text` (a newline breaks one where the author says). -fn lines(text: []const u8) usize { +fn lines(text: []const u8, most: usize) usize { var count: usize = 0; var paragraphs = std.mem.splitScalar(u8, text, '\n'); while (paragraphs.next()) |paragraph| { @@ -114,7 +119,7 @@ fn lines(text: []const u8) usize { count += 1; while (it.next()) |word| { const seen = (std.unicode.utf8CountCodepoints(word) catch word.len) - std.mem.count(u8, word, "`"); - if (n > 0 and n + 1 + seen > chars) { + if (n > 0 and n + 1 + seen > most) { count += 1; n = 0; } @@ -135,7 +140,7 @@ fn width(u: ui.Ui, line: []const u8) f32 { /// Lines of at most `chars` visible characters, broken at spaces; a code /// run keeps its backticks on each line it spans. -fn wrap(u: ui.Ui, text: []const u8) []const []const u8 { +fn wrap(u: ui.Ui, text: []const u8, most: usize) []const []const u8 { var out: std.ArrayList([]const u8) = .empty; var paragraphs = std.mem.splitScalar(u8, text, '\n'); while (paragraphs.next()) |paragraph| { @@ -145,7 +150,7 @@ fn wrap(u: ui.Ui, text: []const u8) []const []const u8 { while (it.next()) |word| { const seen = std.unicode.utf8CountCodepoints(word) catch word.len; const ticks = std.mem.count(u8, word, "`"); - if (n > 0 and n + 1 + seen - ticks > chars) { + if (n > 0 and n + 1 + seen - ticks > most) { out.append(u.f.scratch, line.items) catch break; line = .empty; n = 0; @@ -164,10 +169,10 @@ fn wrap(u: ui.Ui, text: []const u8) []const []const u8 { } test "lines of at most forty characters, backticks not counted" { - try std.testing.expectEqual(@as(usize, 1), lines("Its address space, 128 TiB, to scale.")); - try std.testing.expectEqual(@as(usize, 2), lines("Its address space, 128 TiB, to scale: mapped only at each end.")); + try std.testing.expectEqual(@as(usize, 1), lines("Its address space, 128 TiB, to scale.", chars)); + try std.testing.expectEqual(@as(usize, 2), lines("Its address space, 128 TiB, to scale: mapped only at each end.", chars)); // Four code runs of nine: 39 shown, 47 with their backticks. - try std.testing.expectEqual(@as(usize, 1), lines("`012345678` `012345678` `012345678` `012345678`")); + try std.testing.expectEqual(@as(usize, 1), lines("`012345678` `012345678` `012345678` `012345678`", chars)); // A newline breaks where the author says. - try std.testing.expectEqual(@as(usize, 2), lines("And all of it at once:\nthe map.")); + try std.testing.expectEqual(@as(usize, 2), lines("And all of it at once:\nthe map.", chars)); } diff --git a/anim/src/context.zig b/anim/src/context.zig index 7d56c62..874a22a 100644 --- a/anim/src/context.zig +++ b/anim/src/context.zig @@ -391,7 +391,8 @@ pub fn frameBase(rec: *const Recording, i: u64, regs: zt.Regs) Base { /// `d` bytes from base `name` (`rbp-18`, `rbp+8`, `rbp`), as the stack's tag writes a range. fn fromBase(u: ui.Ui, name: []const u8, d: i64) []const u8 { - return if (d == 0) name else if (d > 0) u.print("{s}+{x}", .{ name, @as(u64, @intCast(d)) }) else u.print("{s}-{x}", .{ name, @as(u64, @intCast(-d)) }); + const p = rows.hexMark(@abs(d)); + return if (d == 0) name else if (d > 0) u.print("{s}+{s}{x}", .{ name, p, @as(u64, @intCast(d)) }) else u.print("{s}-{s}{x}", .{ name, p, @as(u64, @intCast(-d)) }); } /// A frame's span on the stack: its function's name, and as a call its @@ -472,15 +473,16 @@ pub const Stack = struct { /// The stack built a `column` at a time (design/README.md, 6. Verbs: /// `column`; motion.md, chapter II): each part a clock the scene plays /// (frames, negative before it begins), its rows coming in top down as - /// shown, 2 f apart, 12 f each; until then under the page. + /// shown, `apart` frames apart (2 by default), 12 f each; until then under the page. pub const Reveal = struct { offsets: anim.Value, roles: anim.Value, spans: anim.Value, + apart: f32 = 2, /// How much of row (or span) `k`'s part is still under the page, its clock at `clock`. - fn hidden(clock: f32, k: f32) f32 { - return 1 - std.math.clamp((clock - 2 * @max(k, 0)) / 12, 0, 1); + fn hidden(r: Reveal, clock: f32, k: f32) f32 { + return 1 - std.math.clamp((clock - r.apart * @max(k, 0)) / 12, 0, 1); } }; @@ -493,6 +495,8 @@ pub const Stack = struct { const slots = rowsOf(box); const is = (now.moment().regs(rec.tid) catch null) orelse return; const was = (now.before().regs(rec.tid) catch null) orelse is; + rows.prefixed = now.introduction; + defer rows.prefixed = false; // The window: from rsp, or further into the frame ([rsp, rbp+16)) // when that is longer than the panel, so that the word the last // steps touched is in its middle. When a step moves it the rows @@ -729,12 +733,12 @@ pub const Stack = struct { if (y + m.row < body.y or y > box.h) continue; const addr = window[0] +% @as(u64, @bitCast(n * 8)); // Not come in yet (`reveal`): the offset under the page (from past the pins to 172), the role with its row. - const hide_offset = if (k.reveal) |rv| Reveal.hidden(placed.value(rv.offsets), (y - top) / m.row) else 0; - const hide_role = if (k.reveal) |rv| Reveal.hidden(placed.value(rv.roles), (y - top) / m.row) else 0; + const hide_offset = if (k.reveal) |rv| rv.hidden(placed.value(rv.offsets), (y - top) / m.row) else 0; + const hide_role = if (k.reveal) |rv| rv.hidden(placed.value(rv.roles), (y - top) / m.row) else 0; // The page laid over them is opaque whatever the panel's own fade (a faded page over faded text leaves some). var page_u = u; page_u.at.pose.opacity = 1; - defer if (hide_offset > 0) page_u.faded(hide_offset).fill(.{ .x = 120, .y = y, .w = theme.metric.slot.offset + 4 - 120, .h = m.row }, theme.color.page); + defer if (hide_offset > 0) page_u.faded(hide_offset).fill(.{ .x = theme.metric.slot.lane_end, .y = y, .w = theme.metric.slot.offset + 4 - theme.metric.slot.lane_end, .h = m.row }, theme.color.page); // Who points here: a pin in the lane, landing with its link. const names = pins(u, now, is, was, addr, travel); var marks: rows.Marks = .{ .lead = lead, .first = now.writtenWatched(addr, 8, .memory, 0, watched_from, watched_to) }; @@ -744,10 +748,15 @@ pub const Stack = struct { marks.read = 0; marks.read_shows = now.reading(.memory, 0); } - // A word stored with the value it held (a `push rbp` over the old saved rbp): armed, and nothing struck. + // A word stored with the value it held (a `push rbp` over the old saved rbp): armed, and nothing struck; + // in the introduction struck as any write, its mark gone by the step's end (nothing remembers it). if (touched_here and touch.?.write and now.walking() and now.writeAge(addr, 8) != 0) { const s_at = now.plan.at[1]; - marks.first.arm = std.math.clamp((now.time - (s_at - time.strike.arm)) / time.stagger, 0, 1) * (1 - std.math.clamp((now.time - s_at) / time.quick, 0, 1)); + if (now.introduction) { + marks.first = now.heat(0, null, now.time - s_at); + marks.first.corner = 0; + marks.first.level *= 1 - std.math.clamp((now.time - now.plan.advance) / @max(now.plan.total - now.plan.advance, 1.0 / 60.0), 0, 1); + } else marks.first.arm = std.math.clamp((now.time - (s_at - time.strike.arm)) / time.stagger, 0, 1) * (1 - std.math.clamp((now.time - s_at) / time.quick, 0, 1)); } const below_rsp: i64 = if (tied) @bitCast(addr -% bases[1].value(is)) else @bitCast(addr -% if (held) rsp_shown else is.rsp); map.row(.stack, addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row }); @@ -792,7 +801,9 @@ pub const Stack = struct { const k_role = (addr -% roles_from) / 8; var role_at: [2]@TypeOf(roleName(u, .none, 0)) = undefined; for (&role_at, roles, [2]Recording.Moment{ now.before(), now.moment() }) |*r, of, mem| { - r.* = slotName(u, if (k_role < of.len) of[k_role] else .{}, (Recording.word(mem, addr, 8) catch null) orelse 1); + const slot_is: zt.telescope.Slot = if (k_role < of.len) of[k_role] else .{}; + // The introduction names the way back too (its caption's words: `return address` would cut `main+50`). + r.* = if (now.introduction and slot_is.role == .return_address) .{ .name = "the way back" } else slotName(u, slot_is, (Recording.word(mem, addr, 8) catch null) orelse 1); } const what: zt.telescope.Role = if (k_role < roles[1].len) roles[1][k_role].role else .none; const role = role_at[1]; @@ -870,7 +881,7 @@ pub const Stack = struct { // Rows crossed, counted on its whole way (its start may be off the window). const count = std.math.clamp(@ceil(goes(now, was, is, "rsp") * total_rows - 0.01), 1, total_rows); const bytes: u64 = @intFromFloat(count * 8); - pinAmount(u, x, top + place * m.row, names_, if (is.rsp < was.rsp) u.print("-{x}", .{bytes}) else u.print("+{x}", .{bytes}), amount_shows); + pinAmount(u, x, top + place * m.row, names_, u.print("{s}{s}{x}", .{ if (is.rsp < was.rsp) "-" else "+", rows.hexMark(bytes), bytes }), amount_shows); // The rows it crossed, a 3-unit vermilion bracket in the outer arc lane. if (crossed > 0.05) u.faded(amount_shows).bracket(theme.metric.arc.lanes[0], top + @min(place, old) * m.row + 2, top + @max(place, old) * m.row - 2, theme.mark(.write).solid, theme.metric.bracket.tie, 1, false); } else if (lone != null and joinsBefore(pins(u, now, is, was, is.named(name) orelse 0, travel).names, name)) { @@ -886,7 +897,7 @@ pub const Stack = struct { } else u.pinRow(x, top + place * m.row, names_, theme.color.region.stack); } for (spans[0..n_spans], 0..) |sp, i| if (sp.shows > 0) { - const sv = if (k.reveal) |rv| v.faded(1 - Reveal.hidden(placed.value(rv.spans), @floatFromInt(i))) else v; + const sv = if (k.reveal) |rv| v.faded(1 - rv.hidden(placed.value(rv.spans), @floatFromInt(i))) else v; if (sp.was) |was_name| { rows.span(sv.faded(1 - renamed), map.content(box.w), sp.y0, sp.y1, was_name, sp.newest, sp.open); rows.span(sv.faded(renamed), map.content(box.w), sp.y0, sp.y1, sp.name, sp.newest, sp.open); diff --git a/anim/src/cursor.zig b/anim/src/cursor.zig index b09db8d..c145823 100644 --- a/anim/src/cursor.zig +++ b/anim/src/cursor.zig @@ -80,8 +80,17 @@ pub const Levels = struct { annotation: enum { tied, whole } = .tied, /// A value's way between memory and a register (`carry`, "4. Ties"), /// read at each step (a beat may turn it on): none, an arrow, or the - /// arrow carrying the value's digits on a chip. - carry: enum { off, arrow, value } = .off, + /// arrow carrying the value's digits on a chip; or the arrow after the + /// instruction's touch, a store's too (the row names the word, then the + /// value goes there: the introduction's `push rbp`). + carry: enum { off, arrow, value, after_touch } = .off, + /// The introduction's (design/motion.md, "A scene: the introduction"): + /// what the working frame leaves to the eye, said: the stack's offsets + /// and a pin's amount written with `0x` where hex and decimal differ + /// (beside a symbol's decimal offset, `main+50`), a return address's + /// role named (`the way back`), and a store of the value its word held + /// struck as any write (the step's event). + introduction: bool = false, }; /// How a step is drawn. Walk: everything, as a sentence. Run: the mark and @@ -303,6 +312,11 @@ pub const Cursor = struct { /// The `aim` relation's knob (design/README.md, "4. Ties"): 0 off (the /// default), 1 standing (in and out over 18 f), 2 for the step. aim_knob: anim.Value, + /// A standing aim drawn as a step's is (`aim(.drawn)`): frames of its + /// way, 0 to 24 (18 the head's, 6 the row's frame; past 24, drawn), and + /// 1 while at full ink, 0 at the standing 60%. + aim_drawn: anim.Value, + aim_lit: anim.Value, /// The same values a little behind (`time.minimap_lag`, then a frame /// later each, `time.minimap_fade` of them): what the minimap draws /// from, secondary action that never starts on a primary onset's frame @@ -333,6 +347,8 @@ pub const Cursor = struct { .sprint_veil = s.value(0), .count = s.value(0), .aim_knob = s.value(0), + .aim_drawn = s.value(99), + .aim_lit = s.value(0), .lags = undefined, .first = start, .last = start, @@ -628,7 +644,12 @@ pub const Cursor = struct { const writes = c.levels.memory and (wrote > 0 or (touch != null and touch.?.write)); if (writes) { const store = if (carry) |cc| !cc.load else false; - if (store) { + if (store and c.levels.carry == .after_touch and touch != null and touch.?.write) { + // The touch to the word, the register framed as read (6 f), then the carry. + plan.touch = t + 6 * f; + plan.carry = plan.touch + k.touch + 12 * f; + plan.at[1] = plan.carry + k.carry + time.strike.arm; + } else if (store) { // The register framed as read (6 f), then the carry: no touch, the row having named the word. plan.carry = t + 12 * f; plan.at[1] = plan.carry + k.carry + time.strike.arm; @@ -778,30 +799,50 @@ pub const Cursor = struct { /// off unless the author turns it on, for a scene or a beat): `.standing` /// draws the aims of the words on screen, coming and going over 18 f; /// `.step` those of the words a walked step writes or reads. - pub fn aim(c: Cursor, s: *anim.Frame, knob: enum { off, step, standing }) void { + /// `drawn`: standing, but drawn as a step's aim is, head first from the + /// word at full ink (18 f), the row's address framed as it lands (6 f); + /// a `standing` after it falls to 60% (18 f). + pub fn aim(c: Cursor, s: *anim.Frame, knob: enum { off, step, standing, drawn }) void { // Over what follows: the timeline's cursor stays where it was. const start = s.cursor; defer s.cursor = start; switch (knob) { - .off, .standing => s.play(.{c.aim_knob.to(if (knob == .off) 0 else 1)}, .{ .seconds = 18.0 / 60.0, .ease = anim.ease.linear }), + .off, .standing => s.play(.{ c.aim_knob.to(if (knob == .off) 0 else 1), c.aim_lit.to(0) }, .{ .seconds = 18.0 / 60.0, .ease = anim.ease.linear }), .step => s.play(.{c.aim_knob.to(2)}, .{ .seconds = 0 }), + .drawn => { + s.play(.{ c.aim_knob.to(1), c.aim_lit.to(1), c.aim_drawn.to(0) }, .{ .seconds = 0 }); + s.play(.{c.aim_drawn.to(24)}, .{ .seconds = 24.0 / 60.0, .ease = anim.ease.linear }); + }, } } /// There at once, with nothing struck: a cut. pub fn jump(c: Cursor, s: *anim.Frame, to: u64) void { + c.jumpWalked(s, to, to); + } + + /// There at once, as though each moment from `from` on had been walked + /// to `to`, at rest: what the panels read of the steps before (the rows + /// run, the trail, the marks they left) as a walk leaves it (a chapter + /// opening on the last one's picture). + pub fn jumpWalked(c: Cursor, s: *anim.Frame, from: u64, to: u64) void { const Jump = struct { + from: u64, to: u64, fn run(j: @This(), sf: *anim.Frame, v: Cursor) void { var all: [history + 3]anim.Animation = undefined; - for (v.stops, 0..) |stop_value, i| all[i] = stop_value.to(@floatFromInt(j.to)); + for (v.stops, 0..) |stop_value, i| all[i] = stop_value.to(@floatFromInt(@max(j.to -| i, j.from))); all[history] = v.phase.to(1); all[history + 1] = v.marks[0].to(@floatFromInt(j.to)); all[history + 2] = v.marks[1].to(@floatFromInt(j.to)); sf.play(all, .{ .seconds = 0 }); } }; - c.both(s, Jump{ .to = to }); + // At the scene's first instant there is no before for the minimap's mirrors to lag behind. + if (s.cursor == 0) { + for (0..c.lags.len) |k| (Jump{ .from = from, .to = to }).run(s, lagged(c, k)); + (Jump{ .from = from, .to = to }).run(s, c); + } else c.both(s, Jump{ .from = from, .to = to }); } /// For a component, while it draws (on the minimap the values are a lagging mirror's: `lagInto`). @@ -824,6 +865,9 @@ pub const Cursor = struct { .annotation = c.levels.annotation, .way = .{ c.first, c.last }, .aim = placed.value(c.aim_knob), + .aim_drawn = placed.value(c.aim_drawn), + .aim_lit = placed.value(c.aim_lit), + .introduction = c.levels.introduction, }; var plan: [Plan.values]f32 = undefined; for (&plan, c.plan) |*is, v| is.* = placed.value(v); @@ -908,8 +952,13 @@ pub const Now = struct { annotation: @FieldType(Levels, "annotation") = .tied, /// The scene's way through the recording: its first moment and its last. way: [2]u64 = .{ 0, 0 }, - /// The `aim` knob: 0 off, up to 1 standing (coming or going), 2 for the step. + /// The `aim` knob: 0 off, up to 1 standing (coming or going), 2 for the step; + /// a standing one's way drawn (`Cursor.aim_drawn`, frames) and its ink (`aim_lit`). aim: f32 = 0, + aim_drawn: f32 = 99, + aim_lit: f32 = 0, + /// `Levels.introduction`. + introduction: bool = false, /// The program's state as shown. pub fn moment(n: Now) Recording.Moment { diff --git a/anim/src/hexdump.zig b/anim/src/hexdump.zig index 9b39bf6..d1c363c 100644 --- a/anim/src/hexdump.zig +++ b/anim/src/hexdump.zig @@ -801,8 +801,10 @@ pub fn readingIn(u: ui.Ui, y: f32, shift: f32, moment: Recording.Moment, values: var word: u64 = 0; for (0..@min(len, 8)) |k| word |= @as(u64, bytes[k]) << @intCast(8 * k); if (word == 0) break :blk "NULL"; - if (x + theme.metric.context.arrow_w + @as(f32, @floatFromInt(ui.digits(word))) * adv > room) break :blk "\u{2026}"; - x = u.arrow(x, y + m.row / 2, .points); + // The arrow has its own room, as in a chain: no character before it. + const ax = if (x > b.reading + shift) x - adv else x; + if (ax + theme.metric.context.arrow_w + @as(f32, @floatFromInt(ui.digits(word))) * adv > room) break :blk "\u{2026}"; + x = u.arrow(ax, y + m.row / 2, .points); x = u.address(x, base, word, .{ .ink = ui.rgb(rows.ink(rows.regionOf(moment, word))) }) + adv; continue; }, diff --git a/anim/src/nodes.zig b/anim/src/nodes.zig index 5218d7f..bc2ef86 100644 --- a/anim/src/nodes.zig +++ b/anim/src/nodes.zig @@ -40,6 +40,9 @@ pub const Nodes = struct { /// No registers in the pins: an instrumented program's registers say nothing of it. quiet: bool = false, focus: bool = true, + /// A pin's names past the second by name where they fit before the next + /// node, not a count (the introduction's: what its caption names). + named: bool = false, pub fn draw(g: *const Nodes, f: *sk.Frame, placed: anim.Placed) void { const box = g.stage.box(placed, .band); @@ -175,13 +178,18 @@ pub const Nodes = struct { const new = for (before) |was| { if (was.addr == o.addr) break false; } else true; + // Its pin's names run right as far as the next node (or the band's edge). + var room = box.w - m.pad - 8; + for (places) |q| if (q.x > place.x) { + room = @min(room, q.x - 8); + }; // What begins fades in; it does not pop. - if (show > 0) g.node(u.faded(show * (if (new) now.moving(.idea, 0, time.quick) else 1)).moved(0, below), now, o, place, label, value_size); + if (show > 0) g.node(u.faded(show * (if (new) now.moving(.idea, 0, time.quick) else 1)).moved(0, below), now, o, place, label, value_size, room); } g.tags(u, now, things, places, label); } - fn node(g: *const Nodes, u: ui.Ui, now: cursors.Now, o: objects.Object, r: Rect, label: f32, value_size: f32) void { + fn node(g: *const Nodes, u: ui.Ui, now: cursors.Now, o: objects.Object, r: Rect, label: f32, value_size: f32, room: f32) void { const moment = now.shown(.idea); const heap = theme.color.region.heap; const pw = theme.metric.node.pointer_w; @@ -235,7 +243,7 @@ pub const Nodes = struct { ties.anchor(u, .{ .node_pin = o.addr }, .{ .x = cx - 1, .y = r.y + r.h, .w = 2, .h = label + 10 }); if (names.names.len > 0 and names.shows > 0) { u.faded(names.shows).pinUnderInked(cx, r.y + r.h, &.{}, &.{}, heap, label); - u.faded(names.shows * names.text).pinNames(cx, r.y + r.h, names.names, names.inks, label); + u.faded(names.shows * names.text).pinNames(cx, r.y + r.h, names.names, names.inks, label, if (g.named) room else 0); } } diff --git a/anim/src/objects.zig b/anim/src/objects.zig index 6ee2b4c..dd9ea85 100644 --- a/anim/src/objects.zig +++ b/anim/src/objects.zig @@ -38,8 +38,7 @@ pub const Link = struct { from: u64, to: ?u64 }; /// shortcut: 64 objects at most; a bigger structure wants a view of part of it. pub fn reach(scratch: std.mem.Allocator, rec: *const Recording, m: Recording.Moment, root: ?[]const u8) []Object { var found: std.ArrayList(Object) = .empty; - const variables = m.variables(scratch) catch return &.{}; - for (variables) |v| { + for (rec.variables(scratch, m)) |v| { if (root) |name| if (!std.mem.eql(u8, rec.name(v.name), name)) continue; // A local its call has yet to assign points wherever that stretch of stack did before. if (!rec.assigned(v, m.index)) continue; diff --git a/anim/src/regroup.zig b/anim/src/regroup.zig index c9f618a..a904ba2 100644 --- a/anim/src/regroup.zig +++ b/anim/src/regroup.zig @@ -4,14 +4,16 @@ //! verbs that make words of them, each a clock the scene plays (frames, //! linear): //! -//! - `in`: the rows arrive, sixteen bytes a row, 18 f each, 12 f apart; no +//! - `in`: the rows arrive, sixteen bytes a row, 18 f each, 18 f apart; no //! ink, the addresses faint. //! - `regroup` (design/README.md, 6. Verbs): sixteen a row to eight, the //! return address walked (its offsets, `low byte`, `high byte`, its bytes -//! flying low byte first on nested arcs to its word's field, the gaps -//! closing, `zeros in front`), the other fifteen at a run. +//! flying low byte first to its word's field, on nested arcs, or over a +//! top row one at a time; the gaps closing, `zeros in front`), the other +//! fifteen at a run. //! - `framed`: three words that hold addresses framed as read, 30 f apart. -//! - `fold`: the rows out (6 f), the dump's tag to the shelf (18 f, `glide`); back. +//! - `fold`: the rows glide up into the header (24 f), the header becomes +//! the tag, the tag to the shelf (24 f, `glide`); back, the reverse. //! - `ink` (6. Verbs): a word's digits to its region's ink, the walked one //! framed with its bytes (its band in `segments` is the scene's echo); //! the rest at a run, 2 f apart. @@ -31,6 +33,18 @@ const Rect = ui.Rect; const t = theme.color.text; pub const words = 16; +/// `in`: frames between one row's arrival and the next's (motion.md's 12: +/// the rows come while the first text is read, and its reading has them). +pub const rows_apart = 18; +/// The walked word's flights (motion.md, "A word read": 36 f, 6 f apart): +/// over its row there is room for one in the air at a time, so each is +/// 24 f and the next lifts as it comes down (18 f apart), nothing crossing +/// in the air; what follows them is `later` by as much. +const flight = 24; +const flight_apart = 18; +const later: f32 = 108 + 7 * flight_apart + flight - 186; +/// The regroup's clock, to the last word in. +pub const regroup_frames = 386 + later; const size = theme.size.mono.context; const adv = ui.advance(size); const pitch = theme.metric.context.row; @@ -148,11 +162,6 @@ pub const Words = struct { }; } - /// The word's text: its hex without the zeros in front. - fn digits(u: ui.Ui, v: u64) []const u8 { - return u.print("{x}", .{v}); - } - pub fn draw(w: *const Words, f: *sk.Frame, placed: anim.Placed) void { const u: ui.Ui = .{ .f = f, .at = placed }; const in = placed.value(w.in); @@ -161,28 +170,30 @@ pub const Words = struct { defer @import("segments.zig").unclipStage(f, was); const r = placed.value(w.regroup); const fold = placed.value(w.fold); - const shown = 1 - clamp01(fold / 6); + // Folding: the rows glide up into the header (24 f), which becomes the tag (`tag`). + const gather = glide(fold / 24); + const header_y = at.top - pitch; w.tag(u, fold); - if (shown <= 0) return; - const v = u.faded(shown); + if (gather >= 1) return; + const v = u; const data = read(w.rec, w.at); const m = w.rec.moment(w.at); // The header (mock 29), with the first row; gone as the dump is tied to its place. // The veil over every row but the walked one, while it is walked (the header too). - const veil = clamp01((r - 48) / 18) - clamp01((r - 270) / 18); - const header = clamp01(in / 18) * (1 - placed.value(w.placed)) * (1 - veil); - if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, at.top - 12, "128 bytes, from where rsp points", t.faint); + const veil = clamp01((r - 48) / 18) - clamp01((r - 270 - later) / 18); + const header = clamp01(in / 18) * (1 - placed.value(w.placed)) * (1 - veil) * (1 - clamp01((fold - 12) / 8)); + if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, at.top - 12, v.print("128 bytes at {x}", .{w.rec.register(w.at, "rsp")}), t.faint); const address_ink = ui.mix(t.faint, theme.color.region.stack, placed.value(w.placed)); const become = placed.value(w.become); const g = glide(become); for (0..words) |i| { const p = where(i, r); - const arrive = clamp01((in - 12 * @as(f32, @floatFromInt(i / 2))) / 18); + const arrive = clamp01((in - rows_apart * @as(f32, @floatFromInt(i / 2))) / 18); if (arrive <= 0) continue; - const row = v.faded(arrive * (if (i == w.walked) 1 else 1 - theme.color.veil_alpha * veil)); + const row = v.faded(arrive * (if (i == w.walked) 1 else 1 - theme.color.veil_alpha * veil) * (1 - gather)); const slot: f32 = @floatFromInt(@as(i64, @bitCast(data.base + 8 * i -% w.panel.first)) >> 3); - const y = std.math.lerp(p.y, w.panel.top + pitch * slot, g); + const y = std.math.lerp(std.math.lerp(p.y, header_y, gather), w.panel.top + pitch * slot, g); const base = theme.baseline(y, pitch, size); // The bytes go first (9 f), then the addresses travel right to the slots' column: never over them. const ax = std.math.lerp(at.address, w.panel.x + theme.metric.slot.address, glide((become - 0.25) / 0.75)); @@ -195,13 +206,16 @@ pub const Words = struct { const framed = placed.value(w.framed); if (framed >= 0) for (w.three, 0..) |i, k| { const shows = clamp01((framed - 30 * @as(f32, @floatFromInt(k))) / 6); - if (shows > 0) v.read(w.wordRect(i, data.words[i], placed), shows); + var rect = w.wordRect(i, data.words[i], placed); + rect.y = std.math.lerp(rect.y, header_y, gather); + if (shows > 0) v.faded(1 - gather).read(rect, shows); }; } /// Word `i`'s digits as they stand in the field (ranged right, or at its left). fn wordRect(w: *const Words, i: usize, value: u64, placed: anim.Placed) Rect { - const n: f32 = @floatFromInt(ui.digits(value)); + // A number that is no address as the stack panel writes it (`0x` in front): see `drawWord`. + const n: f32 = if (rows.regionOf(w.rec.moment(w.at), value) == .none) ui.Value.of(value, false).width() / adv else @floatFromInt(ui.digits(value)); const left = glide(placed.value(w.left) / 24); const x = std.math.lerp(at.field_end - n * adv, at.field, left); return .{ .x = x, .y = at.top + pitch * @as(f32, @floatFromInt(i)), .w = n * adv, .h = pitch }; @@ -215,7 +229,7 @@ pub const Words = struct { const b = i * 8 + k; if (i == w.walked and r >= 108) { // In flight or landed: a faint copy fades into its place from a third of its flight. - const copy = clamp01((r - 120 - 6 * @as(f32, @floatFromInt(k))) / 12); + const copy = clamp01((r - 108 - 8 - flight_apart * @as(f32, @floatFromInt(k))) / 12); if (copy > 0) u.faded(copy).text(.mono, size, bx, base, u.print("{x:0>2}", .{data.bytes[b]}), dimmed()); continue; } @@ -232,7 +246,7 @@ pub const Words = struct { /// How far the run has brought word `i` in (its word in, its bytes dim): 8 f, rows 6 f apart. fn runIn(w: *const Words, i: usize, r: f32) f32 { const q: f32 = @floatFromInt(if (i > w.walked) i - 1 else i); - return clamp01((r - 288 - 6 * q) / 8); + return clamp01((r - 288 - later - 6 * q) / 8); } fn walkedFrame(w: *const Words, placed: anim.Placed) f32 { @@ -242,7 +256,7 @@ pub const Words = struct { } fn drawWord(w: *const Words, u: ui.Ui, m: Recording.Moment, value: u64, i: usize, y: f32, r: f32, placed: anim.Placed) void { - const shows = if (i == w.walked) @as(f32, if (r >= 240) 1 else 0) else w.runIn(i, r); + const shows = if (i == w.walked) @as(f32, if (r >= 240 + later) 1 else 0) else w.runIn(i, r); if (shows <= 0) return; const v = u.faded(shows); const kind = rows.regionOf(m, value); @@ -279,88 +293,116 @@ pub const Words = struct { return; } } - if (kind == .none) v.text(.mono, size, rect.x, base, digits(u, value), ink) else _ = v.address(rect.x, base, value, .{ .ink = ink, .rwx = kind == .rwx }); + if (kind == .none) _ = v.value(rect.x, base, value, false, .{ .ink = ui.rgb(ink) }) else _ = v.address(rect.x, base, value, .{ .ink = ink, .rwx = kind == .rwx }); const frame = if (i == w.walked) w.walkedFrame(placed) else 0; if (frame > 0) v.read(rect, frame); } /// The walked word, from its offsets to its sixteen digits (motion.md, "A word read"). fn walk(w: *const Words, u: ui.Ui, data: Bytes, r: f32) void { - if (r < 66 or r >= 240) return; + if (r < 66 or r >= 240 + later) return; const y = at.top + pitch * @as(f32, @floatFromInt(w.walked)); const base = theme.baseline(y, pitch, size); const value = data.words[w.walked]; - // A row near the dump's top has no room over it for the arcs at x2 (the camera's frame - // begins two rows over the header): there the bytes fly under the row, over the veiled - // rows, and the offsets and labels stand over it, the header's place (veiled with the rest). + // A row near the dump's top (at x2 the camera's frame has a row and a half over the header): + // its offsets stand over it, in the header's row (veiled with the rest), `low byte` left of + // `+0` and `high byte` right of `+7`; the bytes fly over that row (40 up), one at a time, + // each with its offset over it, its label going as it lifts and coming on the other side as + // it lands, so that nothing in the air crosses what stands, and no row of memory is printed over. const flip = w.walked < 4; const dir: f32 = if (flip) -1 else 1; // Under the row (over it, flipped), its offsets and labels on the page (the veiled rows there give way). // They go as the gaps close (192), not after: closed, their pairs are 24 apart and they would touch. - const labels = clamp01((r - 84) / 12) * (1 - clamp01((r - 192) / 12)); - const offsets = clamp01((r - 66) / 12) * (1 - clamp01((r - 192) / 12)); - const zeros_mark = clamp01((r - 204) / 12) * (1 - clamp01((r - 228) / 12)); + const labels = clamp01((r - 84) / 12) * (1 - clamp01((r - 192 - later) / 12)); + const offsets = clamp01((r - 66) / 12) * (1 - clamp01((r - 192 - later) / 12)); + const zeros_mark = clamp01((r - 204 - later) / 12) * (1 - clamp01((r - 228 - later) / 12)); const page_x = at.bytes - 12; const page_w = at.field_end - at.bytes + 24; - if (offsets > 0) u.faded(offsets).fill(.{ .x = page_x, .y = if (flip) y - 2 * pitch - 6 else y + pitch, .w = page_w, .h = 2 * pitch + 6 }, theme.color.page); - if (zeros_mark > 0) u.faded(zeros_mark).fill(.{ .x = page_x, .y = y + pitch, .w = page_w, .h = 2 * pitch + 6 }, theme.color.page); - const close = glide((r - 192) / 12); + if (!flip and offsets > 0) u.faded(offsets).fill(.{ .x = page_x, .y = y + pitch, .w = page_w, .h = 2 * pitch + 6 }, theme.color.page); + const close = glide((r - 192 - later) / 12); for (0..8) |k| { const kf: f32 = @floatFromInt(k); - const s = clamp01((r - 108 - 6 * kf) / 36); + const s = clamp01((r - 108 - flight_apart * kf) / flight); const from = at.bytes + kf * at.pair; const pair = 7 - kf; const to = std.math.lerp(at.field + pair * at.pair, at.field_end - (8 - pair) * 2 * adv, close); - const long = to - from; - const high = std.math.clamp(long / 4, theme.time.flight.arc_min, theme.time.flight.arc_max); - const x = std.math.lerp(from, to, theme.ease(.glide, s)); - const lift = dir * high * @sin(std.math.pi * s); + // Up off its place, over, down onto it; flipped, a plateau 40 up, the same for all (one flies at a time). + var x: f32 = undefined; + var lift: f32 = undefined; + var across: f32 = undefined; + if (flip) { + across = glide((s - 0.1) / 0.8); + x = std.math.lerp(from, to, across); + // Clear of the offsets standing in the row over it; one in the air at a time, so one height. + lift = 40 * @min(theme.ease(.glide, clamp01(s / 0.25)), theme.ease(.glide, clamp01((1 - s) / 0.25))); + } else { + across = theme.ease(.glide, s); + x = std.math.lerp(from, to, across); + const high = std.math.clamp((to - from) / 4, theme.time.flight.arc_min, theme.time.flight.arc_max); + lift = high * @sin(std.math.pi * s); + } // The byte itself: bright and bold in the air (from 108 the walk draws it, not the row). if (r >= 108) { const air = s > 0 and s < 1; const text = u.print("{x:0>2}", .{data.bytes[w.walked * 8 + k]}); // In the air it carries its ground: over the veiled rows it reads alone. - if (air) u.fill(.{ .x = x - 3, .y = base - lift - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); + if (air) u.fill(.{ .x = x - 3, .y = base - lift - 17, .w = 2 * adv + 6, .h = 20 }, theme.color.page); // Each digit of a pair on its own: a zero in front of the word fades on its own. for (0..2) |d| { const lead = 2 * (7 - k) + d < 16 - ui.digits(value); - const fade: f32 = if (lead and r >= 228) 1 - clamp01((r - 228) / 12) else 1; + const fade: f32 = if (lead and r >= 228 + later) 1 - clamp01((r - 228 - later) / 12) else 1; if (fade > 0) u.faded(fade).text(if (air) .mono_bold else .mono, size, x + @as(f32, @floatFromInt(d)) * adv, base - lift, text[d .. d + 1], if (air) t.bright else t.primary); } } - // Its offset under it, going with it. + // Its offset under it (over it, flipped), going with it (in the air 22 over it: the frame's top is near). const off = offsets * clamp01((r - 66 - 2 * kf) / 12); - if (off > 0 and s > 0 and s < 1) u.faded(off).fill(.{ .x = x - 3, .y = base + dir * pitch - lift - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); - if (off > 0) u.faded(off).text(.mono, size, x, base + dir * pitch - lift, u.print("+{d}", .{k}), t.dim); + const off_base = base + dir * (if (flip) std.math.lerp(pitch, 22, clamp01(lift / 40)) else pitch) - lift; + if (off > 0 and s > 0 and s < 1) u.faded(off).fill(.{ .x = x - 3, .y = off_base - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); + if (off > 0) u.faded(off).text(.mono, size, x, off_base, u.print("+{d}", .{k}), t.dim); // `low byte` from its byte's left, `high byte` to its byte's right: under the bytes, never the addresses. + // Flipped: beside its offset, outside the run, the low byte's on the left at rest and on the right + // landed (the word reads it last); it goes as its byte lifts and comes as it lands, never crossing its offset. if (k == 0 or k == 7) if (labels > 0) { const label = if (k == 0) "low byte" else "high byte"; const lw = u.width(.sans, theme.size.sans.tag, label); - u.faded(labels).text(.sans, theme.size.sans.tag, if (k == 0) x else x + 2 * adv - lw, base + dir * 2 * pitch + 2 - lift, label, t.dim); + const left = x - lw - adv / 2; + const right = x + 2 * adv + adv / 2; + const landing = s >= 0.5; + const lx = if (!flip) (if (k == 0) x else x + 2 * adv - lw) else if ((k == 0) == landing) right else left; + const ly = if (flip) off_base else base + 2 * pitch + 2 - lift; + // (`high byte`, right of `+7` at rest, would stand where `+6` lands: it goes as `+6` lifts.) + const gone = if (k == 7) clamp01((r - 108 - flight_apart * 6) / flight / 0.2) else clamp01(s / 0.2); + const there: f32 = if (!flip) 1 else if (landing) clamp01((s - 0.8) / 0.2) else 1 - gone; + if (there > 0) u.faded(labels * there).text(.sans, theme.size.sans.tag, lx, ly, label, t.dim); }; } - // The zeros in front, bracketed (motion.md: 204 to 228). + // The zeros in front, bracketed (motion.md: 204 to 228, here `later`), on a ground only as wide as its label. if (zeros_mark > 0) { const lead: f32 = @floatFromInt(16 - ui.digits(value)); const x0 = at.field_end - 16 * adv; const v = u.faded(zeros_mark); + const said = "zeros in front"; + v.fill(.{ .x = x0 - 4, .y = y + pitch + 2, .w = v.width(.sans, theme.size.sans.tag, said) + 8, .h = pitch - 2 }, theme.color.page); v.fill(.{ .x = x0, .y = y + pitch - 2, .w = lead * adv, .h = 2 }, t.dim); v.fill(.{ .x = x0, .y = y + pitch - 8, .w = 2, .h = 6 }, t.dim); v.fill(.{ .x = x0 + lead * adv - 2, .y = y + pitch - 8, .w = 2, .h = 6 }, t.dim); - v.text(.sans, theme.size.sans.tag, x0, base + pitch + 2, "zeros in front", t.dim); + v.text(.sans, theme.size.sans.tag, x0, base + pitch + 2, said, t.dim); } } - /// The dump folded to its tag on the shelf (mock 49's shelf, y 48): the - /// rows out over 6 f, the tag from over the rows to the shelf (18 f, `glide`). + /// The dump folded to its tag on the shelf (mock 49's shelf, y 48): as + /// the rows gather into the header, the header becomes the tag (the + /// header out 12 to 20, the tag in 16 to 24, its title where the + /// header's was), which then goes to the shelf (24 f, `glide`); back, + /// the reverse. fn tag(_: *const Words, u: ui.Ui, fold: f32) void { - if (fold <= 0) return; - const title = "the stack's 128 bytes"; - const p = glide((fold - 6) / 18); + if (fold <= 16) return; + const title = "the 128 bytes"; + const p = glide((fold - 24) / 24); const w = u.width(.sans_medium, theme.size.sans.tag, title) + 40; - const x = std.math.lerp(at.address - 8, theme.canvas.margin_x, p); + const x = std.math.lerp(at.address - 28, theme.canvas.margin_x, p); const y = std.math.lerp(at.top - 30, theme.canvas.stage.y, p); - const v = u.faded(clamp01(fold / 6)).moved(x, y); + const v = u.faded(clamp01((fold - 16) / 8)).moved(x, y); v.fill(.{ .x = 0, .y = 0, .w = w, .h = theme.metric.context.tag }, theme.color.raised); v.frame(.{ .x = 8, .y = 6, .w = 12, .h = 12 }, t.faint, theme.stroke.rule); v.text(.sans_medium, theme.size.sans.tag, 28, theme.metric.context.tag - 6, title, t.dim); diff --git a/anim/src/rows.zig b/anim/src/rows.zig index 08f1fb2..bdf9454 100644 --- a/anim/src/rows.zig +++ b/anim/src/rows.zig @@ -326,9 +326,20 @@ pub fn slot(u: ui.Ui, y: f32, w: f32, moment: Recording.Moment, addr: u64, from_ return chain(u, at, y, moment, held, room, lead); } +/// The stack panel's offsets written with `0x` while it draws its rows +/// (`Levels.introduction`), where hex and decimal differ (10 and over), as +/// an instruction's operands and a value are (`-8`, `-0x18`). +pub var prefixed = false; + +/// `0x` in front of `n` (`prefixed`), or nothing. +pub fn hexMark(n: u64) []const u8 { + return if (prefixed and n >= 10) "0x" else ""; +} + /// A slot's offset from rsp, `from_rsp` bytes: hex, faint, ranged right to 172. fn offset(u: ui.Ui, y: f32, from_rsp: i64) void { - const text = if (from_rsp < 0) u.print("-{x}", .{@as(u64, @intCast(-from_rsp))}) else u.print("+{x}", .{@as(u64, @intCast(from_rsp))}); + const p = hexMark(@abs(from_rsp)); + const text = if (from_rsp < 0) u.print("-{s}{x}", .{ p, @as(u64, @intCast(-from_rsp)) }) else u.print("+{s}{x}", .{ p, @as(u64, @intCast(from_rsp)) }); u.text(.mono, size, theme.metric.slot.offset - u.width(.mono, size, text), baseline(y), text, t.faint); } diff --git a/anim/src/segments.zig b/anim/src/segments.zig index db9d28f..a304993 100644 --- a/anim/src/segments.zig +++ b/anim/src/segments.zig @@ -572,6 +572,10 @@ pub const Place = struct { /// Frames into the tie (negative: not begun); frames into its quieting. clock: anim.Value, quiet: anim.Value, + /// 0 to 1: the dump's place marked on its box for a camera's visit (it + /// is far thinner than a unit there): a 2-unit tick across the box in + /// the stack's ink, `128 bytes` over it, left of where the link comes down. + tick: ?anim.Value = null, pub fn draw(p: *const Place, f: *sk.Frame, placed: anim.Placed) void { const clock = placed.value(p.clock); @@ -590,9 +594,15 @@ pub const Place = struct { u.route(&.{ .{ p.x, p.y0 }, .{ p.x, top }, .{ to[0], top }, .{ to[0], to[1] } }, ink, .{ .width = theme.stroke.tie.link, .head = .{ 10, 10 }, .progress = drawn, .radius = 8 }); // The stack's band framed bright as the head lands. const bright = std.math.clamp((clock - 42) / 6, 0, 1) * (1 - std.math.clamp((clock - 48) / 12, 0, 1)); - if (bright > 0) for (l.space.clusters, 0..) |c, i| if (i < 6 and p.addr >= c.lo and p.addr < c.hi) { + const marked = if (p.tick) |tv| std.math.clamp(placed.value(tv), 0, 1) else 0; + if (bright > 0 or marked > 0) for (l.space.clusters, 0..) |c, i| if (i < 6 and p.addr >= c.lo and p.addr < c.hi) { const b = l.boxes[i]; - u.faded(bright).frame(.{ .x = b.x - 5, .y = b.y - 5, .w = b.w + 10, .h = b.h + 10 }, t.bright, theme.stroke.line); + if (bright > 0) u.faded(bright).frame(.{ .x = b.x - 5, .y = b.y - 5, .w = b.w + 10, .h = b.h + 10 }, t.bright, theme.stroke.line); + if (marked > 0) { + const label = "128 bytes"; + u.faded(marked).fill(.{ .x = b.x, .y = to[1] - 1, .w = b.w, .h = 2 }, region.stack); + u.faded(marked).text(.sans, theme.size.sans.tag, to[0] - 8 - u.width(.sans, theme.size.sans.tag, label), to[1] - 6, label, region.stack); + } }; } }; diff --git a/anim/src/ties.zig b/anim/src/ties.zig index b5214e3..3048e32 100644 --- a/anim/src/ties.zig +++ b/anim/src/ties.zig @@ -765,7 +765,10 @@ const Cx = struct { line.target = .beyond; line.words = bb.words; } else return; - cx.linkTo(line, drawn, back); + // Drawn back toward its head, the head goes over the last third, not in a frame. + var faded = cx; + faded.raw = cx.raw.faded(1 - std.math.clamp((back - 2.0 / 3.0) * 3, 0, 1)); + faded.linkTo(line, drawn, back); } /// The step's projection: the first run of bytes it read or wrote in @@ -862,7 +865,9 @@ const Cx = struct { } const right = row_box[2]; // How much it shows: standing with the knob (18 f in and out), for the step from the word's mark to the advance. - var drawn: f32 = 1; + // Standing, drawn as a step's when the scene says (`aim(.drawn)`): head first, then the row's frame. + var drawn: f32 = if (step) 1 else cursors.standard(std.math.clamp(now.aim_drawn / 18.0, 0, 1)); + var framed: f32 = if (step) 1 else std.math.clamp((now.aim_drawn - 18.0) / 6.0, 0, 1); var shows: f32 = if (step) 1 else @min(now.aim, 1); if (step) { if (now.resting()) return; @@ -870,23 +875,24 @@ const Cx = struct { const long = @abs(y_row - y_word) > 10 * theme.metric.context.row * k; drawn = cursors.standard(std.math.clamp((now.time - from) / @as(f32, if (long) 24.0 / 60.0 else 18.0 / 60.0), 0, 1)); shows = 1 - std.math.clamp((now.time - now.plan.advance) / time.quick, 0, 1); + framed = if (drawn >= 1) 1 else 0; } if (drawn <= 0 or shows <= 0) return; - // Standing, 60% toward the page; fraying, dashed over its first 12 f, then fading. - const ink = if (step) ui.rgb(theme.color.region.code_) else ui.mix(theme.color.region.code_, theme.color.page, 0.6); + // Standing, 60% toward the page (at full ink while lit); fraying, dashed over its first 12 f, then fading. + const ink = if (step) ui.rgb(theme.color.region.code_) else ui.mix(theme.color.region.code_, theme.color.page, 0.6 * (1 - std.math.clamp(now.aim_lit, 0, 1))); const v = cx.raw.faded(shows * (1 - std.math.clamp((fray - 0.4) / 0.6, 0, 1))); const points = [4]ui.Vec{ .{ rule, y_word }, .{ lane, y_word }, .{ lane, y_row }, .{ right, y_row } }; if (fray > 0) { // Dashed, 12 on 8, the gaps opening over the fray's first 12 f. const open = std.math.clamp(fray / 0.4, 0, 1); dashed(v, &points, ink, theme.stroke.rule * k, 12 * k, 8 * k * open); - } else v.route(&points, ink, .{ .width = theme.stroke.rule * k, .head = .{ 8 * k, 8 * k }, .progress = drawn, .radius = theme.metric.tie.radius * k }); + } else v.route(&points, ink, .{ .width = theme.stroke.rule * k, .head = .{ 10 * k, 10 * k }, .progress = drawn, .radius = theme.metric.tie.radius * k }); // The row's address framed in code's ink as the head lands. - if (drawn >= 1 and fray == 0) { + if (drawn >= 1 and fray == 0 and framed > 0) { const adv = ui.advance(theme.size.mono.context) * k; const digits: f32 = @floatFromInt(ui.digits(if (row_box[1] == line.to[1]) line.value else line.was)); const x0 = row_box[0] + (theme.metric.insn.address - 4) * k; - v.frame(.{ .x = x0, .y = row_box[1], .w = digits * adv + 8 * k, .h = row_box[3] - row_box[1] }, ink, theme.stroke.rule * k); + v.faded(framed).frame(.{ .x = x0, .y = row_box[1], .w = digits * adv + 8 * k, .h = row_box[3] - row_box[1] }, ink, theme.stroke.rule * k); } } }; diff --git a/anim/src/ui.zig b/anim/src/ui.zig index 589bfb6..eeac127 100644 --- a/anim/src/ui.zig +++ b/anim/src/ui.zig @@ -555,13 +555,14 @@ pub const Ui = struct { u.fill(.{ .x = cx - p.stub / 2, .y = y + p.under_head[0] - 1, .w = p.stub, .h = rise - p.under_head[0] + 1 }, ink); sk.draw.polygon(u.f, &.{ .{ cx, y + 1 }, .{ cx - p.under_head[1] / 2, y + 1 + p.under_head[0] }, .{ cx + p.under_head[1] / 2, y + 1 + p.under_head[0] } }, u.at.pen(.{ .fill = rgb(ink) })); if (names.len == 0) return; - u.pinNames(cx, y, names, inks, size); + u.pinNames(cx, y, names, inks, size, 0); } /// The names of a `pin` `under`: the first left of the stub, the - /// second right of it ("" for a side kept free), the rest a count; - /// each bold in `inks` (a variable's: where it lives) or primary. - pub fn pinNames(u: Ui, cx: f32, y: f32, names: []const []const u8, inks: []const u24, size: f32) void { + /// second right of it ("" for a side kept free), the rest a count, or + /// by name where they fit before `room` (an x; 0: none); each bold in + /// `inks` (a variable's: where it lives) or primary. + pub fn pinNames(u: Ui, cx: f32, y: f32, names: []const []const u8, inks: []const u24, size: f32, room: f32) void { const p = theme.metric.pin; const by = y + 8 + size * 0.86; const ink = struct { @@ -573,7 +574,15 @@ pub const Ui = struct { // One name a side: a node's neighbour has its own. The rest are a count. if (names.len > 1) { u.text(.mono_bold, size, cx + p.under_names, by, names[1], ink(inks, 1)); - if (names.len > 2) u.text(.mono_bold, size, cx + p.under_names + u.width(.mono, size, names[1]) + advance(size) / 2, by, u.print("+{d}", .{names.len - 2}), theme.color.text.primary); + var x = cx + p.under_names + u.width(.mono, size, names[1]) + advance(size) / 2; + var end = x; + for (names[2..]) |n| end += u.width(.mono, size, n) + advance(size) / 2; + if (names.len > 2 and end - advance(size) / 2 <= room) { + for (names[2..], 2..) |n, i| { + u.text(.mono_bold, size, x, by, n, ink(inks, i)); + x += u.width(.mono, size, n) + advance(size) / 2; + } + } else if (names.len > 2) u.text(.mono_bold, size, x, by, u.print("+{d}", .{names.len - 2}), theme.color.text.primary); } } diff --git a/anim/test/gallery/atoms.png b/anim/test/gallery/atoms.png Binary files differindex 9ae1959..79ceabf 100644 --- a/anim/test/gallery/atoms.png +++ b/anim/test/gallery/atoms.png diff --git a/anim/test/gallery/graph-map.png b/anim/test/gallery/graph-map.png Binary files differindex eec101e..c7f1a2c 100644 --- a/anim/test/gallery/graph-map.png +++ b/anim/test/gallery/graph-map.png diff --git a/anim/test/gallery/graph.png b/anim/test/gallery/graph.png Binary files differindex 305b3d4..a35d7f7 100644 --- a/anim/test/gallery/graph.png +++ b/anim/test/gallery/graph.png diff --git a/anim/test/gallery/loupe.png b/anim/test/gallery/loupe.png Binary files differindex 47977d6..2020692 100644 --- a/anim/test/gallery/loupe.png +++ b/anim/test/gallery/loupe.png diff --git a/anim/test/gallery/none.png b/anim/test/gallery/none.png Binary files differindex ba6f328..d12d870 100644 --- a/anim/test/gallery/none.png +++ b/anim/test/gallery/none.png diff --git a/anim/test/gallery/rest.png b/anim/test/gallery/rest.png Binary files differindex c1a9e52..c42c53f 100644 --- a/anim/test/gallery/rest.png +++ b/anim/test/gallery/rest.png diff --git a/anim/test/gallery/rows.png b/anim/test/gallery/rows.png Binary files differindex 280b72c..42c3b05 100644 --- a/anim/test/gallery/rows.png +++ b/anim/test/gallery/rows.png diff --git a/anim/test/gallery/step.png b/anim/test/gallery/step.png Binary files differindex 56c798d..5ba2cbb 100644 --- a/anim/test/gallery/step.png +++ b/anim/test/gallery/step.png diff --git a/anim/test/gallery/subject.png b/anim/test/gallery/subject.png Binary files differindex 15857f9..164a270 100644 --- a/anim/test/gallery/subject.png +++ b/anim/test/gallery/subject.png diff --git a/anim/tools/chart.py b/anim/tools/chart.py index aa20e43..53324ff 100644 --- a/anim/tools/chart.py +++ b/anim/tools/chart.py @@ -88,8 +88,9 @@ motion.REGIONS.update({ # program column, the dump in the state column (the texts beside the address space there while # the dump is on the shelf); the camera at x2 on the dump for its first three beats. "intro_memory": {"space": (64, 48, 880, 840), "dump": (976, 48, 880, 840), **words}, - # Chapter II: the texts on the left (the program column, empty), the registers built over the stack. - "intro_stack": {"text": (64, 48, 880, 840), "registers": (976, 48, 880, 236), "stack": (976, 296, 880, 592), **words}, + # Chapter II: the texts on the left (the program column), main's rows and reverse's first under them, + # the registers built over the stack. + "intro_stack": {"text": (64, 48, 880, 536), "code": (64, 584, 880, 304), "registers": (976, 48, 880, 236), "stack": (976, 296, 880, 592), **words}, # Chapter III: the aligned panel across both columns under its text above, then the working frame # (the nodes lens as the list scene's), then the map. "intro_code": {"text": (64, 48, 1792, 120), "aligned": (64, 168, 1792, 720), **words}, |
