diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-16 21:28:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-16 21:28:20 -0300 |
| commit | 6933f99ddb2d7103515d26838496309a807bba26 (patch) | |
| tree | 991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/rewrite-a.md | |
| parent | 82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff) | |
| download | sketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip | |
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/rewrite-a.md')
| -rw-r--r-- | examples/noc/notes/rewrite-a.md | 109 |
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. |
