diff options
Diffstat (limited to 'design/motion.md')
| -rw-r--r-- | design/motion.md | 773 |
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. |
