summaryrefslogtreecommitdiff
path: root/examples/noc/notes/rewrite-a.md
diff options
context:
space:
mode:
Diffstat (limited to 'examples/noc/notes/rewrite-a.md')
-rw-r--r--examples/noc/notes/rewrite-a.md109
1 files changed, 109 insertions, 0 deletions
diff --git a/examples/noc/notes/rewrite-a.md b/examples/noc/notes/rewrite-a.md
new file mode 100644
index 0000000..7e61738
--- /dev/null
+++ b/examples/noc/notes/rewrite-a.md
@@ -0,0 +1,109 @@
+# Phase 2, rewrite-a: six ports on the new layer
+
+random_walk, noise_walker, bouncing_ball, accel_to_mouse, fluid_resistance,
+angular_forces. They use `sk.math`, `sk.draw` (Pen, plus L1 `Tessellation`
+for the walkers), `sk.Clock`, and `std.Random.Xoshiro256` / `std.math.lerp`
+directly. helpers_a.zig is deleted. rewrite-b deleted helpers_b.zig and the
+`vector` import. Two files survive:
+
+- `src/processing_noise.zig`: Processing's exact `noise()`, moved verbatim.
+ noise_walker uses it, and so does rewrite-b's flow_field (`sk.math.noise`
+ has about 0.65× the spread, so the picture changes).
+- `src/trail.zig`: a stopgap for the persistent canvas until phase 3 adds
+ offscreen targets. It keeps the pixels in Session and fills L1
+ tessellations into them on the CPU (aliased, opaque only). Each walker
+ keeps a "shadow" walker in Session and replays the walk in `draw`. When
+ `clock.count` goes backwards, the trail is wiped and repainted from step 0.
+ This needs the picture to be a function of the step count only: a
+ console `set walker.x …` would desynchronise it. It passes timeline check
+ 7, and also a seek to the start then step to the end gives the same
+ screenshot as playing.
+
+Every sketch has `test/<name>.script` (behaviour and screenshot, all looked
+at), `test/<name>.timeline.script` (from the accel_to_mouse template, with
+the sketch's own input: clicks for fluid_resistance, the pointer for
+accel_to_mouse, frames for the rest; the walkers add a seek-start/step
+screenshot check) and `test/<name>.reload.script` with one draw edit in
+build.zig. In each reload script, State is equal before and after `load
+{v2}`, the screenshots differ in the edited region, and play goes on. The
+walkers' edit shows only on new steps, so they play on and then check the
+newest dot or circle with `expect-pixel`. `zig build e2e` passes (exit 0).
+The first run had transient failures across both batches, including
+rewrite-b's. That was probably a concurrent build or edit. The two reruns
+were clean.
+
+## Lines (non-blank, non-comment), before → after
+
+| sketch | before | after | notes |
+| --- | --- | --- | --- |
+| random_walk | 45 | 39 | + shared trail.zig. The 28.8 KB trail bitset and `steps` are gone from State. |
+| noise_walker | 44 | 48 | + trail.zig. The L1 drawing into the CPU trail is longer than `pen.circle`. |
+| bouncing_ball | 36 | 22 | `bounces` removed; tests use `velocity[0]`, `position[1] ~tol`. |
+| accel_to_mouse | 35 | 24 | `caught` and `acceleration` removed. Reads `in.mouse_x` per frame. |
+| fluid_resistance | 86 | 68 | `resets` and `frame_count` removed; tests use `movers[4].mass` etc. |
+| angular_forces | 83 | 69 | `frame_count` removed; `transformed(.place(..))` is push/translate/rotate. |
+| **sketches** | **329** | **270** | |
+| helpers_a.zig | 128 | 0 | |
+| trail.zig | — | 54 | phase-3 stopgap |
+| processing_noise.zig | (in helpers_a) | 78 | kept on purpose |
+
+## What the new API made easier
+
+- No Session or GPU layer for the four redrawn sketches. `draw` is
+ `f.clear` plus `sk.draw.circle(f, pos, r, pen)`, and the pens are `const`
+ data. A Pen with radius instead of diameter matches `circle(x, y, r*2)`
+ directly.
+- `mover_pen.transformed(.place(m.position, m.angle))` is Processing's
+ push/translate/rotate/pop. The forgotten-reset bug can no longer happen.
+- Indexed `expect` paths and `~tol` removed every test-only State field
+ (bounces, caught, resets, three frame_counts). A failed `~` expect prints
+ the value it found, which is how every expected value here was obtained.
+- The per-frame host fix made `in.mouse_x` inside the step loop correct.
+- The L1 data is a real escape hatch: trail.zig rasterises
+ `Tessellation.points/indices` itself, with no library change.
+- `sk.Clock.count` replaces the hand-kept frameCount.
+
+## What still reads badly
+
+- **Drawing anywhere but the frame.** `sk.draw.circle` only emits to a
+ Frame. To put a Pen circle on the trail, noise_walker builds two
+ Tessellations by hand (fill, then stroke with width 2) and fills them
+ with two colours. That is 8 lines where Processing has one.
+- **Persistent canvases** (known, phase 3). trail.zig plus a shadow walker
+ per sketch costs about 60 lines for two sketches.
+- **Random in a range.** `std.math.lerp(0.1, 2, r.float(f32))` appears 5
+ times in angular_forces' init. It works, but it reads worse than
+ `random(0.1, 2)`.
+- `vec.scale(force, 1 / m.mass)` for `force / mass`, and
+ `@as(f32, @floatFromInt(i)) * 70`. These are Zig's own costs.
+- **Colour arguments.** `f.clear(sk.Color.white)`: Frame methods take
+ `anytype` colours, so `.white` / `.gray(220)` decl literals do not work
+ there, while they do in Pens and `f.shape`.
+- **Scripts.** An exact `expect` on a float (no `~`) fails without printing the value it found (integers do print it).
+ `console get position` prints `<16 bytes>` for a vector. Each `console`
+ line advances a frame, which shifts every value read after it.
+
+## Library: what to add (ranked)
+
+1. **`sk.Clock` slack (bug).** Host and script ticks are 16_666_666 ns, a
+ hair under 1/60 s, so at `hz = 60` the clock lags one extra step, and
+ `owed` then sits just under a step. With live jitter that gives
+ 0-then-2-step frames (judder) on a 60 Hz display. helpers_a's `steps60`
+ had a `step - 1e-6` slack for exactly this. Snap within a small epsilon
+ (or round tick dt to the step). Not patched, because it changes stepping
+ semantics and the clock tests. Posted on the board.
+2. **Offscreen targets + `Input.jumped`** (phase 3). These replace
+ trail.zig and the shadow-walker replay.
+3. **Pen output to a sink, not only a Frame.** For example
+ `pen.tessellate(gpa, .circle(c, r)) -> [2]?{Tessellation, Color}`, or
+ `circle(sink, …)` where the sink is a Frame or a list of (Tessellation,
+ Color). A small CPU fill of a Tessellation into an RGBA buffer
+ (trail.zig's 20 lines) would also help phase-3 tests and thumbnails.
+4. **Script ergonomics.** Print the found value on every failed
+ `expect`, floats included. Have `get` print vectors as `{x, y}`. Add an `expect`-style
+ read-only `print FIELD` that does not cost a frame.
+5. **Decl-literal colours in Frame methods.** Typed `Color` parameters, or
+ accept `.white`, `.gray(v)`.
+6. **`random(lo, hi)`** (or `sk.math.lerp` taking a `std.Random`). It is
+ optional: std is fine, but the PVector-name README table should show
+ the idiom.