summaryrefslogtreecommitdiff
path: root/anim/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'anim/README.md')
-rw-r--r--anim/README.md161
1 files changed, 98 insertions, 63 deletions
diff --git a/anim/README.md b/anim/README.md
index 9878765..74596bb 100644
--- a/anim/README.md
+++ b/anim/README.md
@@ -2,29 +2,26 @@
Animations of how a program ran, from a `ztrace` recording, on sketchbook's
`anim` (live scenes). The frame is a debugger's whole context, as pwndbg
-shows it, with one lens beside it; how it looks is `../design/README.md`
-(revision 2) and how it moves is `../design/motion.md`.
-
-**State of this tree: mid-change, handed over.** The motion model (a step as
-a sentence) and the context frame are in and every scene builds and runs;
-the look was not checked against the design's mocks after the last round of
-changes, and the scripted tests only check that scenes run. See "What is
-not done" at the end.
+shows it, with one lens over it; the names, sizes and colours of everything
+in it are the design language's catalogue (`../design/README.md`), and how
+it moves is `../design/motion.md`. Code and design share one set of names:
+a block of the catalogue is a function or a component of the same name here.
```sh
zig build record # the recordings, into zig-out/recordings
zig build run -Dscene=fib # a scene in a window, hot reload (zig build lib --watch)
zig build export -Dscene=fib -- DIR --fps 60 --size 1920x1080 # frames as PNGs (or - for raw RGBA)
zig build videos -Doptimize=ReleaseFast # every scene: out/NAME-1080.mp4 and out/NAME-2160.mp4 (x264, 60 fps)
-zig build test # unit tests, and each scene run headless
+zig build test # unit tests, each scene run headless, and the gallery against its pictures
+zig build gallery # the gallery's pictures drawn anew into test/gallery
zig build bench # what a recording costs a frame
zig build bench -- NAME BY [FUNCTION] # a recording's steps (BY: moment, line, over), with what each changed
python3 tools/chart.py chart out/fib-1080.mp4 --out out/motion/fib # the designer's timing chart and five checks
```
-Needs what sketchbook and ztrace need, and `setarch`, `clang++` and
-`llvm-config` (the pass plugin), `ffmpeg` (videos), python with numpy and
-Pillow (charts). Dependencies are by path (`..` is ztrace, `../../sketchbook`,
+Needs what sketchbook and ztrace need, and `setarch`, `clang` (the pass
+plugin), `ffmpeg` (videos), python with numpy and Pillow (charts).
+Dependencies are by path (`..` is ztrace, `../../sketchbook`,
`../../02-pardes-code`); `zig-pkg` is a symlink to pardes's.
## A scene
@@ -39,88 +36,126 @@ pub const scene = anim.Live(frame, struct {});
fn frame(s: *anim.Frame) void {
const rec = canim.open(recordings.steps); // a recording the build made and embedded
- const split = canim.layout.split.beside; // how the program column is shared
var at = canim.cursor(s, rec, rec.lineMoment(10, rec.call("main", 0).enter));
- at.levels = .{ .idea = .calls, .source_rows = 8 }; // what a step is timed by
+ at.levels = .{ .idea = .calls, .source_rows = 10 }; // what a step is timed by
at.journey(.line, rec.call("fib", 0).exit.?); // the clock's whole way
- const ctx = canim.context(s, at, .{ .split = split }); // source, disassembly, registers, stack, backtrace, clock
- const tree = canim.callTree(s, .{ .cursor = at, .box = split.lens, .function = "fib", .focus = true });
- const joins = canim.ties(s, .{ .cursor = at }); // connections between panes; add it last
+ // The stage: the band (the lens) over the program column and the state column.
+ const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject });
+ const tree = canim.callTree(s, .{ .cursor = at, .stage = ctx.stage, .function = "fib" });
+ const joins = ctx.ties(s); // thread, link, projection; add it last
var says: canim.Narrator = .{};
- canim.establish(s, .{ ctx.clock, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace, tree, joins });
+ canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, tree, joins });
says.line(s, "`fib` calls itself."); // old caption out, a gap, new one in, then stillness
at.walk(s, .line, rec.lineMoment(6, rec.call("fib", 0).enter)); // each step in full, timed by its content
at.hurry(s, .line, rec.call("fib", 4).enter, .{}); // a run: ramps in and out, counted on the clock
- at.hurry(s, .line, rec.call("fib", 10).exit.?, .{ .pace = canim.theme.time.sprint });
+ ctx.stage.relayout(s, canim.layout.split.none); // a change of split, 48 f
s.wait(canim.theme.time.before_cut);
}
```
`frame` runs every frame and builds the whole timeline each time; a
component is an `anim` object (`fadeIn`, `fadeOut`) that draws the program's
-state at the cursor.
+state at the cursor, at the box its `Stage` gives it now.
**The cursor** (`src/cursor.zig`) moves in steps from one moment straight to
a later one (`Recording.Stop`: `.moment`, `.line`, `.over`, `.call`,
-`.syscall`). For each step it writes a timetable, a `Plan`: the line fires
-(0.20 s); each level the step touched strikes 0.30 s 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 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`, `syscalls.step`). Components read it
-through `Cursor.now(at)`: `landed(level)`, `shown(level)`, `written(addr,
-size, level, delay)`, `register(i, delay)`, `reading(level)`, `moving(level,
-lead, seconds)`, `fires(view)`, `advancing()`, `marks`.
+`.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
+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)`.
## The blocks
-| Block | File | Reads | Use |
+The catalogue's layers, and where each block is. Every block is drawn in
+every state the code has in the `gallery` scene.
+
+| Layer | Block | Where | Notes |
| --- | --- | --- | --- |
-| `Recording` | `src/Recording.zig` | every moment once, at open | the index: lines, calls, syscalls, allocations, which registers and bytes each moment changed; `next`, `lineMoment`, `call`, `variable`, `assigned`, `instruction`, `viewFirst` |
-| `ui.Ui` | `src/ui.zig` | | rects, text on a baseline, `panel`, `value` (a value by its class), `chainArrow`, `struck`/`readFrame` (marks in the context), `written`/`readMark` (marks in a lens's cell), `arrow`, `clip`, `veil` |
-| `context.chain` | `src/context.zig` | `zt.telescope.chase` | a value followed as far as it points, each link in its region's ink |
-| `Registers` | `src/context.zig` | `Moment.regs`, mappings | 18 rows: sixteen, rip (a current mark), the flags; options `syscalls`, `quiet` |
-| `Stack` | `src/context.zig` | `Moment.regs`, `Moment.read` | eight words from rsp as a telescope, plaques for rsp and rbp, frame notes |
-| `Backtrace` | `src/context.zig` | `zt.telescope.backtrace` | the call chain by frame pointer, newest on top |
-| `Disasm` | `src/context.zig` | the recorded instructions | rows round the pc in address order, the pc's row fixed |
-| `Source` | `src/source.zig` | `Moment.line` (the index) | the whole file in a window, pardes's colours, the current mark and its trail |
-| `Clock` | `src/words.zig` | the cursor | the progress rule over the caption, `moment N of M`, the step counter |
-| `Caption`, `Narrator` | `src/words.zig`, `src/root.zig` | | the narrator's sentence, one at a time |
-| `CallTree` | `src/calls.zig` | the index of calls | lens: every call of a function as a tree |
-| `Nodes` | `src/nodes.zig` | `Moment.variables`, `Moment.read`, `Moment.allocation`, types | lens: structs the program's pointers reach, as nodes and arrows, with variable tags |
-| `Hexdump` | `src/hexdump.zig` | `Moment.read`, `Moment.allocation`, types | lens: sixteen bytes a row, each word marked as what it is |
-| `Array` | `src/array.zig` | `Moment.variables`, `Moment.read`, reads and writes | lens: an array's cells, index tags, values in flight |
-| `Crossing` | `src/syscalls.zig` | the index of syscalls | lens: the kernel's side of a system call, on vellum |
-| `Ties` | `src/ties.zig` | anchors the others publish | connections between panes: the gold thread, the step's link, a written word and its node |
-| `Camera` | `src/root.zig` | | announced moves: `go(box, zoom, others)`, `back(others)`, `apply` |
-| `Locals`, `Memory`, `Heap`, `Timeline`, `Legend`, `Label`, `Veil` | `src/registers.zig`, `memory.zig`, `heap.zig`, `syscalls.zig`, `words.zig` | | first-pass blocks, still built; only `Legend` and `Label` are used (the title card) |
+| 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 |
+| | `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` |
+| | `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` |
+
+`Recording` (`src/Recording.zig`) is the index every block reads: lines,
+calls, syscalls, allocations, which registers and bytes each moment changed
+and read (a debugger's `touch` reads count), each moment's `touch` and
+`branch`, and each instruction's line.
## The recordings
`build.zig` records four programs of `tools/` under `ztrace record` (the
debugger: registers, the stack, what they point at, the instructions round
-the pc, at every stop), each by a bare name in a directory of its own with
-an empty environment, without address randomisation:
+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.
| 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`) | every line | `--alloc --preload` the agent |
+| `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 |
+
+## 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):
+
+| | 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 |
+
+What still 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.
## What is not done
-- The look was not compared with `design/mock/09` to `11` after the frame
- changed; the designer's later notes (a catalogue of blocks, ties as a
- design form, the disassembly's annotations) are not in.
-- The disassembly has no operand note, no call, jump or return annotation
- (`touch` and `branch` events are not read).
-- The motion checks (`tools/chart.py`) were last run before the frame
- changed; no scene is known to pass them now.
-- `test/*.script` only run each scene to three instants; there are no pixel
- assertions and no gallery.
-- 4K exports and performance at the context's density were not measured
- after the change.
+- 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.