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/research-zig-internals.md | |
| parent | 82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff) | |
| download | sketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip | |
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/research-zig-internals.md')
| -rw-r--r-- | examples/noc/notes/research-zig-internals.md | 770 |
1 files changed, 770 insertions, 0 deletions
diff --git a/examples/noc/notes/research-zig-internals.md b/examples/noc/notes/research-zig-internals.md new file mode 100644 index 0000000..8f1ebb7 --- /dev/null +++ b/examples/noc/notes/research-zig-internals.md @@ -0,0 +1,770 @@ +# Research: Zig std and sketchbook internals, for imperative creative coding + +Scope: what sketchbook should add or change so Nature of Code style sketches +are easy to write while staying Zig-ish (explicit, no hidden globals, explicit +allocators, std idioms). This covers Zig 0.17 std and sketchbook's own +internals. Processing/p5 and LÖVE/raylib API surveys, and shaders in depth, +are covered elsewhere. + +Paths below are relative to `lib/sketchbook/` unless they start with `src/` +of the game (`../../src/...`) or `sketches/noc/`. + +Experiments were run in a scratch dir against the real `src/abi.zig`, +`src/layout.zig` and `src/host/memory.zig`, using zig 0.17.0. They are marked +**[verified]**. + +--- + +## 0. The strongest evidence: the NoC ports already hit every gap + +`sketches/noc/src/helpers_a.zig` and `helpers_b.zig` were written separately by +two port batches. Both re-implement the same missing pieces: + +| Gap | helpers_a | helpers_b | Game (`../../src`) | +| --- | --- | --- | --- | +| PVector ops on `@Vector(2,f32)` | `setMag`, `limit`, `splat` (:32-40) | `mag`, `dist`, `scale`, `normalize`, `setMag`, `limit`, `heading`, `fromAngle` (:210-234) | — | +| `random(lo, hi)` over a State PRNG | `range` (:42) | `random` (:240) | — | +| `noise()` | Processing's exact table at comptime (:50-129) | table rebuilt from a seed (:279-336) | — | +| Pointer-free list for State | — | `List(T, cap)` (:247-273) | `dialogue.State.offered`+`count`, `Choice.text`+`len`, `room.Layout.items`+`len`, `tracker.Song.order`+`order_len` | +| Circles/lines/polygons with fill+stroke | `Pen` over `vector.Drawing.Builder`, GPU renderer (:146-193) | `Pen` + `Canvas` over CPU renderer (:350-399) | `ui.outline` = 4 fills (`ui.zig:20`); the cursor tail is 96 one-pixel-ish rects (`ui.zig:88-105`) | +| Transform (push/translate/rotate/pop) | `Style.transform: Affine` | `Pen.transform: Affine` (:356) | — | +| Fixed 60 Hz step | `steps60` (:17-27) | absent: batch B steps per frame, so speed depends on refresh rate | `dialogue.end(dt, ...)` uses tick dt | +| `map()` | `map` (:132) | — | — | +| draw returning errors | — | every sketch wraps: `paint(...) catch \|err\| f.host.print(...)` (`flocking.zig:130`, `system_of_systems.zig:68`, `flow_field.zig:102`, `the_wave.zig:26`) | — | +| No-`background()` trails | — | — | `random_walk.zig` keeps a `StaticBitSet(640*360)` in State and re-uploads 900 KB of pixels every frame (:19, :48-53) | + +Every proposal below is something at least one of these files had to build by +hand. + +--- + +## 1. Variable numbers of entities in State + +### What layout reflection does today + +`src/layout.zig:41-57` flattens *structs* into dotted leaves; everything else, +arrays included, is **one leaf** (`:50-53`, `leaf()` at `:59-78` gives arrays +kind `.array`). The leaf hash is the structural signature (`:116-147`): an +array's signature is `[N]` ++ the element's full signature, and a struct's +signature includes every field name, offset and type. + +Migration (`src/host/memory.zig:95-111`) copies a leaf only if +`before.hash == leaf.hash and before.size == leaf.size`; otherwise the leaf +keeps the new default. Enums are remapped by tag name (`:113-120`); nothing +else is. + +### What that means for particle lists [verified] + +Prototype: `List(P, cap) = struct { buffer: [cap]P, len: u32 }`, migrated with +the real `memory.migrate`: + +| Edit while running | Result | +| --- | --- | +| Add a field to `P` | `buffer` reset (every particle zeroed), `len` **kept** (10 zombie particles at the origin) | +| Capacity 64 → 128 | `buffer` reset, `len` kept | +| Capacity 64 → 4 | `buffer` reset, `len = 10` kept, so `buffer[0..len]` is **out of bounds** (`helpers_b.List.slice` at :254 would panic) | +| Same with a struct-of-arrays list (one `[cap]F` per field) | adding a field keeps every other column (`kept=3 reset=1`), with no host change | + +The game has the same hazard, and worse: `tracker.State.songs: [8]Song` +(`../../src/tracker.zig:56`) is one leaf. Adding any field to `Song` (a `swing` +byte, say) on hot reload **erases every song the player composed**. + +### std 0.17 situation + +- `std.BoundedArray` is gone: removed in `196e36bbb2` ("std: remove + BoundedArray … handled by ArrayListUnmanaged via the '...Bounded' method + variants"). The idiom now is `std.ArrayList(T).initBuffer(&buf)` plus + `appendBounded`, `addOneBounded`, `insertBounded`, … which return + `error.OutOfMemory` when full (`/usr/lib/zig/std/array_list.zig:681`, + `:1046`, `:1425`). +- `ArrayList` holds a slice (`items: Slice`, `:647`) and `MultiArrayList` holds + `bytes: [*]u8` (`multi_array_list.zig:26`): neither can live in State. + `layout.check` rejects them at compile time, which is right. +- `initBuffer` is fine for *locals* in `update`/`draw` (`room.Layout` could be + one), but State needs its own pointer-free type. + +### Proposal: `sk.List(T, capacity)` (and `sk.Ring`) + +Mirror std naming so it reads like `ArrayList`'s bounded API, and clamp the +length so a capacity shrink can never index out of bounds. + +```zig +// src/sketch/list.zig +pub fn List(comptime T: type, comptime capacity: u32) type { + return struct { + const Self = @This(); + pub const Elem = T; + pub const cap = capacity; + + /// Zeroed, not undefined: state files and snapshots stay comparable. + buffer: [capacity]T = @splat(std.mem.zeroes(T)), + len: u32 = 0, + + pub const empty: Self = .{}; + + /// Live elements. Clamped: after a capacity shrink `len` may exceed `cap`. + pub fn items(l: *Self) []T { return l.buffer[0..@min(l.len, capacity)]; } + pub fn constItems(l: *const Self) []const T { return l.buffer[0..@min(l.len, capacity)]; } + + /// Same contract as `ArrayList.appendBounded`. + pub fn append(l: *Self, item: T) error{OutOfMemory}!void; + pub fn addOne(l: *Self) error{OutOfMemory}!*T; + pub fn swapRemove(l: *Self, i: usize) T; // O(1), for particles + pub fn orderedRemove(l: *Self, i: usize) T; // keeps draw order + pub fn clear(l: *Self) void; + pub fn full(l: *const Self) bool; + }; +} + +/// Fixed-size history: `push` overwrites the oldest. For trails, recent +/// events, and "what happened since the last draw" (see section 5). +pub fn Ring(comptime T: type, comptime capacity: u32) type { + return struct { + buffer: [capacity]T = @splat(std.mem.zeroes(T)), + /// Items ever pushed: a sequence number that also survives wrap-around. + pushed: u64 = 0, + pub fn push(r: *@This(), item: T) void; + pub fn latest(r: *const @This(), n: usize) Iterator; // newest n, oldest first + pub fn since(r: *const @This(), seq: u64) Iterator; // pushed after `seq` + }; +} +``` + +Usage (NoC 4.2, particle system): + +```zig +pub const State = struct { + rng: std.Random.DefaultPrng = .init(4), + particles: sk.List(Particle, 512) = .empty, +}; + +// update, per fixed step +s.particles.append(.spawn(s.rng.random(), origin)) catch {}; // full: drop, like a capped emitter +var i: usize = 0; +while (i < s.particles.items().len) { + const p = &s.particles.items()[i]; + p.step(); + if (p.dead()) _ = s.particles.swapRemove(i) else i += 1; +} +``` + +Optional `sk.Soa(T, cap)` with `items(.pos)` (the `MultiArrayList` API shape) +gives per-field migration for free. The prototype needs one fix: use each +field's own default for its column (`attrs.defaultValue(F)`), not `zeroes`. +Without that, a new `mass: f32 = 1` column came back as 0 [verified]. SoA +reads worse for NoC code, so it is a niche tool, not the default. + +**Cost:** `List` + `Ring` + tests: about 150 lines, half a day. No host change. + +### Proposal: element-wise array migration in the host + +Make the reflected layout understand repetition, so arrays of structs migrate +field by field and element by element, and arrays whose element type is +unchanged keep their common prefix. + +1. `abi.Field` (`src/abi.zig:561`) gains `count: u32 = 1, stride: u32 = 0, + elem_hash: u64 = 0`. +2. `layout.flatten` (`src/layout.zig:41`): for `[N]S` where `S` is a + non-packed struct, recurse into `S` with the path `name[]` and emit leaves + with `count = N, stride = @sizeOf(S)`, so you get `particles.buffer[].pos.x`. + For arrays of scalars or enums, emit one leaf with `elem_hash` = hash of + the child. Nested arrays of structs (tracker `Song.patterns`) can either + multiply into up to three `(count, stride)` dimensions, or stop at one + level and rely on rule 3 for the inner arrays. +3. `memory.migrate` (`src/host/memory.zig:95`): + - a repeated leaf copies `min(old.count, new.count)` elements at their strides; + - an array leaf whose hash differs but whose `elem_hash` matches copies the + common prefix (capacity change); + - enum elements get `remapEnum` per element. +4. `StoredField` (`memory.zig:40`) gets the new fields; bump `file_magic` to + `SKETCH02` (`memory.zig:23`), and treat old files as foreign, which is the + existing path for a missing layout. +5. `fields.zig` (`format`/`set`, `:7-50`) and `web.zig` `sk_field`/`sk_tag` + (`:321-358`) accept an index in the path: `particles.buffer[3].pos.x`. Then + console `get`/`set`, script `expect`/`await`, the probe and + `window.sketch.field()` can all address individual entities. +6. The memory overlay (`host/overlay.zig:18`) shows one row per leaf, so a + repeated leaf stays one row (`particles.buffer[].pos.x ×512`). + +With that change, adding `mass` to `Particle` keeps every position and +velocity, a capacity change keeps the first `min` particles, and the tracker +songs survive a new `Song` field. + +**Cost:** about 230 lines including tests (layout 40, abi 5, memory 50, +fields 40, web 15, overlay 10, tests 70). About 1 day. `abi.hash` changes +automatically (`abi.zig:635`). + +--- + +## 2. Deterministic randomness and noise + +### PRNG in State: already works [verified] + +```zig +pub const State = struct { rng: std.Random.DefaultPrng = .init(42) }; +``` + +- `DefaultPrng = Xoshiro256` (`/usr/lib/zig/std/Random.zig:13`), whose state + is `s: [4]u64` (`Random/Xoshiro256.zig:9`): no pointers, so + `layout.check` accepts it. +- `.init(42)` works as a field default: `seed` runs SplitMix64 at comptime. +- Reflection gives one leaf, `rng.s` (kind `.array`, 32 bytes). It migrates + byte for byte as long as the generator type does not change. +- `std.Random` (the interface from `.random()`) holds a pointer and a + function pointer. Putting it in State is a compile error, which is correct: + take it locally. +- **Determinism across hosts [verified]:** a checksum over 20k values of + `float(f32)`, `floatNorm(f32)` (ziggurat tables), `@sin` and the noise below + was identical (`514686fd`) in native Debug (self-hosted backend), native + ReleaseFast (LLVM), wasm32 Debug and wasm32 ReleaseSmall. Recordings and + web replays agree. +- Smaller alternatives if size matters: `SplitMix64` (8 B), `Pcg` (16 B), + `Xoroshiro128` (16 B), `Sfc64` (32 B). `Isaac64` (about 4 KB) and `ChaCha` + are overkill. +- `std.Io` has randomness too (`Io.zig:1-14`). That is exactly what `update` + must not use: it is a nondeterministic source. Sketches should never be + handed an `Io` in `update`; the existing `call` dispatcher + (`src/sketch/root.zig:235-269`) already rejects unknown parameter types. + +### Proposal: don't wrap the PRNG; add free functions over `std.Random` + +Wrapping std's generator would duplicate its whole API. The Zig-ish move is to +keep `std.Random` as the interface and add the handful of creative-coding +draws as free functions: + +```zig +// src/sketch/random.zig: every function takes the std interface +pub fn range(r: std.Random, lo: f32, hi: f32) f32; // p5 random(lo, hi) +pub fn gaussian(r: std.Random, mean: f32, sd: f32) f32; // randomGaussian, via floatNorm +pub fn chance(r: std.Random, p: f32) bool; +pub fn unit(r: std.Random) sk.Vec2; // PVector.random2D +pub fn inRect(r: std.Random, rect: anytype) sk.Vec2; +pub fn pick(r: std.Random, comptime T: type, items: []const T) T; +/// Monte Carlo / "accept-reject" (NoC 0.5). +pub fn acceptReject(r: std.Random, comptime f: fn (f32) f32) f32; +/// A generator for entity `i`, independent of how many numbers others drew: +/// edits that add a draw elsewhere don't reshuffle this entity. +pub fn stream(seed: u64, i: u64) std.Random.DefaultPrng; // .init(std.hash.int(seed ^ i *% K)) +``` + +```zig +// update +const r = s.rng.random(); +for (0..n) |_| try s.walkers.append(.{ .pos = sk.random.inRect(r, bounds), .step = sk.random.gaussian(r, 0, 2) }); +``` + +**Where the seed comes from:** +- a fixed default (reproducible art); +- `init(s, host)` with `s.rng = .init(host.clock())`. Init is not replayed, + and the seed is saved with the state, so replays still match; +- a console `set rng.s ...` (works today). + +**Randomness in `draw`** (p5 sketches often call `random()` there): `draw` +cannot write State. Use a local `std.Random.DefaultPrng.init(seed ^ in.frame)`, +or the stateless `sk.noise.hash01(seed, i)`. + +**Cost:** about 60 lines, a couple of hours. + +### Proposal: `sk.noise`, pure functions of seed and coordinates + +Two flavours, both with no mutable globals: + +```zig +// src/sketch/noise.zig +/// Gradient noise, about -1..1, a pure function: lattice corners hashed with +/// `std.hash.int` and `seed`. No permutation table, so the seed can be a +/// runtime State field. +pub fn perlin2(seed: u32, x: f32, y: f32) f32; +pub fn perlin3(seed: u32, x: f32, y: f32, z: f32) f32; // flow fields animated by z = t +pub const Fbm = struct { octaves: u4 = 4, falloff: f32 = 0.5, lacunarity: f32 = 2 }; +/// p5's noise(x, y): 0..1, octaves summed. +pub fn fbm2(seed: u32, x: f32, y: f32, o: Fbm) f32; +pub fn fbm3(seed: u32, x: f32, y: f32, z: f32, o: Fbm) f32; +pub fn hash01(seed: u32, i: u32) f32; // stable "random" per index, for draw + +/// Processing's own noise() (PApplet), for ports checked against reference +/// images: 4096 floats from java.util.Random's LCG. Build it where the seed +/// is known: at comptime for a constant seed (helpers_a.zig:52), or in +/// Session/on the stack from a State seed (helpers_b.zig:285). Not in State: +/// it is derived data (16 KiB). +pub const Classic = struct { + table: [4096]f32, + pub fn init(seed: u64) Classic; + pub fn get(n: *const Classic, x: f32, y: f32, z: f32) f32; +}; +``` + +A 40-line `perlin2`/`fbm2` prototype passed range, smoothness and +seed-sensitivity tests, and gave the same bits on native and wasm [verified] +(range about -0.75..0.70, which is typical for 2D Perlin). Simplex/OpenSimplex2 +can come later; Perlin covers NoC chapter 0 and the flow-field examples. + +**Cost:** about 200 lines including Classic and tests, half a day. + +--- + +## 3. Math vocabulary: `Vec2` struct vs `@Vector(2, f32)` vs duck typing + +### What exists + +- `src/sketch/shape.zig` duck-types points: anything with `x`/`y`, or 2+ + element vectors or arrays (`:9-22`). Helpers return the caller's type + (`Out`, `:52-60`). +- `src/sketch/tween.zig:8-33` `lerp` works on floats, vectors, arrays and + structs (it splats `t` for vectors). `progress` (`:65`) is inverse-lerp + clamped, and `ease.*` (`:72`) are the easing curves. +- `src/vector/geom.zig:6-34` already uses `Vec = @Vector(2, f32)` with free + functions `dot`, `cross`, `length`, `normalize`, `perp`, `mix`, `splat`, plus + a full `Affine` (`:36-97`). That is the obvious seed of `sk.math`. +- `std.math` has `lerp` (with `@mulAdd`, where `t` must match the vector type, + so it needs a splat; `math.zig:1382`), `clamp` (scalars and vectors, `:526`), + `wrap` to `[-r, r)` (`:443`), `degreesToRadians`/`radiansToDegrees` + (`:268`, `:303`), `tau`, `atan2`, `hypot`. It has **no** `remap`/`map`, + `smoothstep`, `fract`, `sign`, or angle normalization to `[0, tau)`. + +### `@Vector` findings [verified] + +- Operators work for vector with vector: `pos += vel; vel += acc;`. Scalar + with vector does **not**: `v * 2` is "mixed scalar and vector operands". + You need `v * @as(Vec, @splat(k))`, or `v *= @splat(k)` where the result + type is known. Both batches wrote `scale(v, s)` for exactly this reason + (`helpers_b.zig:216`). +- No `.x`/`.y`: you write `p[0]`/`p[1]`, which is what `flocking.zig:43-46` + has to do. +- **Layout differs by backend:** `@sizeOf/@alignOf(@Vector(2, f32))` is + **16/16 on x86_64 with the self-hosted backend (Debug)**, and 8/8 with LLVM + (`-fllvm`, ReleaseFast), on wasm32 and on aarch64. So: + - in Debug, every `Vec2` in State takes double the space; + - switching `-Doptimize` changes the size, so `migrate` resets every vector + leaf (`memory.zig:102` checks size) and every array-of-structs containing + one (the signature includes offsets). +- Reflection treats a vector as an opaque leaf (`layout.zig:66`, kind + `.bytes`). `fields.zig` prints `<16 bytes>` (`:22`) and refuses `set` + (`:47`). So `get mover.pos`, `set mover.pos.x 100` and a script's + `expect mover.pos.x 320` are all impossible with `@Vector` state today. + +### Proposal + +1. **`sk.Vec2 = extern struct { x: f32 = 0, y: f32 = 0 }`** as the type to + *store*. It is 8 bytes everywhere, flattens to `pos.x`/`pos.y` float + leaves (console, scripts, probe and overlay all work), and `shape.zig` + already accepts it. Its methods follow PVector, so NoC translates line for + line, left to right: + + ```zig + pub const Vec2 = extern struct { + x: f32 = 0, y: f32 = 0, + pub const zero: Vec2 = .{}; + pub fn xy(x: f32, y: f32) Vec2; + pub fn add(a: Vec2, b: Vec2) Vec2; pub fn sub(a: Vec2, b: Vec2) Vec2; + pub fn scale(a: Vec2, k: f32) Vec2; pub fn div(a: Vec2, k: f32) Vec2; + pub fn mul(a: Vec2, b: Vec2) Vec2; // component-wise + pub fn dot(a: Vec2, b: Vec2) f32; pub fn cross(a: Vec2, b: Vec2) f32; + pub fn len(a: Vec2) f32; pub fn lenSq(a: Vec2) f32; + pub fn dist(a: Vec2, b: Vec2) f32; + pub fn normalize(a: Vec2) Vec2; // zero stays zero + pub fn withLen(a: Vec2, m: f32) Vec2; // setMag + pub fn limit(a: Vec2, max: f32) Vec2; + pub fn heading(a: Vec2) f32; pub fn fromAngle(rad: f32) Vec2; + pub fn rotate(a: Vec2, rad: f32) Vec2; pub fn perp(a: Vec2) Vec2; + pub fn lerp(a: Vec2, b: Vec2, t: f32) Vec2; + pub fn simd(a: Vec2) @Vector(2, f32); pub fn of(v: @Vector(2, f32)) Vec2; + }; + ``` + + ```zig + // NoC 1.10, accelerating toward the mouse + const dir = sk.Vec2.xy(in.mouse_x, in.mouse_y).sub(m.pos).withLen(0.2); + m.vel = m.vel.add(dir).limit(m.top_speed); + m.pos = m.pos.add(m.vel); + ``` + + Compare `b.limit(b.setMag(b.scale(sum, 1 / count), maxspeed) - self.velocity, maxforce)` + (`flocking.zig:77`). + +2. **Keep `@Vector` as the compute type**, for anyone who prefers operators: + `sk.math` free functions take `anytype` and follow geom's `@Vector` + versions, so `pos += vel` code works without conversions. For hot loops + over thousands of entities, `simd()`/`of()` convert at the edges. + +3. **Teach `layout.flatten` to split `@Vector(N, T)` leaves into `name[0..N]` + scalar leaves.** That is about 10 lines, and makes `@Vector` state + inspectable even for sketches that choose it. The backend size difference + remains, so document "prefer `sk.Vec2` in State". + +4. **`sk.math`** (scalars; lift `geom.Affine` as `sk.Affine` with + `.identity`, `.translate`, `.rotate`, `.scale`, `.mul`, `.apply`): + + ```zig + /// p5 map(): ranges as pairs so the five floats can't be misordered. + pub fn remap(v: f32, from: [2]f32, to: [2]f32) f32; + pub fn remapClamped(v: f32, from: [2]f32, to: [2]f32) f32; + pub fn smoothstep(e0: f32, e1: f32, x: f32) f32; + pub fn fract(x: f32) f32; + pub fn angle(rad: f32) f32; // normalized to [0, tau) + pub fn approach(cur: f32, target: f32, max_step: f32) f32; + ``` + + ```zig + const y = sk.math.remap(@sin(angle), .{ -1, 1 }, .{ 0, height }); + ``` + + Re-export rather than duplicate: `sk.math.clamp = std.math.clamp`, and + `lerp` stays `tween.lerp` (it already splats). + +**Cost:** Vec2 + `sk.math` + Affine lift is about 250 lines with tests, about +1 day. Vector leaf flattening: 1 hour. + +--- + +## 4. Drawing vocabulary: circles, lines, polylines, polygons, transforms + +### What the hosts can do now + +- Commands (`src/abi.zig:225-300`): `clear`, `rect`, `image`, `text`, `clip`, + plus GPU/compute. +- **Native:** `src/host/gfx.zig:112-148` executes 2D commands on an + `SDL_Renderer` created on the SDL_GPU device (`Host.zig:110-116`; it falls + back to any renderer without a GPU). The vendored SDL 3.4 has + `SDL_RenderGeometry` / `SDL_RenderGeometryRaw` (colored triangles, optional + texture), `SDL_RenderLines` (1 px only), and `SDL_RenderTextureAffine` + (an image under an arbitrary affine transform), all in + `zig-pkg/sdl-*/include/SDL3/SDL_render.h:2331, 2458, 2491`. The SDL renderer + has **no MSAA**, so anything not axis-aligned is aliased unless the geometry + carries its own feathered fringe (ImGui/NanoVG style). +- **Web:** `web/host.js:441-485` draws into a 2D canvas, which has native + antialiased `moveTo/lineTo/arc/ellipse/fill/stroke/setTransform`. It has no + per-vertex colour: Canvas2D cannot shade triangles. +- **GPU passes** (`abi.gpu.Pass`) run on SDL_GPU and WebGPU alike. That is + what the vector module uses. + +### Options and costs + +**A. Shape commands, rasterized natively by each host (recommended).** Add +one command, `path`, and let each host draw it its own way: + +```zig +// abi.Command +/// A polyline or polygon in canvas coordinates, filled and/or stroked. +/// `points` is bulk data: scratch, session or store memory. +path: struct { + points: []const Vec2, // extern {x, y} + closed: bool = true, + fill: ?Color = null, + stroke: ?Color = null, + width: f32 = 1, + join: enum(u8) { miter, bevel, round } = .miter, + cap: enum(u8) { butt, round, square } = .round, +}, +``` + +- **Web:** a `canvas.path(ptr, len, closed, fill_rgba, stroke_rgba, width, join, cap)` + import reads a `Float32Array` view of wasm memory, then does + `beginPath`/`moveTo`/`lineTo`/`fill`/`stroke`. That is about 25 lines of JS + plus 5 in `web.zig` (`submit`, `:175-211`). It is exact and antialiased. +- **Native:** tessellate in Zig, then call `SDL_RenderGeometry`: + - fill: a fan for convex shapes, ear clipping for simple concave ones; + - stroke: per-segment quads plus miter/bevel/round joins and caps; + - a 1 px alpha fringe, so edges are antialiased like canvas. + + Shared Zig, about 300 lines (fill, stroke, fringe, tests). It can reuse + `vector/geom.zig` and the join math in `vector/Polygons.zig:153-335`. + `gfx.draw` (`gfx.zig:112`) needs an arena parameter for vertices + (`Host.zig:303` and `:316` pass `frame_arena`). Converting to `SDL_Vertex` + (float colour, `SDL_render.h:89-94`) is one loop. About 40 lines in + gfx.zig. Known gap: translucent strokes double-blend where joint triangles + overlap (ImGui has the same); canvas does not. +- **Frame helpers** (`src/sketch/root.zig`, next to `fill` at `:77`) build + points in scratch: + + ```zig + pub const Style = struct { + fill: ?Color = null, + stroke: ?Color = null, + width: f32 = 1, + join: ... = .miter, + cap: ... = .round, + }; + pub fn line(f: *Frame, a: anytype, b: anytype, style: Style) void; + pub fn polyline(f: *Frame, points: []const Vec2, style: Style) void; + pub fn polygon(f: *Frame, points: []const Vec2, style: Style) void; + pub fn circle(f: *Frame, center: anytype, radius: f32, style: Style) void; // n from radius + pub fn ellipse(f: *Frame, center: anytype, rx: f32, ry: f32, style: Style) void; + pub fn arc(f: *Frame, center: anytype, r: f32, from: f32, to: f32, style: Style) void; + pub fn strokeRect(f: *Frame, r: anytype, color: anytype, width: f32) void; // replaces ui.outline + ``` + +- **Transform:** a plain field on the Frame value the sketch already holds. + It is not a hidden global, and push/pop is `defer`: + + ```zig + pub const Frame = struct { ..., transform: Affine = .identity, ... }; + + for (s.boids.constItems()) |b| { + const saved = f.transform; + defer f.transform = saved; + f.transform = f.transform.mul(.translate(b.pos.x, b.pos.y)).mul(.rotate(b.vel.heading())); + f.polygon(&.{ .xy(6, 0), .xy(-6, -3), .xy(-6, 3) }, ink); + } + ``` + + Helpers apply `transform` to points on the CPU before emitting. A rotated + `fill` becomes a `path`. `image` gets an optional affine: native + `SDL_RenderTextureAffine` (origin, right, down = the matrix columns, + `SDL_render.h:2331`); web `ctx.save(); ctx.transform(a,b,c,d,e,f); + drawImage; ctx.restore()`. About 15 lines per host. `clip` and `text` take + translation and scale only. + +- **Scale:** 2048 boids is 2048 `path` commands. That is cheap on canvas, and + native batches inside SDL. No JSON, unlike GPU passes on the web. + +- **Total cost for A:** abi 20 lines, Frame helpers + Style + transform 150, + tessellator 300, gfx 40, web.zig 10, host.js 40, e2e screenshots. **About + 2 days.** + +**B. Sketch-side tessellation into a `triangles` command.** Native is easy +(`SDL_RenderGeometry`, about 30 lines). The web cannot do per-vertex colour +in Canvas2D, and filling triangle by triangle leaves antialiasing seams. Only +worth adding *later* for meshes (native exact; web approximates with +flat-colour paths), not as the shape primitive. + +**C. Tessellate into a library-owned GPU pass** (one MSAA draw of all shapes, +with shaders built like `vector`'s). The look is identical on both hosts +(SDL_GPU / WebGPU MSAA), and trails come almost free (section 5). But it +requires a GPU (no WebGPU in insecure contexts or on Firefox Linux), draws +into a separate image so ordering with `rect`/`text` means layers, and needs a +shader build step in the sketch library. **About 3 days.** A good second +backend for heavy particle counts, not the first. + +**D. The vector module, as the NoC helpers do now.** +- `Renderer(.gpu)` emits 2 draws per fill and 2 per stroke (`vector/Gpu.zig:63-80`): + 4 draws per stroked, filled boid, so 8k draws for 2048 boids, each + serialised to JSON on the web (`web.zig:231-280`). +- `Renderer(.cpu)` re-rasterizes and re-uploads the whole canvas every frame + (`vector/root.zig:118-123`). + +Both are right for SVG and manim-style work, but heavyweight as the default +`circle()`. + +**Recommendation:** A now; C later as an opt-in "many shapes" backend. + +--- + +## 5. Persistence of the frame (trails, no `background()`) + +### Facts + +- **Native** clears the window every frame (`Host.zig:285-287`) and presents a + swapchain whose old contents are undefined. Nothing persists without an + offscreen target. +- **Web:** the 2D canvas keeps its pixels between frames unless the sketch + clears or `fit()` resizes (`host.js:21-31`). So web "persists" by accident, + and the hosts disagree. +- **GPU passes with `.clear = null`** keep the image's previous contents + (`abi.zig:440`): + - Web honours that even with MSAA: the msaa attachment is stored and loaded + (`host.js:221-235`). + - **Native does not when `samples > 1`:** `gpu.zig:214` forces `LOADOP_CLEAR` + for multisampled passes. That is a host divergence. The fix is + `SDL_GPU_STOREOP_RESOLVE_AND_STORE` and `LOADOP_LOAD` on the msaa texture + when `clear == null` (about 5 lines). +- `random_walk.zig` works around all this by keeping a 28 KB bitset in State + and re-uploading 900 KB of RGBA every frame (`:19`, `:48-53`). That is + deterministic but heavy. +- When paused, `draw` still runs every frame (`Host.frame`, `:228-242`). + Naive accumulation therefore keeps adding the same shapes while paused, and + after a seek the accumulated picture belongs to another timeline. + +### Proposal: `target` command + `sk.Layer` + +```zig +// abi.Command +/// Commands after this draw into `image` (from Host.newImage), or the canvas again with null. +target: ?Image, +``` + +- **Native:** `SDL_SetRenderTarget(renderer, texture)`. Restore to + `self.offscreen` when headless (`Host.zig:524-535`), else NULL. Reset the + clip rect on every switch. `Images.new` (`gfx.zig:44-48`) must create + `SDL_TEXTUREACCESS_TARGET` textures (or add `newCanvas`). Verify that + `SDL_UpdateTexture` (`.pixels`) still works on target textures, and how + logical presentation and render scale apply per target in SDL 3.4: a + 10-line experiment. `.clear` calls `sk_text_begin_frame` (`gfx.zig:115`), + which flushes first (`vendor/text.c:105-113`), so it is safe. Text density + inside a target needs checking (`text.c:115`). +- **Web:** `newImage` already makes a 2D canvas per image (`host.js:427-431`). + `target(id)` switches the `ctx` the canvas imports draw with (make it + `let`). Identity transform for image canvases, `fit()`'s scale for the main + one. About 15 lines. +- Make sure `.image` of the *current* target is refused, since you can't + sample what you're drawing. + +```zig +/// Session: an accumulating picture. A presentation cache, not state: it +/// restarts after a seek, a replay or a reload, and adds nothing while paused. +pub const Layer = struct { + image: Image = .none, + w: u32 = 0, h: u32 = 0, + /// The state step drawn last. + drawn: u64 = 0, + + /// Starts drawing into the layer; false when `step` has not moved on. + /// Clears on first use, on size change, and when `step` went backwards. + pub fn begin(l: *Layer, f: *Frame, step: u64, clear: Color) bool; + /// Back to the canvas, and shows the layer at `dst`. + pub fn end(l: *Layer, f: *Frame, dst: anytype) void; +}; +``` + +```zig +// NoC 0.1 random walk, without a bitset in State: +pub const State = struct { + walker: sk.Vec2 = .xy(320, 180), + rng: std.Random.DefaultPrng = .init(1), + clock: sk.Clock = .{}, + /// Every position since the last draw could have missed: steps are + /// fixed-rate, frames are not. + recent: sk.Ring(sk.Vec2, 64) = .{}, +}; +pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { + if (ss.trail.begin(f, s.recent.pushed, .white)) { + var it = s.recent.since(ss.trail.drawn); + while (it.next()) |p| f.fill(.{ .x = p.x, .y = p.y, .w = 1, .h = 1 }, .black); + } + ss.trail.end(f, .{ .x = 0, .y = 0, .w = 640, .h = 360 }); +} +``` + +`Ring.since` is what makes it exact: at 30 Hz display and a 60 Hz step, +every step is still drawn. For p5's `background(0, 12)` fading trails, draw a +translucent full-canvas `fill` into the layer first. Known 8-bit residue: the +fade never reaches pure black. Document it. + +For pictures that must be exact under seek (sand piles, CA history), keep the +data in State (bitset or `List`) as `random_walk` does. The Layer is the cheap +answer for everything else. + +**Cost:** abi 3 lines, gfx/Host 30, web 20, Layer + Ring 80, native MSAA load +fix 5. **About 1 day.** + +--- + +## 6. What to lift from the game and the NoC helpers + +| Where | What | Lift as | +| --- | --- | --- | +| `helpers_a.zig:17-27` (both batches needed it; B is frame-rate dependent without it) | 60 Hz fixed step from tick dt, clock in State | `sk.Clock = struct { carry: f64 = 0, steps: u64 = 0, pub fn advance(c: *Clock, in: *const Input, hz: f32) u32 }`, used as `for (0..s.clock.advance(in, 60)) \|_\| step(s);` | +| `flocking.zig:128-135` and three more | `paint(...) catch \|err\| f.host.print(...)` wrappers | Let `draw`/`init`/`update` return `!void`. In `Glue` (`root.zig:282-292`): if the return type is an error union, log `"{name}: {t}"` through `host.print`. About 8 lines. Frame drawing methods stay infallible (they already log OOM, `root.zig:65-67`). | +| `ui.zig:16-18` | `rect(x, y, w, h)` constructor | decl literal `sk.Rect.xywh(x, y, w, h)`, so `.xywh(...)` where the type is known | +| `ui.zig:20-25` | outline as 4 fills | `f.strokeRect` / `path` with `stroke` | +| `ui.zig:88-105` | tail as 96 rects | `f.polyline(points, .{ .stroke = pink, .width = 3 })` | +| `ui.zig:30-35`, used by computer/lock/inventory/portrait/dialogue | press-and-release-on-same-target click | `sk.Press(Target)`: `pressed: T = none`, `fn click(p, target, e) bool`. Every scene's `pressed: Target = .none` + `ui.clicked` call becomes one field and one method. | +| `ui.zig:37-64` | beveled button | stays game-side (it's a look), but motivates `sk.Press` | +| `dialogue.zig:38-50`, `Choice` `:26-34`, `room.zig:75-92`, `tracker.zig:30` | `[N]T` + `len` everywhere, `[N]u8` text + `len` | `sk.List(T, N)`; `sk.List(u8, N)` with `appendSlice`/`set(text)` for bounded strings | +| `assets.zig:150-243`, `sounds.zig:69-104` | lazily loaded catalogue keyed by a comptime-generated enum, in Session | `sk.Images(Id)` / `sk.Sounds(Id)` over `std.EnumArray(Id, Image)` plus a `loaded` bitset, with `get(host, id)` and `check(host) usize`. `std.EnumArray` is the std idiom here. | +| `sounds.zig:50-67` | per-bank serial counters + active bits to retrigger voices | a `sk.Cue` (serial: u16, `fire()`) in State, taken by `f.voice(.{ .serial = s.cue.serial, ... })`; this generalises `sk.Request` (`request.zig:11`) | +| `ui.zig:68-84` | damped follower advanced per event | an example, not library (NoC chapter 3 springs cover it) | +| `room.zig:69-71` | rect scaled from source-image pixels | `sk.shape.scale(r, k)` next to `inset`/`offset` (`shape.zig:126-135`) | +| `flocking.zig:131-134` | timing draw with `host.clock()` + env flag | host overlay `overlay timing`: the host already knows each draw's duration | + +### API-shape proposals from std conventions + +- **Decl literals:** `.empty` for containers (`List`), `.init(seed)` for + things that need arguments (PRNG, `Classic`), `.zero`/`.identity` for values + (`Vec2`, `Affine`), and `Color.gray(v)`, `.rgb()`, `.hsv()`, `.hex()` + constructors. These only work where the parameter is *typed*. With + `anytype` (`shape.color`, `shape.zig:94`), `f.clear(.gray(51))` fails to + compile ("not a function") [verified]. Two cheap fixes: + 1. `shape.color` maps an enum literal to a `Color` declaration + (`@field(Color, @tagName(c))`), so `f.clear(.black)` works [verified]; + 2. new APIs take `Style`/`Color` typed (`Style.fill: ?Color`), so + `.{ .fill = .gray(127) }` works. +- **Options structs** with defaults, as std does + (`std.ArrayList.initCapacity` aside, see `Io.Dir.OpenOptions`): + `f.image(img, dst, options: anytype)` (`root.zig:81`) is the only `anytype` + options parameter left. Type it as `struct { src: ?Rect = null, tint: Color = .white, transform: ?Affine = null }` + for ZLS completion and better errors, as `audio`/`pixels`/`download` + already are (`:113-157`). +- **Errors:** container ops return `error.OutOfMemory` like the `*Bounded` + ArrayList methods, so `try`/`catch {}` reads the same as std. +- **std.Io:** don't hand sketches an `Io`. `Host` (`abi.zig:445-531`) is + already the explicit capability object, it covers what sketches need + (files, clock, env), and the web has no `Io` implementation. Keep `Io` out + of `update` above all: its randomness and clock are nondeterministic. +- **SPIR-V (brief):** 0.17 has `std.spirv` (builtins as `addrspace(.input)` + externs, `spirv.zig:1-25`), `callconv(.spirv_vertex/.spirv_fragment/.spirv_kernel)` + (`lang.zig:382-384`) and `@SpirvType`. The interest for this design is + that a Zig shader could share `sk.Vec2`/vertex structs directly with option + C's shape pipeline. But web still needs WGSL via naga, which the GLSL path + already does. Left to the shader research. + +--- + +## Cross-check against the other research (board.md) + +- **research-love P2 `Command.shape`** (one colour, pre-transformed triangles + that don't overlap, plus an optional alpha fringe; the web fills them as + one nonzero path): **I adopt it in place of my `path` command (option A).** + - Tessellation stays in the hot-reloadable library, both hosts get the same + geometry, and the host side is about 30 lines each. gfx.draw needs an + arena parameter (`Host.zig:303,316`). One fill per shape on the web has + no seams. + - Risk to test: strip-tessellated strokes fold back on the inner side of + acute joins. The flipped, opposite-winding triangles cancel under nonzero + on the web (a hole) and double-blend natively. Compute inner-join points, + falling back to bevel when the miter passes the segment ends, and add a + translucent zig-zag e2e screenshot on both hosts. + - My section 4 frame helpers (`line/polygon/circle/...`, `Style`, + `f.transform` with `defer`) still hold; research-love's `Pen` value + (`translated()` returns a copy) is the same idea. Either works; the Pen + copy needs no `defer`. +- **research-love P4 `sk.Rng{ s: [4]u32 }` integer-only**, and research-p5's + "pin the PRNG": agree on owning the generator, because a std release could + change `DefaultPrng` or `Random.float` under saved recordings. Float parity + is *not* the reason: std floats already match bit for bit across hosts + (section 2). Two corrections: + 1. the `s` array is not visible to `get`/`set` today (`fields.zig:22,47`) + until arrays become indexed leaves (section 1); + 2. noise needs a `seed` parameter (`simplex2(x, y)` has none), because + flow_field reseeds on click (`flow_field.zig:91`). +- **research-love P10 `sk.Bounded` and `sk.v2` over `@Vector`**: + - `Bounded` = my `List`: same migration hazard (verified), so it needs + element-wise migration and clamped `items()`. + - `sk.v2` is fine as compute functions, but don't recommend `@Vector` + *storage* in State: it is 16 B in Debug on x86_64 and opaque to + get/set/expect. Store `extern Vec2`, or at least split vector leaves into + `[0]`/`[1]`. +- **research-love P6 targets + `Input.jumped`**: adopt `jumped` in place of + my step-went-backwards heuristic. Keep the two extra rules from section 5: + no accumulation while paused, and `Ring.since` for skipped steps. +- **Coordinator: element-wise migration is the real gap**: confirmed by + running the real `memory.migrate` (section 1). +- **Owner: knobs in build.zig.** These host constants are hardcoded today: + - `slot_count = 8` and `header_len = 64 KiB` (`memory.zig:21-22`); + - `store_base` and `store_reserve = 64 GiB` (`:318-320`); + - the web event queue `[1024]Event` (`web.zig:74`); + - `keep_frames = 300` and `staging_size = 4 MiB` (`gpu.zig:13,108`); + - and a `use_llvm` choice for Debug sketch libs, which fixes `@Vector`'s + layout. + + These belong in `sketchbook.init(b, .{ ... })` (`build.zig:202`) as a + generated options module. Algorithm choices (noise flavour, PRNG) stay as + explicit calls in code, not build-global modes. + +--- + +## Ranked proposals + +| # | Proposal | Cost | Removes | +| --- | --- | --- | --- | +| 1 | `Command.shape` (research-love P2; replaces my `path`) + lib tessellator + `f.line/polyline/polygon/circle/ellipse/arc/strokeRect` / Pen + `Style` + transform + image affine | ~2 days | both `Pen`s, the vector-module dependency for basic shapes, `ui.outline`, the 96-rect tail | +| 2 | `sk.List(T, cap)` (clamped `items()`, std bounded naming) + `sk.Ring` | ½ day | helpers_b List, every `[N]T + len` in the game | +| 3 | Element-wise array migration (repeat leaves, prefix copy, indexed paths) | ~1 day | particle wipes and zombie `len` on reload; protects tracker songs | +| 4 | `sk.Vec2` extern struct with PVector methods + `sk.math` (`remap` with ranges, `smoothstep`, `fract`, `angle`) + `sk.Affine` lifted from `vector.geom`; flatten `@Vector` leaves | ~1 day | both batches' PVector helpers, `p[0]` indexing, uninspectable vector state, backend-dependent 16-byte vectors | +| 5 | Randomness: own pinned generator (`sk.Rng`, research-love P4, Xoshiro/PCG with our own `float`), or `std.Random.Xoshiro256` by concrete name, never the `DefaultPrng` alias; free helpers `range/gaussian/unit/pick/stream` | 2 h | `range`/`random` helpers | +| 5b | Build options for hardcoded host constants (snapshot slots, header size, store reserve, web event queue, gpu cache/staging, Debug backend) | ½ day | owner's "knobs in build.zig" | +| 6 | `sk.noise`: table-free `perlin2/3`, `fbm` with options, `hash01`, Processing-exact `Classic` | ½ day | both noise ports | +| 7 | `target` command + `sk.Layer` (+ native MSAA `clear = null` fix) | ~1 day | random_walk's bitset + full re-upload; host divergence | +| 8 | `sk.Clock` fixed step | 1 h | `steps60`; batch B's refresh-rate-dependent speed | +| 9 | Fallible `draw`/`update`/`init` logged by Glue; typed options; decl-literal colours (`.black`, `.gray(v)`) | 2 h | four `paint` wrappers; `anytype` papercuts | +| 10 | Game lifts: `sk.Press(T)`, `sk.Images(Id)`/`Sounds(Id)` over `std.EnumArray`, `sk.Cue` | ½ day | per-scene click bookkeeping, asset library boilerplate | |
