summaryrefslogtreecommitdiff
path: root/examples/noc/notes/research-zig-internals.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/research-zig-internals.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-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.md770
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 |