summaryrefslogtreecommitdiff
path: root/examples/noc/notes/design.md
diff options
context:
space:
mode:
Diffstat (limited to 'examples/noc/notes/design.md')
-rw-r--r--examples/noc/notes/design.md230
1 files changed, 230 insertions, 0 deletions
diff --git a/examples/noc/notes/design.md b/examples/noc/notes/design.md
new file mode 100644
index 0000000..5762f41
--- /dev/null
+++ b/examples/noc/notes/design.md
@@ -0,0 +1,230 @@
+# sketchbook, iteration 1: design
+
+Merged from the 12 Nature of Code ports (friction-a/b.md), three research
+notes, two adversarial critiques (critique-core.md, critique-zig.md), the
+shader pass (../../shaders/README.md) and board.md. Nothing here is built
+yet; `lib/sketchbook` is untouched.
+
+## Principles (owner)
+
+- The deterministic core stays: State is plain data, `update` sees only
+ State and Input and is replayed, `draw` emits commands as data, and both
+ hosts run every command.
+- The new API is a **layer on top**, Zig-style (`std.posix` under
+ `std.Io`). Today's `abi.Command`, `f.emit`, GPU passes, `Input.events`
+ and Frame methods stay as they are. The new layer is sketch-library code
+ with no hidden state that hands its intermediate data out: a Pen yields
+ triangles you can emit yourself or feed to your own GPU pass.
+- Build knobs live in `build.zig`, but the critics drew a line: **a build
+ option must not change what `update` computes or the state-file
+ format** (a `-D` noise flavour or snapshot count makes a recording or a
+ state file mean something else). Knobs that pass this test: test
+ optimize mode, shader language, web/PWA, tools.
+
+## What the ports showed
+
+- Both porters independently wrote the same ~200-line helper file:
+ circles/lines/stroke under a transform through the `vector` module,
+ PVector ops, a PRNG in State, Perlin noise, a fixed-capacity list, a
+ fixed-step clock. 9 ports need filled/stroked circles, 3 need line
+ segments, 2 need convex triangles, 3 need translate·rotate, 4 need alpha.
+ Nothing used arcs, blend modes, HSV, image transforms, or randomness in
+ `draw`.
+- **Three host bugs** surfaced, each found independently by more than
+ one agent and confirmed by experiment:
+ 1. Seek feeds the whole recording to **one** `update`, with mouse/key
+ state as of the batch's end. `accel_to_mouse` ends at (581, 311) by
+ playback but (350, 195) by `seek end`. Slow-frame playback batches
+ too. `in.dt`/`in.now` are wrong during replay (Host.zig:229-246).
+ 2. Input state is not part of snapshots/recordings: a replay after a
+ live mouse move ends at (163, 102) instead of (581, 311).
+ 3. Arrays are opaque migration leaves: change an element type or a
+ capacity and the array resets to `undefined` while its `len` is
+ kept, giving garbage elements, or a panic on shrink. The game's
+ tracker songs are exposed the same way. Separately, a state file
+ the host doesn't recognise is **truncated** on open (memory.zig:129).
+
+## Disagreements, decided
+
+| Question | Decision | Why |
+| --- | --- | --- |
+| `Command.shape` payload: `triangles` (critic-zig) or `points + ends + indices` (critic-core) | **`{ color, points, ends, indices }`** | Measured: Canvas2D fills a triangle soup 3.6× slower than the outline (1000 circles: 11 vs 3 ms), and seams between separately filled triangles show. The web fills the subpaths as one nonzero path; native passes points+indices straight to `SDL_RenderGeometry`. The library guarantees positive winding and disjoint triangles. |
+| `Vec2` struct with methods (research-zig) or `@Vector(2, f32)` | **`@Vector`** + host splits vector lanes into leaves | `+=` stays; one type with the shaders (`vec2`). The real problems (unreadable in console/scripts, Debug's 16-byte layout resetting on `-Doptimize`, padding garbage in `diff`) are fixed in the host by lane leaves and leaf-wise compare. |
+| `Rng` wrapper / own PCG32 vs std generator | **`std.Random.Xoshiro256` (concrete, never `DefaultPrng`) in State, plus a build stamp in recordings** | No wrapper earns its lines (`std.math.lerp(lo, hi, r.float(f32))`). The concrete type can't silently change via the `DefaultPrng` alias, and the stamp warns when a recording is played against a different build. Open question below if you want our own algorithm anyway. |
+| Clock cap (≤ 8 steps/call) | **Keep the cap, after the per-tick host fix** | With one `update` per tick, the cap depends only on the recorded tick, so it replays identically; it prevents the spiral of death after a stall. Before the host fix every Clock design is wrong. |
+| AA fringe on shapes | **No fringe** | It halves 1 px line intensity on the web (128 vs 255). Native shapes are aliased like `rect` today; see open questions. |
+
+## Iteration 1, in order
+
+Each step ships with its tests (details in critique-core §3).
+
+**A. Host behaviour (no API change)**
+1. One `update` per tick: playback, seek and step deliver whole frames;
+ `in.dt`/`in.now` come from the tick in both live and replay (so they
+ match bit for bit); Input is reset and re-seeded on record start and
+ snapshot restore. Tests: play-vs-seek-vs-step equal the stop snapshot;
+ replay after a live move equals the first replay.
+2. Inspection: `@Vector` lanes and array elements become addressable
+ leaves (`get/set/expect pos[0]`, `boids.buffer[3].pos[1]`), `diff`
+ compares leaf by leaf, and script `expect`/`await` take `~tol`. This
+ removes the 8 State fields the ports added only for their tests.
+3. Element-wise array migration (copy shared elements field by field,
+ enums by name, clamp on shrink), with a reader for today's state
+ files. Never truncate an unrecognised file; refuse it instead.
+ Fixture: a copy of `drat-meout.state` keeps every value.
+
+**B. The one new host primitive**
+
+4. `Command.shape { color, points: []const [2]f32, ends: []const u32,
+ indices: []const u32 }`: one SDL_RenderGeometry call natively, one
+ nonzero path fill on the web. Tests on both hosts: overlapping
+ translucent circles, a concave polygon, an acute translucent zig-zag
+ stroke (no holes, no double blend), a 1 px line, and 5000 circles
+ under 16 ms on the web.
+
+**C. The new layer (sketch library; pure, no state of its own)**
+
+5. `sk.math`, one geometry module shared with `vector`:
+ `Vec = @Vector(2, f32)`, `scale`, `distance`, `withLength` (setMag),
+ `clampLength` (limit), `angle` (heading), `unit` (fromAngle),
+ `Affine.place(at, radians)`, `noise(seed, x, y, z)` (table-free, golden
+ values equal on native and wasm). The README gets a PVector-name table.
+6. `sk.draw`, two levels:
+ - L1: `fillCircle`, `strokeCircle`, `fillPolygon`, `strokePolygon`,
+ `strokeLine`. Each appends to a caller-owned `sk.draw.Tessellation`
+ (points, ends, indices), using a caller-given allocator, with an
+ `Affine`.
+ - L2: `Pen { fill: ?Color, stroke: ?Color, width, xf }` as plain data,
+ where `pen.transformed(m)` is the push. `sk.draw.circle/line/polygon(f,
+ …, pen)` tessellate into scratch memory and emit `shape`; on
+ out-of-memory they log and drop, like `Frame.emit`. Radius, not
+ diameter. One colour type (`abi.Color`, with `Color.gray(v)`).
+7. Root: `sk.Clock { hz, owed, count, steps(in) }` and `sk.List(T, cap)`
+ with std names (`appendBounded`, `orderedRemove`, `swapRemove`,
+ `slice`, `constSlice`), clamped, defaulting to `@splat(.{})` (not
+ `zeroes`: enums without a 0 tag).
+
+**D. Parity fixes and tooling**
+
+8. Web image tint keeps RGB (it keeps only alpha today); native MSAA
+ passes with `clear = null` load (clearing on first use, since Vulkan
+ starts undefined and WebGPU zeroed).
+9. Recordings carry the sketch build hash; `play` warns on a mismatch.
+10. Build/harness:
+ - `addZigShaders` moves into sketchbook's build.zig, with the SPIR-V
+ fix-up tool (from sketches/shaders).
+ - An e2e optimize option.
+ - Concurrent e2e runs get unique store paths.
+ - Fix the teardown segfault on the store-busy path (Host.zig:118).
+ - Investigate `LeakedSdlMemory` under parallel e2e (−j1 passes 12/12).
+
+**E. Then:** rewrite the 12 ports on the new layer, delete
+helpers_a/b.zig, and compare line counts (critic-zig estimates 778→~640
+in the ports and 296→~25 in the helpers). At least one port (flocking)
+drops to L1/L0 to batch 1000 boids into 2 commands.
+
+## Deferred (no port needs it yet)
+
+Offscreen targets, `jumped`, Layer/Ring for trails (2 ports, both with
+workarounds that stay correct after a seek), blend modes (SDL's multiply
+differs from Canvas for α<1), colour spaces, image affines, textures in
+GPU passes, `Draw.instances` (safe whenever wanted), arcs/ellipses/joins,
+input sugar, fallible `draw`, host constants as build options (never as
+compile-time file-format constants).
+
+## Open questions for the owner
+
+1. **Native antialiasing.** Canvas2D antialiases shapes; SDL_RenderGeometry
+ does not, so native circles look jaggier than the same sketch on the web.
+ Accept it for iteration 1, or add an MSAA SDL_GPU pipeline for `shape`
+ on the host (no API change)?
+2. **RNG.** Concrete std `Xoshiro256` plus the build stamp, or our own
+ pinned generator (PCG32) so recordings survive Zig upgrades?
+3. **Processing-exact noise.** One sketchbook noise in the library, with
+ porter-a's exact Processing `noise()` kept in the noc project for
+ faithful ports. Fine?
+4. **Order.** A (host fixes) first is safest, since it changes behaviour
+ under your existing recordings and the game. Or start with B+C to see
+ the ports shrink sooner?
+
+## Decisions taken (owner delegated them)
+
+1. Native shapes ship aliased in iteration 1; antialiasing becomes a phase-3
+ feature, driven by the recursive tree (thin lines).
+2. RNG: `std.Random.Xoshiro256` used directly in State, plus the build stamp
+ on recordings.
+3. One table-free noise in the library; porter-a's Processing-exact
+ `noise()` stays in the noc project.
+4. Order: iteration 1 (host fixes + drawing layer, built in parallel by
+ core-host and draw-layer), then rewrite the 12 ports on it, then phase 3.
+
+## Phase 3: new examples that need the deferred features
+
+Each feature is built only together with an example that needs it, and the
+example is written from scratch on the new API.
+
+| Example (NoC 2nd ed.) | Feature it drives |
+| --- | --- |
+| 4.8 Image texture system: smoke | `imageMode(CENTER)`-style placement, image tint alpha on both hosts, Gaussian random (`std.Random.floatNorm`) |
+| 4.9 Additive blending | blend modes (`alpha`, `add`), with SDL vs Canvas parity tests |
+| 8.6 Recursive tree | recursion over `Pen.transformed`, stroke width from the mouse, native antialiasing for thin lines |
+| 8.5 Koch curve | data that grows 4× per click: `List` capacity vs Store-backed growth |
+| 8.9 L-system | strings that grow to thousands of characters: State vs Store, turtle push/pop |
+| 5.8 Path following | translucent thick polylines with joins (miter/round/bevel), `noFill` shapes |
+| 5.13 Quadtree | stroked rects, points, thousands of shapes per frame |
+| 5.12 Bin-lattice separation | 2000 boids: batching/instancing performance |
+| 11.1 Flappy bird | text, game loop, restart: game-style structure |
+| 0.1/0.6 walkers (rewritten again) | offscreen targets + `Input.jumped` for trails, replacing the Session-repaint workaround |
+
+## Acceptance: live reload, per example (owner)
+
+Every example (the 12 rewritten ports, the phase-3 examples, the Book of
+Shaders sketch) must hot-reload both its Zig code and its shaders with
+State kept. Checked automatically, not by hand:
+
+- `App.addReloadCheck(.{ .script, .edits })` in sketchbook's build.zig
+ builds the library twice: as written, and from a copy of the sources
+ with textual `edits` applied (`.{ .file, .old, .new }`, failing the
+ build if `old` is not found exactly once). It runs the script through
+ the generic host with `{v2}` defined as the second build.
+- Each example's reload script plays a while, takes a screenshot, checks
+ State fields, runs `load {v2}`, checks that the same State values
+ carried over, plays on, and takes a second screenshot. A compare step
+ asserts the screenshots differ where the edit should show.
+- Each example declares one code edit (e.g. a color or a force constant
+ in `draw`/`update`). Shader examples also declare one shader edit, in
+ Zig and in GLSL.
+- Checked once by hand: the file watcher path (`zig build run` with
+ `zig build lib --watch`) on one example, editing a Zig shader.
+
+## Acceptance: timeline, per example (owner)
+
+Every example must scrub correctly: pause, go back, replay. Each example
+gets a timeline script that:
+
+1. records its own interaction (clicks, drags, keys) for a few seconds,
+ then stops and snapshots slot N;
+2. `play`s to the end, and the state equals slot N exactly (leaf by leaf,
+ no tolerance: this is the determinism claim);
+3. `seek`s to the end, and to the middle then plays on: both equal slot N;
+4. `step`s back and forward and lands on the same frames;
+5. pauses for a while: State does not move (`draw` must not change it);
+6. replays after a live mouse move: equals the first replay (critic-core E2);
+7. screenshots after a seek and compares with the live screenshot at the same
+ point. This catches draw-side caches (trails) that the state check
+ cannot see; the walkers' trails must pass it once phase 3 adds targets
+ and `Input.jumped`.
+
+Script support (core-host): `expect-snapshot N` (live state equals slot N,
+leaf-wise, reporting the first differing leaves) and screenshot equality
+(shared compare tool with draw-layer's reload check).
+
+### Phase 3 addition: vector GPU backend draw count (from perf.md)
+
+fix1–3 (pipeline looked up once per pass, redundant state calls skipped,
+one vertex binding) are applied in lib/sketchbook. What's left is ~0.6 µs of
+driver CPU per draw, and the vector GPU backend issues 2 draws per filled
+shape. Cut the draw count: convex single shapes drawn directly (no stencil),
+and fills with disjoint bounds batched into one stencil + one cover draw.
+Driven by 5.13 Quadtree / 5.12 Bin lattice when drawn through `vector`, and
+measured with perf.md's bench.