summaryrefslogtreecommitdiff
path: root/anim/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 22:02:01 -0300
committerGabriel Schneider <[email protected]>2026-11-10 22:06:03 -0300
commit8b5d0340c9f9b3168c67f04e57cfa03712ac992c (patch)
tree66891f03e905731b8afa2689e86fe612675f4f35 /anim/README.md
parent36bb1c332a124cb4d437dd8386b267ee58310a5d (diff)
downloadcomputeranim-8b5d0340c9f9b3168c67f04e57cfa03712ac992c.tar.gz
computeranim-8b5d0340c9f9b3168c67f04e57cfa03712ac992c.zip
canim: a continue is a wave; what arrives after a fade is plain; a pin only where its register points
From the designer's review of the SQLite scene. Between far stops the changed registers strike two frames apart in pwndbg's order, and links and pins set off with memory. A stack window or a dump that fades in carries no marks of changes the viewer did not see. At rest a moved register kept a pin at its old place as well, in every scene: gone. The kernel's answer is filled before the return arrow leaves, and rax strikes as it lands. Every dump has one reading, by type (a char quoted, a bool by name); line numbers are as wide as the program's largest; pins' names keep the side they came to. Names and measures follow the catalogue (.loose, theme.metric.calls, time.pin, time.continue_wave). Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'anim/README.md')
-rw-r--r--anim/README.md125
1 files changed, 75 insertions, 50 deletions
diff --git a/anim/README.md b/anim/README.md
index 5801c74..bf2100a 100644
--- a/anim/README.md
+++ b/anim/README.md
@@ -75,7 +75,12 @@ projection from its return address does, 36 f after); the writes of one step str
mark advances last; a rest. `walk` plays steps in full, `hurry` ramps the
pace down and up again (each step 0.6 of the one before) to a run (0.30 s a
step) or a sprint, `step` takes an explicit `Plan` (`Array.swap`,
-`syscalls.step`). Components read it through `Cursor.now(at)`.
+`syscalls.step`), and `continue` goes to a stop far from this one (a
+breakpoint): the line it leaves fires, the registers it changed strike in
+a wave 2 f apart in pwndbg's order (fill 6 f, no arm, no pulse), then
+memory and the idea, a 36 f hold, the mark out and in (6 f each, the
+source fading through first if far), a 24 f rest. Components read it
+through `Cursor.now(at)`.
## The scenes
@@ -87,7 +92,7 @@ step) or a sprint, `step` takes an explicit `Plan` (`Array.swap`,
| `sort` | insertion sort: compares and swaps | `subject`, `array` | `sort` |
| `syscalls` | open, read, close, write: the kernel's side | `subject`, `syscalls` | `hello` |
| `zoom` | one line of C as its instructions, the call's bytes | `none`, the camera at x2 | `steps` |
-| `sqlite` | a row's way to disk in SQLite: from `sqlite3_step` to `sqlite3BtreeInsert` (three continues, the row's struct on the stack), the commit's `unixWrite` nine calls under `main`, `pwrite64` of page 2 into the kernel, and the page read as a B-tree leaf | `subject` with the backtrace in the drawing's place, then `syscalls`; its view a `hexdump.Dump` | `sqlite` |
+| `sqlite` | a row's way to disk in SQLite: from `sqlite3_step` to `sqlite3BtreeInsert` (three continues, the row's struct on the stack), the commit's `unixWrite` nine calls under `main`, `pwrite64` of page 2 into the kernel, and the page read as a B-tree leaf | `subject`, `backtrace` (`Context.Options.backtrace`), then `syscalls`; its view a `hexdump.Dump` | `sqlite` |
| `gallery` | every block in its states | all three | `gallery` |
## The blocks
@@ -97,20 +102,20 @@ every state the code has in the `gallery` scene.
| Layer | Block | Where | Notes |
| --- | --- | --- | --- |
-| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes"; JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 |
+| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes" (`metric.calls`, `time.pin`, `time.continue_wave`, `time.relayout_fade` there; the insn's character counts gone); JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 |
| 1 atom | `address` (`lead`, `name`, `rwx`), `value` (and `Ui.typed`: `fd`, `bool`, `char`), `arrow` (`points`, `holds`, `more`), `mark`s, `plaque` (`chip`), `pin` (`row`, `under`), `bracket` (`quiet`, `tie`, `thread`), `tag` | `src/ui.zig` (`Ui.address`, `.value`, `.arrow`, `.written`, `.read`, `.cellWritten`, `.cellRead`, `.current`, `.trail`, `.unknown`, `.chip`, `.pinRow`, `.pinUnder`, `.bracket`, `.panel`) | marks in the context: `armed`, `struck`, `held` (a tick), `read`; in a lens's cell the same with a bar |
-| | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `text` (a string's ink), `allocator` (also bytes that are no field of what a dump is about), `unread`; `pad`; `bytesAt` moves the bytes right of a long (stack) address |
+| | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `text` (a string's ink), `loose` (a byte of no field: the allocator's, padding, past what a dump is of), `unread`; `pad`; `bytesAt` moves the bytes right of a long (stack) address, by the dump's widest |
| 2 row | `chain`, `reg` (and `rip` with the flags), `slot`, `line`, `bytes`, `call` (`span`, `callRow`) | `src/rows.zig` | `chain` follows `zt.telescope.chase`; cut at its far end, `more` |
| | `insn` | `src/disasm.zig` | columns at 2, 31, 40, 134, 180, 264, 564; operands whole, the annotation from 564 or a character after them; then a size word goes, then the operands give way, never inside `[]`; `current`, `ran` (every instruction of the last three steps), `ahead`, `outside`; the jump lane from the jump just before the pc's moment |
-| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's window on `[rsp, rbp+16)` keeping the touched word in view, rsp and rbp's pins travelling (keeping their place among the names they leave and join); a window that moves more than 16 words fades out and in round memory's strike; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth |
-| | `source` | `src/source.zig` | the whole file in a window, its middle third; numbers as wide as the window needs (SQLite's have five digits), the text moved right by as much; a window more than two windows away fades out and in |
-| | `disasm` | `src/disasm.zig` | 17 rows (9 as subject), fewer above near a function's start |
-| | `hexdump` | `src/hexdump.zig` | a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; `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 those left out, marks the scene plays, the bytes a syscall was given as the kernel took them, and only what the debugger read at the stop (`seen`) |
-| | lenses: `nodes`, `array`, `calls`, `syscalls` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`) | 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 bytes the call is given or fills |
+| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's window on `[rsp, rbp+16)` keeping the touched word in view, its tag the first and last word shown (`rsp+20 to rsp+48`), rsp and rbp's pins travelling 18 f after rsp's strike (`time.pin`, keeping their place among the names they leave and join), at rest only where the register points; a window that moves farther than its own height (six or eight slots) fades out and in round memory's strike, and what it brings, and what changed before it, is plain; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth; the backtrace as a lens's drawing with `Context.Options.backtrace` |
+| | `source` | `src/source.zig` | the whole file in a window, its middle third; numbers as wide as the program's largest line (SQLite's six digits), the text moved right by as much; a window going farther than its own height fades out and in |
+| | `disasm` | `src/disasm.zig` | 17 rows (9 as subject), fewer above near a function's start; the line column as wide as the source's; two windows that overlap scroll, others fade out and in |
+| | `hexdump` | `src/hexdump.zig` | a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; 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`) |
+| | 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 bytes the call is given or fills, `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 |
| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, 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; a projection from the view's bytes, or from a frame's return address to its call's node |
| 5 frame | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject` (`theme.layout.split`): 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 |
| | `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` |
-| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`) |
+| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `continue` (`Cursor.continue`, `Plan.wave`), `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`) |
`Recording` (`src/Recording.zig`) is the index every block reads: lines,
calls, syscalls, allocations, which registers and bytes each moment changed
@@ -141,8 +146,8 @@ and no canary stepped through that the source does not say.
A recording that begins inside a call (`--from`) has that call open from
its first stop (`Recording.index`, from the frame chain). Writes are the
bytes whose value changed, to the element the instruction stored (its
-`touch`); a store of the same value is kept apart (`store_spans`) and
-counts as assigning a local. A register's change over a step is net: a
+`touch`); a store of the same value is kept apart (`storedSame`) and
+counts as assigning a local (and as a name coming to a node's pin). A register's change over a step is net: a
call's rsp put back is not struck. The vDSO's `clock_gettime` is stepped
through under the runtime and the agent: its retry loop makes the counts
vary a little from one recording to the next. An address no symbol
@@ -153,59 +158,80 @@ holds is named from its module's first mapping (`list+2c89`).
`tools/chart.py chart` on the 1080p exports in `out/` (the designer's five
checks; its regions follow the two-panel band now). Encoded with `-g 600`:
x264's keyframe at 10, 20, 30 s is a one-frame fade the instrument sees.
+"Before" is the exports this pass started from (10 November, evening);
+"after" the ones it made: the continue's wave, plain windows and dumps
+after a fade, the crossing's order, pins at rest only where their
+register points, `time.pin`, the compact reading, names by arrival.
| | fib | list | sort | syscalls | zoom | sqlite |
| --- | --- | --- | --- | --- | --- | --- |
-| POP, round 2 / 3 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 |
-| CROWD, round 2 / 3 | 7 / 2 | 2 / 7 | 10 / 6 | 5 / 1 | 4 / 3 | – / 1 |
-| RUSH, round 2 / 3 | 0 / 0 | 0 / 2 | 2 / 0 | 1 / 2 | 0 / 0 | – / 1 |
-| AIR, round 3 | 0 | 0 | 0 | 0 | 1 | 4 |
-| seconds, round 3 | 41.5 | 60.5 | 42.0 | 38.5 | 32.0 | 64.6 |
-
-(sort as the coordinator re-exported it without the camera; syscalls and
-sqlite after the crossing's changes: a register carries a call only while
-it holds the argument at the stop shown, `rax` is struck after the
-kernel's `returns` row; fib, list and zoom are the round-3 exports, made
-before the stack's and backtrace's motions below.)
+| POP, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 |
+| CROWD, before / after | 2 / 2 | 7 / 7 | 5 / 5 | 1 / 1 | 4 / 4 | 1 / 0 |
+| RUSH, before / after | 0 / 0 | 2 / 2 | 0 / 0 | 2 / 1 | 0 / 0 | 1 / 1 |
+| AIR, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 1 / 1 | 4 / 5 |
+| seconds, after | 41.5 | 60.5 | 42.0 | 37.9 | 32.0 | 64.6 |
What fires, and why it is left:
-- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 17.58 are the
+- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 17.60 are the
veil coming over the registers, stack and disassembly at the first
shortened step (one veil over three panels); zoom 9.65 and 21.55 the
camera (the regions are fixed on the screen); zoom 11.75 the stack's
window scrolling to its hold under the camera (the stack fills every
- region there). The rest (list 15.92, 19.32 and the others like them,
- sort 11.68, 27.12, 29.42 and the others, syscalls 35.35, sqlite 43.40)
- are an `advance`: the thread, the plaques and rip move as one mark, the
+ region there); sort 30.00 is x264's keyframe on a step's first frame.
+ The rest (list 15.92, 19.32 and the others like them, sort 11.68,
+ 29.42 and 36.13, syscalls 34.75, zoom 3.62) are an
+ `advance`: the thread, the plaques and rip move as one mark, the
source and the disassembly scroll with it, and a link or projection
- goes back into its pin, all on the catalogue's one frame.
-- RUSH: list 29.20 and 29.55, syscalls 29.37 and 29.72, sqlite 9.10: a
- caption arrives, and the next change the instrument sees is the
- keyframe at 30.00 (10.00) (a fade of every region over one frame,
- 0.00% at its peak).
+ goes back into its pin, all on the catalogue's one frame. (sqlite's,
+ the crossing's advance at 43.40, no longer starts with another panel.)
+- RUSH: list 29.20 and 29.55, syscalls 29.32, sqlite 9.10: a caption
+ arrives, and the next change the instrument sees is the keyframe at
+ 30.00 (10.00) (a fade of every region over one frame, 0.00% at its
+ peak).
- AIR: a caption's reading time on a still picture: the last one's and
- the 2 s on the finished picture (zoom 26.88, 3.1 s; sqlite 60.02,
- 4.6 s), and in sqlite three more, each a dense caption over a stop
- (11.38, 7.2 s: the arguments; 32.72, 3.5 s: the commit's backtrace;
- 50.03, 4.9 s: the page's header), its fields framed as it names them.
+ the 2 s on the finished picture (zoom 26.88, 3.1 s; sqlite 60.03,
+ 4.6 s), and in sqlite four more, each a dense caption over a stop
+ (11.38, 7.2 s: the arguments; 24.57, 3.2 s: the two more rows, now
+ that a continue is a wave and a 36 f hold and not a cascade's longest
+ hold; 32.95, 3.2 s: the commit's backtrace; 50.03, 4.9 s: the page's
+ header), its fields framed as it names them.
## What is not done
- Back pointers between nodes still run under the nodes: a page keyline
round each pin's stub and head shows them passing behind it (there is
no lane for them in `beside`).
-- Names keep their side when one of two leaves a pin and when a pin's
- name travels; a name that arrives where another already is takes the
- right, and once it has landed the pin's own order (variables, then
- registers) may put it on the other side. (In the stack's lane, rsp or
- rbp travelling alone keeps its place among the names it leaves and
- joins; both travelling to rows with other names is not handled.)
-- The hexdump's reading of a `char` or `bool` field (the lens's values
- and cells read them by type; the dump's reading column does not).
+- An `under` pin's names are in the order they came to the node (the
+ recording read back from the stop shown), so a name that lands where
+ another is stays on the right it travelled on; but one left alone
+ where it was on the right keeps that side only for the step in which
+ the other left, and takes the left at the next. A third name coming to
+ a pin whose two sides are taken is counted (`+1`), unless it is a
+ variable the scene names and a register holds the right, which it then
+ takes; on its way it is drawn over the right-hand name (list, 7.5 s).
+ A pin's count (`+1`) can run into the left-hand name of the next
+ node's pin (list, 26 to 57 s).
+ (In the stack's lane,
+ rsp or rbp travelling alone keeps its place among the names it leaves
+ and joins; both travelling to rows with other names is not handled.)
+- Pins travel with `time.pin`'s times, but on `standard`, not the
+ catalogue's `glide`, in the stack's lane and the array; a pin in a
+ drawing sets off when the idea strikes (the projection's arrival),
+ not 18 f after its word's strike.
+- The disassembly scrolls or fades over the mark's advance: 24 f where
+ the source's window moves too, 12 f where the mark only jumps.
+- Whether the stack's window faded at a step is judged by the slots it
+ shows now: after a relayout to fewer, a step that scrolled may lose
+ its ticks.
+- A frame's name on a `call` span is never cut (`metric.span.name_max`,
+ 300 units, is not built); the calls tree's small and folded sizes are
+ not built.
- A link to a slot past the stack's window ends in its stub and row count:
drawn in the sqlite scene only (rsi to the struct on the caller's
- stack, `23 rows`, 4.2 s).
+ stack, `23 rows`, 5.0 s; in a continue a link sets off with memory's
+ strike, when the window is at its new place). One to a slot above the
+ window would put its count over the panel's tag.
- The calls tree's leaf spacing holds for fib(5); past about ten leaves
nodes and badges collide (the catalogue's known case).
- `heap` and `pages` lenses are not in the band (`Timeline` is the old
@@ -222,11 +248,10 @@ What fires, and why it is left:
- A program's frame arguments are in the backtrace only for calls the
recording tells (an instrumented program's); at a breakpoint the
callee's are in its registers, which the scene's captions name.
-- The sqlite scene changes what is over the band (the backtrace, then the
- kernel's side) and its view (the SQL at rbx, the row, the page) by a
- fade, not by a verb of the catalogue; the backtrace in the band's
- drawing is a split the catalogue does not have (`subject` with the
- backtrace where the drawing goes: eleven rows).
+- The sqlite scene changes what is over the band (the backtrace lens,
+ then the kernel's side) and its view (the SQL at rbx, the row, the
+ page) by fades scripted in the scene (12 f out, then 12 f in); the
+ kernel's side does not bring its elements in as at `establish`.
- `zig build test` prints "failed command" for each scripted scene: that
is the run echoing its stderr (the Vulkan headless warning), not a
failure; the summary line is the verdict.