diff options
Diffstat (limited to 'examples/noc/notes/design.md')
| -rw-r--r-- | examples/noc/notes/design.md | 230 |
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. |
