diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 18:06:30 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 19:01:23 -0300 |
| commit | e63b0624f57472d40af32a006c32cc47d403b822 (patch) | |
| tree | b7295da62acd96bc7aba425720eed95605526693 /anim/README.md | |
| parent | 318e16181a28725e218121363555580725d6d0d4 (diff) | |
| download | computeranim-e63b0624f57472d40af32a006c32cc47d403b822.tar.gz computeranim-e63b0624f57472d40af32a006c32cc47d403b822.zip | |
canim: what the review found; the band as two panels; list and sort by instruction
The first videos were reviewed frame by frame and the catalogue changed
with them. A lens is a drawing over the program column and its view over
the state column, so the stack keeps six slots, its window on the whole
frame. Operands are whole. list and sort are recorded by instruction
from main (record --from), so their registers strike, links reach nodes
and cells, rows that ran are marked and jumps are drawn. A call's node is
a projection of its return address; pins travel and keep their side; a
mark covers the bytes that changed, at the element's width; a syscall's
result is stored after the kernel returns it and every panel is of one
moment; fast passes are veiled; the clock stands still during a step;
captions get their reading time and a scene's first step comes by four
seconds.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'anim/README.md')
| -rw-r--r-- | anim/README.md | 136 |
1 files changed, 80 insertions, 56 deletions
diff --git a/anim/README.md b/anim/README.md index 74596bb..57beeb5 100644 --- a/anim/README.md +++ b/anim/README.md @@ -63,9 +63,10 @@ a later one (`Recording.Stop`: `.moment`, `.line`, `.over`, `.call`, `.syscall`). For each step it writes a timetable, a `Plan`: the cascade. The line fires (12 f); each level the step touched strikes 18 f after the one before, in the order CPU, memory, idea (a level the scene does not show, or -the step did not touch, gives up its slot; a drawing made of bytes strikes -when the projection from them arrives, 24 f after them, and its write 12 f -later still); the writes of one step strike 6 f apart; a hold to read; the +the step did not touch, or touched nothing drawn, gives up its slot; a +drawing made of bytes strikes when the projection from them arrives, 24 f +after them, and its write 12 f later still; a call's node when the +projection from its return address does, 36 f after); the writes of one step strike 6 f apart; a hold to read; the 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`, @@ -79,19 +80,19 @@ 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 | -| 1 atom | `address` (`lead`, `name`, `rwx`), `value`, `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 | +| 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`, `allocator`, `unread`; `pad` | | 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; `current`, `ran`, `ahead`, `outside`; the annotation from the moment's `touch` and `branch` | -| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's `call` spans and the backtrace from `zt.telescope.frames` | +| | `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; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames` | | | `source` | `src/source.zig` | the whole file in a window, its middle third | -| | `disasm` | `src/disasm.zig` | 17 rows (11 as subject), fewer above near a function's start | -| | `hexdump` | `src/hexdump.zig` | a lens's right half: `bytes` rows and their reading | -| | lenses: `nodes`, `array`, `calls`, `syscalls` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`) | in the band; `nodes` and `array` with their dump | -| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, draws in the channels | -| 5 frame | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject` (`theme.layout.split`) | -| | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the title card is `scenes/title.zig` | -| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `advance`, `cascade`, `run`, `sprint`, `establish`, `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time` | +| | `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 | +| | 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 | +| 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`) | `Recording` (`src/Recording.zig`) is the index every block reads: lines, calls, syscalls, allocations, which registers and bytes each moment changed @@ -104,58 +105,81 @@ and read (a debugger's `touch` reads count), each moment's `touch` and debugger: registers, the stack, what they point at, the instructions round the pc with their lines and callees' parameter counts, at every stop), each by a bare name in a directory of its own with an empty environment, without -address randomisation. The instrumented ones are built `-no-pie`, so their -code and heap have short addresses as the design's columns expect. +address randomisation, with the tools built `ReleaseFast` (a step through +the agent's or the runtime's code is a moment, and a slow tracer stretches +the clock's retry loops it steps through). The instrumented ones are built +`-no-pie -fno-stack-protector -Wl,-z,now`: short addresses, no resolver +and no canary stepped through that the source does not say. -| Name | Program | Stops | Also | -| --- | --- | --- | --- | -| `steps` | `fib.c`, static musl, `-O0` | every instruction | | -| `hello` | `hello.c`, static musl | every line | reads `tools/note` | -| `sort` | `sort.c` built by `ztrace cc` (`calls,vars,stores,loads`) | every line | `--ring` | -| `list` | `list.c` built by `ztrace cc` (`calls,vars,stores,loads`) | every line | `--alloc --preload` the agent: allocator headers are read | -| `gallery` | a copy of `list`, kept in `test/gallery/list.ztrace` | | the gallery's pictures depend on the drawing only | +| Name | Program | Stops | Moments, bytes | Also | +| --- | --- | --- | --- | --- | +| `steps` | `fib.c`, static musl, `-O0` | every instruction | 1999, 336 KB | | +| `hello` | `hello.c`, static musl | every line | 233, 101 KB | reads `tools/note` | +| `sort` | `sort.c`, `ztrace cc --instr vars --only sort,a` | every instruction, `--from main` | 5076, 617 KB | `--ring`: the variables' names and types; each `__zt_var` call is stepped (4 of them) | +| `list` | `list.c`, `ztrace cc --instr vars --only push,reverse,head` | every instruction, `--from reverse` | 3421, 528 KB | `--alloc --preload` the agent: allocator headers are read; the pushes (the agent's and the runtime's first calls) run through | +| `gallery` | the old `list` by line, kept in `test/gallery/list.ztrace` | | 134, 88 KB | the gallery's pictures depend on the drawing only | + +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 +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 +holds is named from its module's first mapping (`list+2c89`). ## Motion, as measured -`tools/chart.py chart` on the 1080p exports (the designer's five checks; the -baseline is `design/motion.md`'s table, measured before the frame changed): +`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. | | fib | list | sort | syscalls | zoom | | --- | --- | --- | --- | --- | --- | -| POP, before / now | 68 / 0 | 40 / 0 | 35 / 0 | 0 / 0 | 1 / 0 | -| CROWD, before / now | 75 / 7 | 43 / 2 | 44 / 10 | 4 / 5 | 5 / 4 | -| METRONOME, before / now | 68 steps / none | 15 / none | 36 / none | 4 / none | none | -| RUSH, now | 0 | 0 | 2 | 1 | 0 | -| seconds | 40.6 | 59.3 | 39.5 | 34.8 | 30.2 | +| POP, round 2 / 3 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | +| CROWD, round 2 / 3 | 7 / 2 | 2 / 7 | 10 / 5 | 5 / 1 | 4 / 3 | +| RUSH, round 2 / 3 | 0 / 0 | 0 / 2 | 2 / 0 | 1 / 2 | 0 / 0 | +| AIR, round 3 | 0 | 0 | 1 | 0 | 1 | +| seconds, round 3 | 41.5 | 60.5 | 46.7 | 38.2 | 32.0 | -What still fires, and why it is left: +What fires, and why it is left: -- CROWD at each `advance` that crosses a function (source, disassembly and - rip move together: the catalogue's `advance` says they are one mark), - inside `run` and `sprint` stretches (steps that are not to be read), and - in fib at 22.25 s: a one-frame change in the disassembly and the stack on - a step's first frame, beside the fire, not yet found. -- AIR at each scene's opening: the designed stillness, 1 s and 0.5 s a panel. -- RUSH in sort and syscalls at the last caption: the last step's cool and - ticks still settle under it. +- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 22.28 are the + veil coming over the registers, stack and disassembly at the first + shortened step (one veil over three panels); sort 9.60 and 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 31.82 and 34.12, syscalls 35.05) 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.17 and 29.52: a caption + arrives, and the next change the instrument sees is the keyframe at + 30.00 (a fade of every region over one frame, 0.00% at its peak). +- AIR: the last caption's reading time and the 2 s on the finished + picture (sort 42.17, 4.6 s; zoom 26.88, 3.1 s). ## What is not done -- The instrumented recordings (`list`, `sort`) clobber registers between - lines, so their registers are `quiet` (no strikes, no links) and their - pins name variables. A `--by insn` recording of `list` with only `vars` - is 1.6 M moments (the loader and libc start-up): too many. So `link`, and - `ran` rows with the jump lane, are seen in the scenes of `steps` (fib, - zoom) only; a recording by line knows no instructions between its stops. -- `establish` for a lens (its elements rising from their rows by - projection) is not drawn: lenses fade in with the panels. -- The `thread`'s brackets on the disassembly change runs at the middle of - the advance; only the source's slides. -- `value` classes `fd`, `flags` (other than rip's), `bool`, `char` are not drawn. -- Back pointers between nodes run under the nodes and can cross a pin's stub. -- `heap` and `pages` lenses are not in the band (`Timeline` is the old far view). -- The camera rests at x2 in `zoom` (the stack of the `none` split fills it); - x1.5 is supported (`theme.camera.scales`) but no scene uses it. -- `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. +- 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. +- 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). +- A link to a slot past the stack's window ends in its stub and row count + (`12 rows`); no scene's link has such a target, so it is drawn in no + export. +- 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 + far view). +- SQLite (the next rung) is not started. +- `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. |
