summaryrefslogtreecommitdiff
path: root/examples/noc/notes/rewrite-b.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/rewrite-b.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz
sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/rewrite-b.md')
-rw-r--r--examples/noc/notes/rewrite-b.md144
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.