summaryrefslogtreecommitdiff
path: root/examples/noc/notes/rewrite-b.md
blob: 9d7163056a5e5448796fb29e7f2f76bb8e15f72b (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
# Phase 2, batch B rewrite (rewrite-b)

the_wave, pendulum, system_of_systems, flow_field, flocking, wolfram_ca,
rewritten on `sk.math`, `sk.draw`, `sk.Clock`, `sk.List`, and
`std.Random.Xoshiro256` in State. `helpers_b.zig` and the `vector` import
are gone (rewrite-a deleted `helpers_a.zig`). Each sketch has a script with
a screenshot, `test/<name>.timeline.script`, and a reload edit in
build.zig with `test/<name>.reload.script`. `zig build e2e` exits 0 (all 12
sketches and their checks).

## Lines (non-blank, non-comment, counted as in loc-before.txt)

| sketch | before | after | what went |
| --- | ---: | ---: | --- |
| the_wave | 36 | 24 | Session/Canvas, `paint` + `try`, `frames` (script-only field) |
| pendulum | 63 | 46 | `mouse` (pointer copied into State), per-event switch for moves, Canvas |
| system_of_systems | 73 | 65 | Canvas, `b.random`; the per-particle Pen stays (alpha varies) |
| flow_field | 110 | 85 | the 2.3 KiB angle grid (State keeps a seed), `fields_made`, the key-repeat check (`in.pressed`), Canvas |
| flocking | 118 | 109 | `pressed`, Canvas; the steering code is a rename (`b.` → `vec.`) |
| wolfram_ca | 48 | 47 | `frames60` → `sk.Clock` (it already drew with `f.fill`) |
| **ports** | **448** | **376** | |
| helpers_b.zig | 177 | 0 | |

flow_field also imports rewrite-a's `src/processing_noise.zig` (78 lines,
counted in rewrite-a's notes).

## Screenshots

I looked at each one next to the pre-rewrite screenshot and the Processing
source. All match in content. Differences:
- the_wave, pendulum: identical apart from the Clock's one-step shift (below).
- system_of_systems, flocking: the same picture with different random draws
  (lerp instead of `lo + f*(hi-lo)`, and the step shift).
- flocking: outlines are 1 px aliased (native `shape`, no AA, phase 3).
  Before, they were antialiased by the vector renderer, so boids now look
  slightly smaller and crisper.
- flow_field: see the noise finding below.
- wolfram_ca: the rule-90 Sierpinski triangle, unchanged.

## Flocking frame time, 1000 boids, ReleaseFast

I timed it the way porter-b did: headless, wall clock, a script that drags
in 880 boids and then plays 600 frames, minus the same script without the
600 frames. Draw-only is the same run after `console set clock.hz 0`
(checked: `clock.count` stays put). Three runs, the first one cold and
dropped. The GPU was shared with other agents.

| | before (CPU vector Canvas) | after (L1, 2 `shape` commands) |
| --- | ---: | ---: |
| total / frame | 8.7–11.6 ms | **3.5–3.6 ms** |
| draw + present | 4–7 ms | **~0.8 ms** |
| update (O(n²) steering) | ~4.6 ms | ~2.8 ms |

Draw is now noise next to the simulation. Batching costs one visible
difference: all bodies are drawn before all outlines, so an outline can
cross a neighbour's body where boids overlap (documented in `draw`).
The update number dropped too. The steering code is unchanged, so I
attribute that to the noisy shared machine, not to the rewrite.

## What the new API made easier

- **No Session, no `paint` with `try`, no renderer.** Each sketch's draw
  is `f.clear` plus `sk.draw.*`. A `Pen` as a file-scope `const` replaces
  "set fill, set stroke, set weight", and `pen.transformed(.place(pos,
  angle))` replaces translate·rotate with a reset afterwards. The reset
  bug can no longer be written.
- **One update per frame.** pendulum's `mouse` and flocking's `pressed`
  existed only because a replay batched frames. Now `in.mouse_x` and
  `in.buttons` are right, and the per-event `switch` over every event kind
  shrank to "handle the presses, then step".
- **Indexed `expect` with `~tol`.** `frames`, `fields_made` and `pressed`
  are gone. Scripts check what matters: `boids.buffer[124].position[0]
  150.8 ~0.01`, `emitters.buffer[0].particles.len 128`, `rows[3][31] 1`,
  `flowfield.seed 2947`.
- **`in.pressed(sk.Key.space)`** replaces the hand-written key-down,
  not-repeat test.
- **L1 batching.** Flocking's draw is 10 lines, has no allocator
  bookkeeping (scratch), and is 5–8x faster.
- **The timeline and reload checks** were mechanical to write from the
  template. Every sketch passed play, seek, step and live-move replay on
  the first try. Only the expected values needed probing.

## What still reads badly (friction, ranked)

1. **`sk.Clock` has no slack** (also reported by rewrite-a, on the board).
   A script frame is `ns_per_s / 60` = 16 666 666 ns, under 1/60 s, so
   `frames 60` gives 58 steps (59 with helpers_b's `step - 1e-5`). Every
   count in my scripts carries this offset, with a comment explaining it.
   Live, it leaves `owed` just under one step, so tick jitter gives
   0-then-2 step frames.
2. **`sk.math.noise` has a narrower spread than Processing's.** On flow_field's
   32×18 grid (offsets 0..3.1 × 0..1.7), sk.math.noise has sd 0.075 and
   range [0.27, 0.71]. Processing's has sd 0.115 and range [0.20, 0.77]. It
   is also exactly 0.5 at integer lattice points. Mapped to 0..2π, nearly
   every arrow points left (π), and the vehicles stream in one direction.
   So I used `processing_noise.zig`, with the click seed as a z slice
   (`z = seed · 0.01`), because its table is fixed. "noise → angle" is the
   book's standard idiom (flow fields, Perlin walkers, terrain). The
   library should document the spread or offer a contrast-normalised
   form.
3. **No pointer-press helper.** Keys have `in.pressed(key)`, but mouse
   presses need `for (in.events) |e| if (e.kind == .mouse_down) { ... e.x,
   e.y ... }` in three sketches (pendulum, system_of_systems, flow_field).
   `in.buttons & 1 != 0` is cryptic for "left button held". Wanted: an
   iterator over this frame's presses with their positions, and
   `in.mouseHeld(.left)`.
4. **`Color.alpha` takes `u8`.** Processing's alpha is a float that runs
   negative (`lifespan`), so system_of_systems writes
   `@intFromFloat(std.math.clamp(p.lifespan, 0, 255))`. A saturating
   float form would help.
5. **One colour per `shape`.** Batching works only for single-colour sets.
   system_of_systems fades every particle, so it emits 2 commands per
   particle (up to ~8000 at 32 full emitters). A per-vertex colour, or
   `(index range, colour)` runs inside one Tessellation, would batch
   particles too. It is not urgent: 2 commands per shape was fine at 390
   particles.
6. **Scripts cannot print a value.** Every expected number was found by
   writing a wrong `expect` and reading "found …". A `print FIELD` (or
   `get`) script line would help.
7. **Script and timeline gotchas** (documented, but each cost a probe run):
   every `console` line is followed by a frame, so counts shift. In a
   reload script, `console play 0` restarts the replay from its start;
   `console pause` is the way to play on. Playback also stops at the
   recording's end, which caps "play on". bouncing_ball's template uses
   `play 0`. I used `pause` so that the "play on" check really continues.
8. **The Processing order (show inside update) still needs off-by-one code.**
   the_wave draws `start_angle - 0.02`, and system_of_systems skips the
   newest particle. That is inherent to update-then-draw, not an API gap.
9. `std.math.lerp(-1, 1, rng.float(f32))` twice per random vector is long.
   It is the agreed idiom (no Rng wrapper), so I note it and do not ask
   for a change.

## Library additions, ranked

1. Clock slack/snap (a bug: judder at hz = display rate).
2. Noise spread: document it, or add a normalised variant, so that
   "noise → angle" ports look like the book without Processing's table.
3. Pointer presses for this frame with positions, plus a named
   held-button test.
4. A float/saturating alpha (`Color.alphaFloat(f32)` or similar).
5. Multi-colour batches in one `shape`: per-vertex colour or colour runs.
6. A `print FIELD` script command.
7. Native antialiasing for `shape` (already phase 3): 1 px outlines on
   small shapes (flocking) show it most.