summaryrefslogtreecommitdiff
path: root/design/motion.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/motion.md')
-rw-r--r--design/motion.md773
1 files changed, 773 insertions, 0 deletions
diff --git a/design/motion.md b/design/motion.md
new file mode 100644
index 0000000..6b2798c
--- /dev/null
+++ b/design/motion.md
@@ -0,0 +1,773 @@
+# Motion
+
+How things move in a canim frame, in what order, and for how long.
+[`README.md`](README.md) gave durations and curves. This is the direction
+that uses them, written after measuring the first five scenes frame by
+frame. Where the two disagree this one wins; the tokens to change are under
+[Revised tokens](#revised-tokens).
+
+Times are at 60 frames a second: "12 f" is twelve frames, 0.20 s.
+
+## What was measured
+
+The five scenes as exported (30 fps, build of 13:01), with
+[`motion/motion.py`](motion/motion.py): a timing chart of each
+([`motion/charts/`](motion/charts)), contact sheets of every transition
+looked at ([`motion/sheets/`](motion/sheets)), and five rule checks.
+
+| | fib | list | sort | syscalls | zoom |
+| --- | --- | --- | --- | --- | --- |
+| seconds | 30.8 | 39.3 | 36.6 | 13.8 | 25.8 |
+| CROWD: three or more panels begin on the same frame | 75 | 43 | 44 | 4 | 5 |
+| POP: a change with no frames in between | 68 | 40 | 35 | 0 | 1 |
+| METRONOME: longest run of evenly spaced steps | 68 at 0.25 s | 15 at 0.25 s | 36 at 0.25 s | 4 at 3.0 s | |
+| walked steps exactly 1.5 s apart | 8 | 7 | 14 | | |
+| seconds between the first caption and the first step | 0.0 | 1.5 | 0.0 | 0.0 | 0.0 |
+
+Three things account for nearly all of it:
+
+1. **A step spends itself on its first frame.** The line's mark, the
+ registers, the bytes and the idea drawn from them all start together
+ and are done in 0.25 s; then 1.25 s of stillness. One change is seen,
+ three are missed, and nothing says which caused which.
+2. **Steps tick.** A walked step is 1.5 s whether it moved a line or pushed
+ a call through four panels.
+3. **Run is a strobe.** 0.25 s a step with nothing eased: whole panels
+ replaced four times a second, for 17 of fib's 31 seconds.
+
+## The direction
+
+### What motion is for
+
+Four jobs, and a movement that does none of them is a cut:
+
+- **Where to look next.** An onset pulls the eye. So onsets come one at a
+ time, and each is where the next thing to understand is.
+- **What caused what.** Cause moves first; its effect follows. Order on the
+ timeline is the argument.
+- **This is the same thing.** What persists slides; what begins or ends
+ fades. A plaque that teleports is two plaques.
+- **Now.** A change has an instant. The strike marks it; everything before
+ is preparation and everything after is reading time.
+
+The viewer listens, reads and watches, and can do one of the three well.
+Nothing moves while a caption arrives. Nothing arrives while something
+moves. The eye takes about a quarter of a second to get anywhere, so two
+onsets in different panels are at least 0.30 s apart.
+
+### A step is a sentence
+
+A step is one line (or one instruction) doing its work. It is drawn in the
+order it would be said:
+
+> *this line* → *changes this* → *which changes that* → *next.*
+
+1. **Fire** (12 f). The current mark is on the line about to run. Its
+ plaque pulses once. Nothing else moves.
+2. **Effects, a level at a time**, 18 f apart, in the order they were
+ caused: CPU (registers), then memory (bytes, words, the heap strip, the
+ locals table), then the idea drawn from them (stack cards, call tree,
+ list nodes, array cells). A level the scene does not show gives up its
+ slot. Each effect is *armed* for 12 f (a frame round the cell, the old
+ value still in it) and then struck.
+3. **Hold.** 36 f after the last strike, 12 f more for each further value,
+ 84 f at most. The gold line and the vermilion values are on screen
+ together: the line, and what it did.
+4. **Advance** (12 to 24 f). The mark moves to the next line. This is the
+ step's follow-through and the next step's anticipation.
+5. **Rest** (24 f). The next line is read.
+
+**The mark goes last.** The exported scenes move it first, and so does the
+working tree's `cursor.lead` (`source = 0.0`). That is a debugger's
+convention, and it puts gold on the line that has *not* run while the
+strikes show what the line before it did: in `list` at 5.27 the mark lands
+on `n->next = head;` as `7` is struck into `value`. Execute, then advance,
+and gold always names the cause of what is red.
+
+A step's length follows from its content:
+
+| A step that | Frames | Seconds |
+| --- | --- | --- |
+| only moves the line | 12 fire + 12 advance + 24 rest | 0.8 |
+| writes one register (or one word, or one cell) | 18 + 36 + 12 + 24 | 1.5 |
+| writes a register and memory | 36 + 48 + 12 + 24 | 2.0 |
+| makes or returns from a call, three levels shown | 54 + 60 + 12 + 24 | 2.5 |
+| swaps two cells | 54 + 36 + 12 + 24 | 2.1 |
+| crosses into the kernel | see the chart | 3.7 to 4.8 |
+
+So a walk has the program's rhythm and not a clock's.
+
+### The principles, here
+
+**Timing and spacing.** A change takes 0.1 to 0.6 s and is then held for
+at least twice that and at least as long as it takes to read:
+
+| To read | Seconds |
+| --- | --- |
+| that something was struck | 0.25 |
+| a byte, a small decimal | 0.3 |
+| a group of four hex digits | 0.5 |
+| the end of an address against another (nobody reads twelve digits) | 0.6 |
+| a line of code, first time; again | 0.8; 0.3 |
+| a caption | 1.5 + 0.06 a character |
+| a frame of n panels, on first sight | 1.0 + 0.5 n |
+
+Spacing is where the frames of a move fall. Measured on the swap in `sort`
+the card is fastest on the first frame it moves and slows from there (35,
+24, 17, 13, 10, 8, 7 pixels a frame), then creeps for eight frames more: a
+jump and a crawl, not an arc
+([sheet](motion/sheets/sort-20.4-swap-onion.png)). The curve does that,
+not the duration; see the next principle. Duration follows distance: the
+mark takes 12 f for one row and 2 f more for each further row; a flight 30,
+36 or 48 f.
+
+**Slow in and slow out.** Three curves do the work.
+
+| Curve | cubic-bezier | Peak speed | For |
+| --- | --- | --- | --- |
+| `standard` | 0.3, 0, 0.2, 1 | 2.6 x mean, a quarter of the way in | the mark, cards, tags, arrows growing, rows making room: things that answer the program |
+| `glide` | 0.45, 0, 0.55, 1 | 1.8 x mean, at the middle | things with weight: a value in flight, the camera, a layout, a colour cooling |
+| `linear` | | | time itself: the progress line, a counter, the playhead; and opacity |
+
+`standard` today is 0.2, 0, 0, 1: half the distance in the first fifth of
+the time, a peak of 4 x mean on the second frame. `camera` today is
+0.65, 0, 0.35, 1: 4% of the way after a fifth of the time, then 2.9 x
+mean. Both read as a pop with a tail. `enter` (0, 0, 0.2, 1) starts at
+full speed and is kept only for a fade that rises 8 units; `exit` for a
+fade that leaves.
+
+A strike is not eased in position, because nothing moves; its fill comes
+in over 6 f so that a cell does not flash in one.
+
+**Anticipation.** The eye is told where before it is told what.
+
+| Before | The cue | Frames |
+| --- | --- | --- |
+| a line runs | its plaque pulses | 12 |
+| a value changes | a 3-unit write-coloured frame round its cell, old value still inside | 12 |
+| a pointer turns | its old arrow goes dashed and faint | 12, with the arm |
+| a value flies | it lifts: a card, 1.12 of its size, 6 units off the cell | 6 |
+| the camera moves | a bright frame on the target; everything else leaves | 24, 18 |
+| the pace changes | the steps before it shorten or lengthen | 3 or 4 steps |
+| a caption's subject | the caption, alone on a still frame | 60 or more |
+
+No wind-up: nothing draws back before it goes. (`cursor.anticipation`, a
+cell shrinking before its pulse, should go; on a 46-unit cell it is two
+pixels of cartoon.) No anticipation at run or sprint.
+
+**Staging.** One idea at a time.
+
+- One onset at a time, 18 f apart. Two panels that show the same bytes (the
+ heap strip and the words) start together; only the one in focus pulses.
+- What cannot be read at the current pace is veiled: registers and bytes
+ during a sprint. What is not the subject of a camera move is gone before
+ it starts.
+- The subject is never at the edge. At x2 the rows about to change are in
+ the middle of the frame, and no row is cut by the stage's edge.
+- A layout is stable. A row, a node, a card or a divider that appears makes
+ room first; nothing else jumps because it came.
+- One caption at a time. The old one leaves (12 f), six frames of nothing,
+ the new one arrives (18 f). Two captions crossfading are an unreadable
+ third ([sheet](motion/sheets/zoom-08.7-out-and-in.png), f304).
+
+**Follow-through and overlapping action.** The cascade is the overlap: each
+level starts while the one before is still solid. After that:
+
+- A strike is followed by its cool, 36 f later, starting as the mark
+ leaves. The digits change face at the middle of the cool, where the
+ colour is moving fastest and hides it.
+- A pointer's word strikes first; its arrow leaves 6 f later and takes 24 f;
+ the row or node it lands on is framed bright for 12 f. The cell is the
+ cause, the arrow the consequence, the landing the point.
+- Of two things doing the same (two flights, four registers read, sixteen
+ bytes copied) the second starts 6 f after the first; bytes of one write,
+ 1 f apart, low address first; bytes copied by the kernel, 2 f apart.
+- What leaves has left before what replaces it arrives.
+- Nothing settles by bouncing. A flight's card is back to size on its last
+ 6 f and the strike is its impact.
+
+**Arcs.** Ideas move on arcs; the machine moves on wires.
+
+- A value between cells of an array, or between nodes: an arc a quarter as
+ high as it is long (34 to 120 units), on `glide`, so it is slowest at
+ lift-off and landing and quickest over the top. A swap is one over and
+ one under.
+- A value between a register and memory, or across the kernel's line: along
+ a square-cornered path, as a flow arrow draws it. Machines do not lob.
+- A variable following a pointer (`cur = cur->next`): its tag travels the
+ arrow it followed.
+- The mark moves straight up and down its gutter. The camera moves in a
+ straight line and zooms by ratio (interpolate the logarithm of the scale),
+ or the first half of a move to x2 looks twice as fast as the second.
+
+**Secondary action.** Embers, bars, the trail, flag chips, result badges,
+the step counter and the progress line. They never start on a frame where
+something primary starts, never travel or scale, and only fade. If one of
+them draws the eye it is too strong: the digit pop at the middle of each
+cool does, in every scene, 0.8 s after each strike.
+
+**Exaggeration and appeal.** The look is sober, so the budget is small and
+spent in three places: the pulse of a strike, the lift of a flight, the
+fire of a line. Appeal here is exactness: everything lands on the grid, on
+whole pixels, on the beat; the same event takes the same frames every time.
+No bounce, no elastic, no rotation, no blur, no smear frames.
+
+**Squash and stretch.** Only the pulse, and not as a scale. At 8% a
+register's cell grows 27 units sideways and 3 up, and two struck rows merge
+([sheet](motion/sheets/fib-02.2-register-strike-and-cool.png), f70). The
+pulse is an outset of 4 units on every side, whatever the cell's size, drawn
+over its neighbours; the digits do not move.
+
+**Pose to pose.** Every rest state is a still that was designed (the
+mocks). Motion is the way between two of them and is never the only place
+something is shown.
+
+### The rhythm of a scene
+
+**Open.** Head and panels fade in 6 f apart, source first (18 f each).
+Then stillness: 1.0 s and 0.5 s a panel. Then the first caption, and 2 s
+more. A scene's first step is never before 4 s.
+
+**Beats.** The beat is 0.5 s. Steps are as long as their content; a
+*phrase* (one trip round a loop, one call and its return) ends with a rest
+of one beat. Three steps and a rest is a bar, and a loop is heard as bars.
+
+**Breath.** A step the narration names has its caption up a second before
+it fires and holds a beat longer after. Captions change only in a rest. No
+caption stands longer than 12 s; if there is nothing to say for longer, the
+scene is too long there.
+
+**Pace.**
+
+| | A step | What is drawn | When |
+| --- | --- | --- | --- |
+| walk | by content, 0.8 to 2.5 s | everything | the first time anything happens, and whatever the narration names |
+| run | 0.30 s | the mark glides (8 f); cards, nodes and arrows ease (8 f); values get embers, never solids; no fire, arm or pulse | a pattern seen once in full; 24 steps at most |
+| sprint | 0.067 s or less | structures grow; embers; the mark only at phrase ends; registers and bytes veiled | everything longer |
+
+A run keeps its bars: 12 f of rest at each phrase end. A sprint does not.
+
+**Changing pace** is never a switch.
+
+- Into a run: four steps, each 0.6 of the one before (1.5, 0.9, 0.54,
+ 0.32). Out of it: three steps lengthening the same way, then one beat of
+ stillness before the walked step that the run was heading for.
+- On the first shortened step the panels that cannot be read at speed take
+ the veil (18 f), and the head's `where` gains a counter, `step 41 of 212`.
+- A 3-unit gold line grows along the head's rule with the cursor's place in
+ the recording, linearly. At a walk it is still; in a sprint it sweeps.
+ It is the scene's clock, and the only thing on screen that says "fast".
+- The caption says it too: "and so on, down to `fib(1)`".
+
+**Close.** The last step's hold, then 2 s on the finished picture. A scene
+ends on its result, read.
+
+## Timing charts
+
+Frames at 60 a second from the step's first frame. *Arm* and *strike* are
+always the same sub-chart:
+
+| Frames | A strike at frame s |
+| --- | --- |
+| s-12 to s | arm: a 3-unit frame in write's colour inside the cell's edge, in over 2 f; the old value unchanged |
+| s to s+6 | the fill comes in, linear; the digits become the new value, bold, in ink, at s+3 |
+| s to s+12 | pulse: the fill's edges go out 4 units and back, sine |
+| s+6 to s+36 | solid |
+| s+36 to s+60 | cool to the ember, on `glide`; the bar is under it from the start; digits to their ordinary face at s+48 |
+| then | ember and bar for three steps; out over 36 f, linear, in the step after |
+
+### A register written
+
+| Frames | |
+| --- | --- |
+| 0 to 12 | fire |
+| 6 to 18 | arm on the value cell |
+| 18 | strike (to 24 in, to 30 pulse, to 54 solid) |
+| 54 to 66 | the mark advances, `standard`; the cool starts (to 78) |
+| 66 to 90 | rest |
+
+Two registers by one step: the second is armed and struck 6 f after the
+first, in the order they were written. rip changes with no mark at frame 18.
+
+### Memory written
+
+The same, one slot later if a register was struck too: arm 24 to 36,
+strike 36. Drawn as bytes, they strike 1 f apart from the low address. The
+heap strip's mark is the same strike at scale, without a pulse. Hold to 84,
+advance to 96, rest to 120.
+
+A row that was not in the grid: the rows below glide down 18 f, the row
+fades in 12 f, and only then is it armed. An unknown byte that becomes
+known without being written fades from dots to digits in 12 f, with no mark.
+
+### A value read
+
+| Frames | |
+| --- | --- |
+| r to r+6 | a 3-unit frame in read's colour and its ember, fading in; no arm, no pulse |
+| to the advance | held |
+| advance to +18 | out |
+
+A read is in the slot of its level. It is gone before the next line fires:
+in `sort` and `syscalls` read frames stand through the rest and vanish in
+one frame.
+
+### A pointer written
+
+| Frames | Memory | The idea (one slot later) |
+| --- | --- | --- |
+| s-12 to s | arm on the word; the old arrow goes dashed and faint | |
+| s to s+6 | strike | arm on the node's pointer square, from s+6 |
+| s+6 to s+30 | the new arrow draws along its lane, head first, `standard` | strike at s+18 |
+| s+30 to s+42 | the row it lands on: a bright 3-unit frame, then 12 f out | its arrow draws, s+24 to s+48 |
+| | | the node it lands on framed, s+48 to s+60 |
+| s+6 to s+54, +18 | the old arrow, dashed, holds, then fades | the same |
+
+A pointer made null draws no new arrow; the old one still lingers, in both
+panels (today only the nodes keep it).
+
+### A pointer followed
+
+`cur = cur->next`.
+
+| Frames | |
+| --- | --- |
+| r to r+6 | the `next` word, and the node's pointer square, framed as read |
+| r+12 to r+36 | `cur`'s tag travels the arrow from node to node, `glide`; in memory its plaque slides down the mark lane |
+| r+36 | the variable's own cell (a local, a register) is struck: it is where the address was written |
+
+36 f of travel when the arrow is longer than 400 units.
+
+### A call pushed
+
+Three levels shown.
+
+| Frames | |
+| --- | --- |
+| 0 to 12 | fire on the line that calls |
+| 6 to 18, 18 | arm, strike: `rdi`, the argument |
+| 24 to 36, 36 | arm, strike: `rsp`; in memory the return address |
+| 42 to 60 | the cards below move down one place, `standard` |
+| 48 to 60 | the new card fades in, 12 units above its place and coming down |
+| 42 to 54 | in the tree, the edge draws from the caller's node |
+| 54 to 60 | the callee's node fades in gold; the caller's goes from gold to a waiting ring |
+| 60 to 114 | hold |
+| 114 to 120 | the mark on the calling line cools to the trail |
+| 120 to 126 | the mark fades in on the callee's first line (the panel scrolls first if it must) |
+| 126 to 150 | rest |
+
+A call is a jump: the mark does not cross the lines between
+([sheet](motion/sheets/fib-02.2-mark-crosses-seven-lines.png): seven lines
+in five frames).
+
+### A return
+
+| Frames | |
+| --- | --- |
+| 0 to 12 | fire on the `return` |
+| 6 to 18, 18 | `rax`: the answer |
+| 24 to 36, 36 | `rsp` |
+| 42 | the top card's result is struck at its right end |
+| 54 | the tree node's badge is struck; the node goes from gold to done |
+| 66 to 78 | the card fades out, rising 12 units, `exit` |
+| 78 to 96 | the cards below move up, `standard` |
+| 96 to 114 | hold |
+| 114 to 126 | the mark jumps back to the caller's line |
+| 126 to 150 | rest |
+
+### The line changes
+
+| | Frames | |
+| --- | --- | --- |
+| to a line 1 to 8 rows away, in view | 12, and 2 a row beyond the first, 24 at most | slides, `standard`; the number appears in the plaque when it lands |
+| a call, a return, more than 8 rows | 6 out, 6 in, the in starting as the out ends | the old place takes the trail's first colour |
+| to a line out of view | 24 before the mark moves | the text scrolls by whole lines, `glide`; never a cut |
+
+The trail shifts without animation.
+
+### A system call
+
+`read(3, buf, 32)`. The kernel's side holds the last call until this one
+arrives.
+
+| Frames | |
+| --- | --- |
+| 0 to 12 | fire on the line |
+| 18, 24, 30, 36 | `rax`, `rdi`, `rsi`, `rdx` framed as read, 6 f each |
+| 48 to 72 | the crossing arrow draws down from the registers through the line, `standard` |
+| 60 to 72 | the last call's name and rows fade out, `exit` |
+| 72 to 84 | this call's name fades in, rising 8 units |
+| 84, 90, 96 | its rows, top to bottom, 6 f each; `returns` shows a dash |
+| 102 to 120 | its card pushes on the kernel's list |
+| 120 to 144 | a flow draws from the kernel up to `buf` |
+| 144 to 176 | the 16 bytes strike 2 f apart; no pulse |
+| 186 to 210 | the arrow back draws up |
+| 198 to 210, 210 | arm, strike: `rax` |
+| 216 | the `returns` row takes the value |
+| 216 to 252 | hold |
+| 252 to 264 | advance |
+| 264 to 288 | rest |
+
+For `write` the work runs the other way: the user's bytes framed as read
+(120 to 126), a flow down (126 to 150), the kernel's cells filling 2 f
+apart. A call with no work (`close`) goes from 120 straight to the arrow
+back: 3.7 s. Nothing on the kernel's side changes before frame 60: the
+kernel does not know the call until it has crossed.
+
+### A swap
+
+The compare in the step before is its anticipation: both cells framed as
+read.
+
+| Frames | |
+| --- | --- |
+| 0 to 12 | fire on the `swap` |
+| 12 to 18 | the first value lifts |
+| 18 to 24 | the second lifts |
+| 18 to 48 | the first flies over, `glide`, 30 f for neighbours |
+| 24 to 54 | the second flies under |
+| 48, 54 | each lands: back to size on its last 6 f, then its cell is struck |
+| 54 to 90 | hold |
+| 90 to 102 | advance |
+| 102 to 126 | rest |
+
+Each cell keeps its old digits, faint, until its own landing.
+
+### A node linked
+
+`n->next = head` is a pointer written (above). A node allocated:
+
+| Frames | |
+| --- | --- |
+| slot 0 | the heap strip's block fades in, 12 f; in the words, rows make room (18 f) and arrive with dots (12 f) |
+| slot 1 | the node fades in, 12 f, with dots in both halves, at its place in the row; nodes after it glide aside first (18 f) |
+
+`head = n`: `head`'s word is struck; its arrow redraws to the new node as
+for any pointer; the other nodes glide to their new places 18 f after the
+arrow lands.
+
+### The camera
+
+In, to x2:
+
+| Frames | |
+| --- | --- |
+| before | the level's caption has been up at least 60 f; nothing is mid-step |
+| 0 to 24 | a bright 3-unit frame on the target (6 f in) |
+| 12 to 30 | everything else on the stage fades out; the head and the caption stay |
+| 30 to 102 | the move, `glide`, on the logarithm of the scale; the frame fades over its first 12 f; the rail's gold square slides to the level |
+| 102 to 138 | still |
+
+Out is the same backwards: the move, then the other panels fade in 6 f
+apart, then 36 f still. Sideways at x2 (registers to stack) is not out and
+in: the target fades out (12 f), the next fades in at x2 (12 f), the rail's
+square slides. 0.5 s instead of 2.6.
+
+The frame at x2 is 896 by 384 units, on the 24-unit grid: the panel's tag
+and as many whole rows as fit, with the rows the next steps will change in
+the middle third. If they move out of it the frame glides a whole row
+(24 f) between steps. The stage clips what the camera shows at y = 112 and
+888. Two seconds at x2 without a change and the camera should not be there.
+
+### Captions, opening, closing
+
+| | Frames |
+| --- | --- |
+| a caption leaves | 12, `exit` |
+| nothing | 6 |
+| a caption arrives, rising 8 units | 18, `enter` |
+| the stage stays still after it | 60; 120 after a scene's first |
+| panels arrive at the opening | 18 each, 6 apart, source first |
+| still before the first caption | 60 + 30 a panel |
+| still on the last picture | 120 |
+
+## Revised tokens
+
+In `anim/src/theme.zig` (and the same figures in `design/README.md`,
+"Motion"):
+
+| Token | Was | Is |
+| --- | --- | --- |
+| `bezier(.standard)` | 0.2, 0, 0, 1 | 0.3, 0, 0.2, 1 |
+| `bezier(.camera)` | 0.65, 0, 0.35, 1 | 0.45, 0, 0.55, 1 (and call it `glide`) |
+| `pulse(t)` | a scale, 1 + 0.08 sin | an outset in units, 4 sin(pi t) |
+| `time.step` | 0.25 | 0.20 |
+| `time.step_per_row` | | 2 f (0.0333) |
+| `time.step_max` | | 0.40 |
+| `time.fire` | | 0.20; the first arm starts at 0.10 |
+| `time.cascade` | | 0.30 between levels |
+| `time.strike.arm` | | 0.20 |
+| `time.strike.in` | 0.10, a wait | 0.10, the fill fading in |
+| `time.strike.cool` | 0.40, linear | 0.40, on `glide`; starts with the advance |
+| `time.read_value` | | 0.60 after the last strike |
+| `time.read_more` | | 0.20 a further value, 1.40 in all |
+| `time.rest` | | 0.40 |
+| `time.walk` | 1.50, every step | 1.50, what a one-value step comes to; not a pace |
+| `time.run` | 0.25 | 0.30 |
+| `time.run_max_steps` | | 24 |
+| `time.sprint` | 0.05 | 0.0667 |
+| `time.phrase_rest` | | 0.50 walking, 0.20 running |
+| `time.ramp` | | 0.6: each step of a change of pace, of the one before |
+| `time.stagger` | 0.03 (1.8 frames) | 2 f (0.0333); bytes of one write 1 f |
+| `time.flight` duration | `travel`, 0.60 | 0.50 to 200 units, 0.60 to 400, 0.80 beyond |
+| `time.flight.second` | | 0.10 after the first |
+| `time.redirect.landing` | | 0.20 |
+| `time.caption_in` | 0.25 | 0.30 |
+| `time.caption_out` | | 0.20 |
+| `time.caption_gap` | | 0.10 |
+| `time.caption_lead` | | 1.00; 2.00 for a scene's first |
+| `time.establish` | `settle`, 0.80 | 1.00 + 0.50 a panel, at a scene's opening |
+| `time.before_cut` | 1.00 | 2.00 |
+| `time.camera_clear` | | 0.30 |
+| `time.camera_dwell_max` | | 2.00 without a change at x2 |
+
+In `anim/src/cursor.zig`: `lead` becomes slots (`0.30` for the first level
+a step touches and `0.30` more for each after it, in the order CPU,
+memory, idea) and the source line goes last; `anticipation` goes; `glide`
+is the curve above; `reading` is the table under "A step is a sentence".
+In `anim/src/syscalls.zig`: `enters` 0.80, `cross` 0.40, the work 2 f a
+byte, `returns` at the frame the chart gives.
+
+Every figure is an even number of frames at 60, so a 30 fps export keeps
+them whole. Review at 60 all the same: at 30, today's 0.25 s run alternates
+steps of 7 and 8 frames.
+
+## The five scenes
+
+In each, most valuable first. Times are seconds into the exported file.
+
+### fib
+
+1. **The run is the scene.** 12.77 to 29.77: 68 steps at four a second,
+ each a single frame in which the mark jumps, a card and a node appear
+ and two registers flash solid ([sheet](motion/sheets/fib-12.8-run.png)).
+ 55% of the running time. Ramp into a run (four steps), run only down the
+ first branch (about 12 steps, with a rest at each call), then sprint the
+ rest with registers veiled and the tree as the subject.
+2. **No return is ever walked.** The three steps shown in full are three
+ calls. What recursion is *for*, an answer coming back in `rax` and a
+ card leaving, happens only inside the run. Slow to a walk for the first
+ return (`fib(1)`, at 14.8) and for the last (`fib(5)` = 5, at 29.77, now
+ a pop one second before the cut).
+3. **Each walked step is one frame wide.** 2.27, 6.77, 11.27: mark, tree
+ node, card and two registers all start at the same frame and finish
+ within eight ([sheet](motion/sheets/fib-02.2-call-all-at-once.png)).
+ Sequence them as "A call pushed".
+4. **Nothing is established.** Panels are whole at 0.43, the caption at
+ 0.73, the first step at 0.77
+ ([sheet](motion/sheets/fib-00.0-opening.png)). Four panels need 3 s and the caption 2 s
+ before anything moves.
+5. **1.5 s for everything.** 5.27 and 9.77 move one line and then wait
+ 1.23 s; 2.27 pushes a call through four panels in the same time.
+6. **The mark sweeps seven lines in five frames** at 2.27, 6.77, 11.27. A
+ call is a jump.
+7. **The digit pop**, 0.80 s after each strike (1.57, 3.07, 4.57, ...):
+ bold ink to ordinary digits with faint zeros in one frame, alone on a
+ still picture.
+8. One caption for 31 s. It needs three: the call, the return, the tree.
+9. Ends 1.0 s after the answer arrives.
+
+### list
+
+1. **The reversal cannot be followed.** The scene exists to show three
+ `next` fields turning. The first turn is walked (22.50) and the other
+ two are in the run at 25.53 to 29.03, a frame each. Walk the first trip
+ round the loop, run the second with its eases and a rest, walk the third.
+2. **Four panels on one frame**, every step: 5.27, 6.77, 21.00, 22.50
+ ([sheet](motion/sheets/list-05.2-write-in-four-panels.png)). Memory
+ first (strip and words together), the node 18 f later, the mark last.
+3. **The rewrite at 22.50 has no anticipation and two endings.** In the
+ words the old arrow vanishes on the strike's frame; in the nodes it goes
+ dashed for 0.8 s
+ ([sheet](motion/sheets/list-22.5-pointer-rewritten.png)). Dash it during
+ the arm, in both.
+4. **Things appear from nothing.** 2.27: the source panel is `main` on one
+ frame and `push` on the next
+ ([sheet](motion/sheets/list-02.2-source-cut.png)). 5.27: a row of memory
+ exists, struck, where there was none. 11.27 to 14.50: two nodes arrive
+ in pops. Scroll, make room, fade in.
+5. **Three empty steps in a row**: 16.50, 18.00, 19.50 each move one line
+ and wait 1.23 s, straight after the caption that promised the reversal.
+ At 0.8 s each they are a lead-in; at 1.5 they are 4.5 s of nothing.
+6. Captions crossfade at 14.80 and 29.03: at 14.87 both are on screen, one
+ over the other.
+7. Node bodies change pigment whenever `cur`, `prev` or `next` moves on:
+ colour changes that are not writes, every step of the loop. Keep the
+ pigment on the variable's tag and plaque.
+8. The frees (30.77, then 35.27 to 38.03) are pops. Walk one, run two.
+
+### sort
+
+1. **The first swap is at 20.5 of 36.6 s.** Twelve walked steps (2.27 to
+ 18.77) show three trips round the loop in which nothing swaps. Walk one,
+ run two, and reach the swap by 10 s.
+2. **The caption about the swap arrives 0.2 s before it** (20.30, the
+ flights lift at 20.50). Bring it up at the rest before, and hold 2 s.
+3. **The flights are a jump and a crawl.** Lift 0.10 s; two frames later
+ the cards are two fifths of the way; they spend their last eight frames
+ (0.27 s) on the final few units, hovering over the faint digits they are
+ about to replace
+ ([sheet](motion/sheets/sort-20.4-swap.png)). `glide`, 30 f, the second
+ 6 f behind the first.
+4. **Both cells strike on one frame** (21.23) and their pulses merge into
+ one block. One lands, then the other; the pulse is an outset.
+5. **36 steps, swaps and compares alike, in a 9 s strobe**, 26.53 to
+ 35.27. Run two trips, sprint the rest, slow for the last swap.
+6. Read frames from each compare stand through the rest and vanish in one
+ frame at the next step
+ ([sheet](motion/sheets/sort-06.7-step.png), f202 to f203).
+7. Every third step (5.27, 9.77, 14.27, 18.77) moves one line and waits
+ 1.25 s.
+8. The sorted array is on screen for 1.0 s and nothing says it is sorted.
+
+### syscalls
+
+1. **Effect before cause.** At the first frame of each step (3.77, 6.77,
+ 9.77) the kernel's side already shows the new call, decoded, with its
+ card pushed ([sheet](motion/sheets/syscalls-03.7-kernel-pops.png)); the
+ arrow sets off afterwards. For `read`, `buf` is struck full at 3.77 and
+ the arrow comes back at 4.9 ([sheet](motion/sheets/syscalls-03.7-read.png)).
+ `write` already copies its bytes in order, after the arrow: that is the
+ model ([sheet](motion/sheets/syscalls-09.7-write.png)).
+2. **Four calls in 13.8 s under one caption.** This is the richest scene
+ and the shortest. Each call wants its own line of caption, its own
+ 2 s lead, and the 3.5 to 4.8 s the chart gives it: about 30 s.
+3. **Everything on the kernel's side pops**: name, rows, list.
+4. **3.0 s a call whatever it does.** `close` has one number in and one
+ out; `read` moves fifteen bytes.
+5. The registers reload their arguments in one frame at the step's start,
+ unmarked. Frame them one at a time: they are what the caption is about.
+6. Starts 0.04 s after its caption; ends 1.0 s after `write` returns.
+
+### zoom
+
+1. **The CPU level has nothing to show.** 5.2 to 8.8 at x2 on the
+ registers: `rip`'s digits change once (5.83, a pop) and `rdi` is struck
+ once (7.33) ([sheet](motion/sheets/zoom-05.3-at-x2-registers.png)). The
+ caption says "a handful of instructions" and no instruction is on
+ screen. Until a line can unfold into its instructions, put the
+ instruction in the head's `where`, and leave after the second step.
+2. **Out and in again.** 8.83 to 11.43: back to x1, a caption crossfade in
+ the middle (10.07), in to the stack: 2.6 s of the whole frame moving to
+ go one panel to the right
+ ([sheet](motion/sheets/zoom-08.7-out-and-in.png)). Fade through at x2.
+3. **The subject is at the frame's edge.** 12.07: the return address is
+ struck in the bottom row, half under the caption band; 13.57 the row
+ above it ([sheet](motion/sheets/zoom-11.5-at-x2-stack.png)). The panel's
+ tag is out of frame, so nothing says this is the stack.
+4. **16.57: the grid jumps.** The `fib` divider moves four rows, every row
+ shifts 20 units, `rsp`'s plaque teleports, and sixteen unknown bytes
+ become digits with no mark, all between two frames
+ ([sheet](motion/sheets/zoom-16.5-rows-jump.png)).
+5. **Four seconds of nothing** at x2, 19.1 to 23.1, after one byte is
+ struck at 18.07 ([sheet](motion/sheets/zoom-18.0-end.png)).
+6. **The camera leaves unannounced** at 4.03, 0.03 s after a caption
+ arrives, with no frame on its target; the source and stack slide away
+ and the stack's edge stays in view
+ ([sheet](motion/sheets/zoom-03.7-camera-in.png)).
+7. Back at x1 (24.5) the memory caption is still up, one run step pops,
+ and the scene cuts 1.0 s later. "And back up" needs its own beat: the
+ mark on line 6 again, the three levels in view, 2 s.
+8. Text under the zoom is steady
+ ([sheet](motion/sheets/zoom-05.1-text-settles.png)): nothing to do.
+
+## Stills
+
+Seen while looking at motion; against `README.md`.
+
+- **Camera at x2**: the neighbouring panel shows at the frame's edge (the
+ stack's divider and `rsp` plaque beside the registers, the source's
+ bottom rule above them); on the stack the last row is cut by the caption
+ band and the tag is out of frame. See "The camera".
+- **Kernel argument names** come from a type, not the call: `close` and
+ `read` show their descriptor as `number`, `open` shows flags and mode
+ both as `pointer`. They are `fd`; `path`, `flags`, `mode`; `fd`, `buf`,
+ `count`.
+- **`rax`'s role** reads `result` while it holds the call's number going
+ in. `number`, then `result` once it is struck.
+- A pointer in the kernel's rows is twelve digits unbroken
+ (`7fffffffd8c0`); in fours, as everywhere.
+- On `write` the user's bytes are not framed as read; they still carry the
+ ember of `read`, two calls and six seconds ago.
+- **Types** are in Zig's spelling for a C program: `[8]i32`, `i32`. The
+ source says `int a[8]`.
+- **Two panels titled `heap`** in `list` (the strip and the words).
+- **Two dividers named `fib`** in the stack at x1: `fib(5)`, `fib(4)`.
+- The call stack clips its sixth card; elide below ("2 more").
+- Unknown bytes become known with a reflow and no transition (zoom, 16.57).
+- A divider row inserted into the grid moves every row under it by 20
+ units. Give dividers a fixed place between rows.
+
+## The ten changes
+
+1. **Sequence the step.** Fire; effects one level at a time, 0.30 s apart,
+ each armed then struck; the mark last. The kernel's side included: no
+ effect before its cause.
+2. **Time a step by its content** (0.8, 1.5, 2.0, 2.5 s) and rest a beat at
+ each phrase end.
+3. **Rebuild run and sprint.** 0.30 s steps with the mark and structures
+ eased and values as embers; 24 steps at most; sprint beyond; ramp in over
+ four steps and out over three; veil what cannot be read; counter and
+ progress line.
+4. **Let the picture and the caption be read.** 1.0 s and 0.5 s a panel at
+ the opening; 2 s after a scene's first caption, 1 s after any other;
+ captions leave, pause, arrive; 2 s on the last picture.
+5. **Walk the point of each scene once**: a return, each pointer turning, a
+ swap by 10 s, each system call under its own caption.
+6. **Anticipate every write**: the arm, the fill over six frames, the pulse
+ as a 4-unit outset, the cool eased with the digits changing at its middle.
+7. **New curves, and travel timed by distance**: `standard` 0.3, 0, 0.2, 1;
+ `glide` 0.45, 0, 0.55, 1; the mark 12 to 24 f or a jump; flights 30 to
+ 48 f, the second six behind.
+8. **Direct the camera**: frame the target, clear the stage, move, hold;
+ the tag and whole rows in frame with the action in the middle; sideways
+ by fading through; never 2 s at x2 without a change.
+9. **Nothing pops into a layout**: make room, then arrive; scroll, never
+ cut; slide what persists; fade what becomes known.
+10. **Show the instruction** at the CPU level, and review at 60 frames a
+ second.
+
+## The instruments
+
+[`motion/motion.py`](motion/motion.py): ffmpeg, numpy, Pillow. Regions and
+crops are in design units.
+
+```sh
+cd design/motion
+python3 motion.py chart VIDEO --out charts # the chart, the events, the checks
+python3 motion.py auto VIDEO --out tmp/auto # and a contact sheet of every event
+python3 motion.py sheet VIDEO 20.4 21.4 --step 2 --crop 400,160,1120,368
+python3 motion.py sheet VIDEO f66 f77 --diff # what changed, white on the frame dimmed
+python3 motion.py onion VIDEO f614 f636 --crop 400,160,1120,368 # every frame of a move in one picture
+python3 motion.py track VIDEO f139 f158 --color e8c46a # a colour's box and centre, frame by frame
+```
+
+`chart` compares each frame with the one before, in each region of the
+scene's layout (a table at the top of the script, keyed by the video's
+name; add a scene there). A pixel *moved* if a channel changed by more than
+24 of 255 and is *fading* if by more than 6. The picture is one bar a
+frame and one strip a region: solid for moving, outlined for fading, holds
+shaded with their length. The text lists every event with the first and
+last frame of each region in it, which is where simultaneity shows, and
+ends with the checks:
+
+| Check | Fires when | Wants |
+| --- | --- | --- |
+| POP | over 0.2% of the frame changes within two frames, still either side | easing, or a smaller change |
+| CROWD | three or more panels begin within two frames of each other | the cascade |
+| METRONOME | seven or more events of over 0.5% of the frame, evenly spaced | content-timed steps, phrase rests |
+| RUSH | a panel moves within a second of a caption arriving | the caption's lead |
+| AIR | nothing changes for three seconds | a shorter hold, or something to say |
+
+A scene is ready for eyes when all five are empty or each remaining line
+is deliberate. They are not taste: a chart can pass and still be dull.
+
+Limits: regions are fixed on the screen, so under a camera move their
+names stop meaning panels; `track` follows a colour, so crop to one object
+(its box columns are the honest ones when two share the colour); the
+thresholds suit x264 at the export's quality and will need loosening for a
+harder encode.
+
+What is kept: `motion/charts/` (chart, events and per-frame counts for the
+five scenes as reviewed) and `motion/sheets/` (the sheets this page
+cites, named scene, second, what). `motion/tmp/` is scratch.