diff options
Diffstat (limited to 'examples/noc/notes/rewrite-b.md')
| -rw-r--r-- | examples/noc/notes/rewrite-b.md | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/examples/noc/notes/rewrite-b.md b/examples/noc/notes/rewrite-b.md new file mode 100644 index 0000000..9d71630 --- /dev/null +++ b/examples/noc/notes/rewrite-b.md @@ -0,0 +1,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. |
