summaryrefslogtreecommitdiff
path: root/anim/README.md
blob: 74596bbb03922a3bfcbfa70f3359ce1865ecdb15 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# canim

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 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, 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` (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

```zig
const anim = @import("anim");
const canim = @import("canim");
const recordings = @import("recordings");

pub const background = canim.background;
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
    var at = canim.cursor(s, rec, rec.lineMoment(10, rec.call("main", 0).enter));
    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
    // 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.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
    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, 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 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

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 |
| --- | --- | --- | --- |
| 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 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,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 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.