diff options
Diffstat (limited to 'examples/noc/notes/research-processing-p5.md')
| -rw-r--r-- | examples/noc/notes/research-processing-p5.md | 461 |
1 files changed, 461 insertions, 0 deletions
diff --git a/examples/noc/notes/research-processing-p5.md b/examples/noc/notes/research-processing-p5.md new file mode 100644 index 0000000..33a6bd3 --- /dev/null +++ b/examples/noc/notes/research-processing-p5.md @@ -0,0 +1,461 @@ +# Processing / p5.js → sketchbook + +What to take from Processing 4 and p5.js 2.4 so that sketchbook is as quick +to iterate in, without giving up what sketchbook gets right: plain-data State, +deterministic replayed `update`, `draw` that emits commands as data, every +command runnable by both hosts, GPU work as data. + +Paths below are relative to: +- `P/` = `~/05-genizah/processing4/core/src/processing/` +- `p5/` = `~/05-genizah/p5.js/src/` (2.4.0-rc.2, commit 1ae94e6) +- `sb/` = `~/00-projects/0x4200.cafe/01-drat-meout/lib/sketchbook/` + +**Evidence from the NoC ports.** Two port batches running now +(`src/helpers_a.zig`, `src/helpers_b.zig`) each wrote the same helpers +without coordinating: 60 Hz steps from tick events, PVector's +`setMag/limit/heading/fromAngle`, `random(lo, hi)` over +`std.Random.DefaultPrng`, Processing's `noise()`, a fixed-capacity `List` +for State, and a "Pen" (fill/stroke/weight/transform, circle/line/polygon) +that rasterizes a `vector.Drawing` through `vector.Renderer(.cpu|.gpu)` into +an image every frame. That is the shopping list. Most items below exist so +that the next port does not write these helpers a third time. + +--- + +## 1. How Processing and p5 do it + +| Area | Processing 4 | p5.js 2.4 | sketchbook today → verdict | +|---|---|---|---| +| **Draw loop, frame persistence** | `handleDraw` `P/core/PApplet.java:2026-2120`: `setup()` when `frameCount==0`, latches `pmouseX` (2099), `draw()`, then `dequeueEvents()` (2112): callbacks run *after* draw. The canvas is never cleared for you. | `_draw` `p5/core/main.js:311-362`: rAF, throttled to the target fps with a 5 ms epsilon. `redraw` `p5/core/structure.js:326-365` resets **only the matrix** (342) and bumps `frameCount`. Fill/stroke set late in one frame carry into the next. Canvas persists. | Host clears to black every frame and draws again while paused or seeking (`sb/src/host/Host.zig:285-287`). **Keep.** Persistence is a trap (§3). | +| **frameCount / deltaTime / millis / frameRate** | `frameCount` field (693); `frameRate` is an EMA (2085-2090); `millis()` is wall-clock `currentTimeMillis - offset` (2887). | `deltaTime` from rAF timestamps (`main.js:331`); `millis` `p5/utilities/time_date.js:237`; `frameRate(fps)` `p5/core/environment.js:397`. | `in.frame` is bumped in `draw` (`Host.zig:277`), so it counts redraws. **`in.dt` is not set during replay**: the playing branch of `Host.frame` (`Host.zig:229`) never writes it, and `Host.update` (243-254) does not either. `in.now` is the host clock live but recording-relative in replay (`sb/src/abi.zig:53-54`, `sb/src/host/timeline.zig:114`). So an `update` that reads `in.dt` or `in.now` replays differently. **Fix it, and add a State `Clock`** (P5). | +| **random** | `PApplet.java:4696-4801`: a lazy `new java.util.Random()` (4707) that is unseeded unless you call `randomSeed`; `randomGaussian` → `Random.nextGaussian` (4738). `PVector.random2D()` uses `Math.random()` unless you pass the applet (`P/core/PVector.java:242-245`), so it **ignores randomSeed**. | `p5/math/random.js`: Numerical Recipes LCG (13-27), state stored per instance; **falls back to `Math.random()` until seeded** (278-282). Gaussian is Marsaglia polar with the spare value `y2` kept **module-global** (18, 360-379), so it is shared across instances. `p5.Vector.random2D` uses `Math.random` (`p5/math/p5.Vector.js:3150`). | No helpers; the ports use `std.Random.DefaultPrng` in State. **Take, as a generator stored in State with a pinned algorithm, plus stateless keyed randomness** (P3). | +| **noise** | `PApplet.java:4845-5057`: *value* noise (not gradient noise) on a 4096-float lattice; **`abs()` on every coordinate** (4937), so `noise(-x) == noise(x)`; cosine-LUT smoothing (`noise_fsc`); 4 octaves with falloff 0.5; the table is filled lazily from an unseeded `Random`; `noiseSeed` drops the table (5053). | `p5/math/noise.js`: a straight port (header 1-13), `Math.cos` smoothing (29); **the table is module-global** (31, 268-273), shared by every p5 instance on the page; `noiseSeed` refills it from an LCG (466-505). | None. **Take, as pure functions with the seed as an argument, plus a faithful "classic" mode for ports** (P4). | +| **Style state, push/pop** | `P/core/PStyle.java`: about 30 public fields. `pushStyle` copies all of PStyle into an array stack (`P/core/PGraphics.java:6268-6298`) and throws on underflow (6294). `push()` = `pushStyle()` + `pushMatrix()` (5273). | `p5/core/States.js:1-33`: records diffs (`setValue` remembers a key's first old value); `push` saves the diff and `pop` applies it (`p5/core/p5.Renderer.js:142-155`); **a pop on an empty stack silently uses `{}`** (151). Renderer2D also calls `ctx.save/restore` (`p5/core/p5.Renderer2D.js:877-892`). | No style. **Take, as a value (`Pen`) whose copies replace push/pop** (P2). | +| **Matrix stack** | Java2D keeps a stack of cloned `AffineTransform`s (`P/awt/PGraphicsJava2D.java:75, 2159-2176`). OpenGL keeps 32-deep `float[16]` stacks (`P/opengl/PGraphicsOpenGL.java:302-320, 3683-3715`). | 2D uses the canvas context's transform (`resetMatrix` `p5.Renderer2D.js:834`). 3D keeps `states.uModelMatrix`, cloned on write (`p5/core/p5.Renderer3D.js:98, 787-805`). | None. **Take, as a CPU-side affine inside the Pen.** Commands stay in absolute canvas pixels. | +| **beginShape / vertex / endShape, batching** | `beginShape` stores the kind (`PGraphics.java:1198`); `vertex` writes into `vertices[][]` (1362). OpenGL **tessellates at `endShape` with the current modelview applied on the CPU** (`PGraphicsOpenGL.java:2180-2222`), appends to `tessGeo`, and flushes only when full or when state changes (1930-1940, 2247-2280: "the modelview transformation has been applied already ... set the OpenGL modelview matrix as the identity"). A `blendMode` change forces a flush (6212-6216). Java2D builds a `GeneralPath` (`PGraphicsJava2D.java:58, 746`). | Every primitive becomes a `p5.Shape` made of primitives (`p5/shape/custom_shapes.js:687`), turned into output by visitors: `PrimitiveToPath2DConverter` (1270) for 2D, `PrimitiveToVerticesConverter` (1554) for WebGL. Renderer2D does one `ctx.fill`/`ctx.stroke` per shape (`p5.Renderer2D.js:280-301`). WebGL issues **one draw call per immediate shape** (`p5.Renderer3D.js:528-547`); only `buildGeometry` is retained. | Only `rect` fills; the ports go through the vector module. **Take Processing's model**: tessellate in shared Zig with the transform applied, batch, and emit one flat-colored triangle command (P1). p5's shape-as-data visitor is the right internal structure for `sk.Path`. | +| **rectMode / ellipseMode** | A switch inside `rect` (`PGraphics.java:2684-2718`). | `modeAdjust` (`p5/core/helpers.js:12-60`). | **Trap as a mode.** Take it as rect constructors (P11). | +| **colorMode / HSB / lerpColor** | `colorCalc` clamps to the mode's maxes and converts HSB→RGB inline (`PGraphics.java:7684-7735`); `colorMode` (7560-7578); `lerpColor` (8122-8134). | `colorMode` keeps per-mode maxes in renderer state (`p5/color/setting.js:1044-1065`); Color sits on colorjs spaces (`p5/color/p5.Color.js:59-101`); `lerpColor` interpolates in the current space (`p5/color/creating_reading.js:1825-1845`). | `shape.color` is duck-typed RGB only. **Take, as pure constructors and `mix(space)`. Not as a mode** (P8). | +| **blendMode** | OpenGL flushes, then sets the blend equation per mode (`PGraphicsOpenGL.java:6212-6260`). | Sets `globalCompositeOperation` (`p5.Renderer2D.js:475-500`); SUBTRACT is WebGL-only (481). | Only alpha blending for 2D; `abi.gpu.Blend` covers passes. **Take, as a Pen field that becomes a stateful command only when it changes, limited to modes both hosts can run** (P9). | +| **Offscreen buffers** | `createGraphics` (`P/core/PApplet.java:1764-1880`) returns a full PGraphics with its own style and matrix state. | `createGraphics` (`p5/core/rendering.js:407`), `p5.Graphics` with its own renderer (`p5/core/p5.Graphics.js:27-38`; `reset()` resets only the matrix, 232); `createFramebuffer` (`rendering.js:559`, `p5/webgl/p5.Framebuffer.js:58`). | GPU passes already draw into Images; 2D commands cannot. **Take, as a target command** (P10). | +| **Shaders, filter, uniforms** | `loadShader` (`PGraphics.java:1945`, `PGraphicsOpenGL.java:6911`); uniforms go into a **HashMap by name**, applied at bind time (`P/opengl/PShaderOpenGL.java:742-760`); `filter(PShader)` (`PGraphicsOpenGL.java:6049`). | `loadShader` is async (`p5/webgl/material.js:130`); `setUniform` by name **silently ignores unknown names** (`p5/webgl/p5.Shader.js:1141-1150`); `modify(hooks)` patches shaders through string hooks (425); built-in filters are made with strands (`p5/core/filterShaders.js:12`). | Comptime std140 structs, glslc/naga at build time, pipelines cached by content hash. **Better already. Keep it**, and add a stock fullscreen/filter helper (P12). | +| **Input** | `mouseX` etc. are globals (352); `pmouseX` latched once per frame (2099); callbacks are queued and dispatched after draw (2112, 2264). | Globals plus callbacks fired from DOM handlers at event time (`p5/events/keyboard.js:606-623`, `p5/events/pointer.js:1067, 1231`). | A recorded `Event` list handed to `update`. **Better already.** Add sugar (P14). | +| **saveFrame** | `saveFrame("f-####.png")` writes synchronously and numbers by frameCount (`PApplet.java:3559-3620`). | `saveCanvas` (`p5/image/image.js:250`); `saveFrames` captures on a wall-clock `setInterval`, **capped at 15 s and 22 fps** (631-660). | `screenshot` in scripts. **Take, as a deterministic export from a recording** (P13). | +| **PVector / map / constrain** | Mutating methods with static twins (`PVector.java`). `map`/`constrain` (`PApplet.java:4657, 4326`). | `p5.Vector`; `map(…, withinBounds)` (`p5/math/calculation.js:866`). | `@Vector(2, f32)` already has `+ - *`, and State can hold vectors (`sb/src/layout.zig:87, 125`). **Take the missing functions** (P7). | +| **Tweak mode** | The editor replaces every literal with `tweakmode_int[i]`/`tweakmode_float[i]` (`~/05-genizah/processing4/java/src/processing/mode/java/JavaEditor.java:2140`) and injects a UDP server thread into the sketch (`.../tweak/TweakClient.java:123`). | n/a | `sb/docs/regions-in-source.md` gets the same result with no code injected (rewrite the literal, hot reload). **Keep sketchbook's design.** | + +--- + +## 2. Proposals + +Each proposal gives: how a sketch reads, where it lives, cost on native and +web, and the invariant it touches. "sketch lib" means `sb/src/sketch/`, +which is compiled into the sketch and so behaves the same on both hosts. + +### Relation to research-love (notes/research-love-raylib.md) + +LÖVE, raylib and Processing's OpenGL renderer arrive at the same design: CPU +transform, CPU tessellation, flat batches. So P1, P2, P5, P3/P4, P9 and P10 +below agree with research-love's P2, P1, P3, P4, P5 and P6. Where this +document differs: +- **One command per shape, as research-love has it** (`Command.shape`, no overlap *within* a shape). I drop my "union over the whole command" contract: p5 composites each shape on its own (`p5.Renderer2D.js:280-301`), so overlapping translucent circles must darken. Coalescing is a host-local optimization, and it is **safe only for opaque runs**: merging translucent shapes into one path would change the picture on the web. +- **Blend: three 2D modes, not four.** I had `screen` through `SDL_ComposeCustomBlendMode`. It does not match Canvas2D when alpha < 1: canvas gives `a·s + d·(1 − a·s)`, while the factor pair (SRC_ALPHA, ONE_MINUS_SRC_COLOR) gives `a·s + d·(1 − s)`. Agreed: `{alpha, add, multiply}`. +- **Use `Input.jumped`** (research-love P6) instead of my `ss.drawn != ticks` check in P10. +- **New here:** the `in.dt`/`in.now` replay bug (P5), seed-ignoring `random2D` and module-global noise state in the references (§3), deterministic export (P13), and radius over diameter (P2). +- **Build-time knobs** (the owner's rule): see "Build options" after P14. + +### P1. `Command.triangles` + tessellation in the Frame (lines, circles, polygons, strokes) + +> Superseded in naming and contract by research-love's `Command.shape` +> (one shape per command, no overlap within it, optional AA fringe). The +> web code and segment-count rule below still apply. Batch only opaque +> same-color runs, and do it in the host. + +The single biggest gap. Tessellate in shared Zig and keep both hosts simple. +This is Processing's OpenGL model, transform applied on the CPU. + +```zig +// abi.zig, Command +/// Triangles, 3 points each, in canvas pixels, any winding, filled once +/// with `color`: where triangles overlap, the color is applied once (union), +/// as one canvas path fill would. +triangles: struct { color: Color, points: []const [2]f32 }, +``` + +Tessellation lives in the sketch lib (`sb/src/sketch/tess.zig`, about 400 lines): +- ellipses and arcs as fans, with the segment count taken from the on-screen radius: `n = clamp(ceil(π / acos(1 - 0.25/r_px)), 8, 256)`, where `r_px = r * m.scaleFactor()`; +- lines and polylines as quads, plus join wedges (miter, bevel, round) and caps; +- simple concave polygons by ear clipping. Holes and self-intersection go to the `vector` module, which stays the high-quality path (AA, gradients, even-odd). + +Batching: the Frame keeps the index of the last `.triangles` command and a +scratch `ArrayList([2]f32)`. An emit with the same **opaque** color and blend +appends to that list and patches the command's slice; anything else closes +the batch. Translucent shapes are never merged, because union semantics would +stop overlapping circles from darkening, unlike p5. (p5 WebGL's one draw per +shape, `p5.Renderer3D.js:528-547`, is what this avoids.) + +- **Native** (`sb/src/host/gfx.zig`, about 60 lines): opaque → one `SDL_RenderGeometry` (`/usr/include/SDL3/SDL_render.h:2464`) from an `SDL_Vertex` array in the frame arena. Translucent → draw opaque into a bbox-sized scratch target, then composite it with alpha mod, so stroke joins do not double-blend. Not antialiased at first. A later MSAA SDL_GPU pipeline for this one command is a host-only change: no sketch changes. +- **Web** (about 20 lines of JS plus one `extern "canvas"` in `sb/src/sketch/web.zig`): + ```js + triangles(ptr, n, r, g, b, a) { + const v = new Float32Array(wasm.memory.buffer, ptr, n * 2), p = new Path2D(); + for (let i = 0; i < n * 2; i += 6) { // force one winding so nonzero = union + const [ax, ay, bx, by, cx, cy] = v.subarray(i, i + 6); + p.moveTo(ax, ay); + if ((bx - ax) * (cy - ay) - (by - ay) * (cx - ax) >= 0) { p.lineTo(bx, by); p.lineTo(cx, cy); } + else { p.lineTo(cx, cy); p.lineTo(bx, by); } + } + ctx.fillStyle = rgba(r, g, b, a); ctx.fill(p, 'nonzero'); + }, + ``` + One path per command means no seams between triangles, and union coverage for free. +- **Invariants**: commands stay data, both hosts run it, `abi.hash` changes. State is untouched. + +### P2. `sk.Pen`: style and transform as a value; push/pop is `const` + +```zig +pub fn draw(s: *const State, f: *sk.Frame) void { + f.clear(0xffffff); + const pen = f.pen(.{ .fill = 0x7f7f7f, .stroke = .{ .color = 0x000000, .weight = 2 } }); + for (s.movers.view()) |m| pen.circle(m.pos, m.mass * 4); + + // push(); translate(); rotate(); ...; pop(); + const arm = pen.translate(s.origin).rotate(s.angle); + arm.line(.{ 0, 0 }, .{ s.len, 0 }); + arm.with(.{ .fill = sk.hsv(0.02, 0.7, 0.9) }).circle(.{ s.len, 0 }, 12); + // no pop: `arm` goes out of scope + + var wave = f.path(); // beginShape() + for (s.ys, 0..) |y, i| wave.lineTo(.{ @as(f32, @floatFromInt(i)) * 8, y }); // vertex() + pen.with(.{ .fill = null }).draw(wave); // endShape() +} +``` + +```zig +// sb/src/sketch/pen.zig +pub const Stroke = struct { color: Color = .black, weight: f32 = 1, cap: Cap = .round, join: Join = .miter }; +pub const Style = struct { fill: ?Color = .white, stroke: ?Stroke = null, blend: Composite = .alpha }; +pub const Pen = struct { + frame: *Frame, + m: Affine = .identity, + style: Style = .{}, + pub fn with(p: Pen, overrides: anytype) Pen // Style fields by name; colors duck-typed + pub fn translate(p: Pen, by: anytype) Pen // any point type + pub fn rotate(p: Pen, radians: f32) Pen + pub fn scale(p: Pen, by: anytype) Pen // f32 or point + pub fn circle(p: Pen, center: anytype, radius: f32) void + pub fn ellipse(p: Pen, center: anytype, radii: anytype) void + pub fn arc(p: Pen, center: anytype, radii: anytype, from: f32, to: f32, kind: enum { open, chord, pie }) void + pub fn rect(p: Pen, r: anytype) void // emits `.rect` when m is translate+scale + pub fn line(p: Pen, a: anytype, b: anytype) void + pub fn polyline(p: Pen, points: anytype) void // slice of any point type + pub fn polygon(p: Pen, points: anytype) void + pub fn point(p: Pen, at: anytype) void + pub fn draw(p: Pen, path: Path) void // fill then stroke + pub fn image(p: Pen, img: Image, dst: anytype, options: anytype) void // affine via P6b +}; +``` + +- Opinion: use **radius, not diameter** (`circle(x, y, d)` in p5). It matches `ellipse(center, radii)` and the Camera's math. Write the port gotcha in the docs once. +- `Affine` moves from `sb/src/vector/geom.zig:36` into the sketch lib; `vector` re-exports it, so there is one type. +- `sk.Path` is a scratch-allocated builder (`moveTo`, `lineTo`, `quadTo`, `cubicTo`, `close`, with a new subpath on `moveTo` as `beginContour`). It is p5's Shape-as-data idea, without the begin/end state machine. +- Where: sketch lib only, about 200 lines. Cost: none on the hosts. +- Invariant: none. The Frame is rebuilt for each draw (`sb/src/sketch/root.zig:381`), so nothing can leak from frame to frame (the p5 bug at `structure.js:342`), and a forgotten pop cannot exist. + +### P3. `sk.Rng` in State, with a pinned algorithm, plus keyed stateless randomness + +```zig +pub const State = struct { + rng: sk.Rng = .init(1), // randomSeed(1) + clock: sk.Clock = .{}, + walker: sk.V2 = .{ 320, 240 }, +}; +pub fn update(s: *State, in: *const sk.Input) void { + for (0..s.clock.steps(in, 60)) |_| + s.walker += .{ s.rng.range(-1, 1), s.rng.range(-1, 1) }; +} +pub fn draw(s: *const State, f: *sk.Frame) void { + // jitter in draw: still while paused, identical on replay + for (s.stars.view(), 0..) |star, i| + pen.point(star + sk.v2.splat(sk.rand.at(s.seed, .{ i, s.clock.ticks }) - 0.5)); +} +``` + +```zig +pub const Rng = struct { + /// PCG32. Pinned here, not `std.Random.DefaultPrng`: a Zig release may + /// change that alias, or `Random.float`, under a saved recording. + state: u64, + inc: u64 = 0xda3e39cb94b95bdb, + spare: f32 = 0, // Marsaglia's second value, kept in State + has_spare: bool = false, // (p5 keeps it module-global: random.js:18) + pub fn init(seed: u64) Rng + pub fn float(r: *Rng) f32 // [0, 1) + pub fn range(r: *Rng, lo: f32, hi: f32) f32 // random(lo, hi) + pub fn below(r: *Rng, comptime T: type, n: T) T + pub fn chance(r: *Rng, p: f32) bool + pub fn gaussian(r: *Rng, mean: f32, sd: f32) f32 + pub fn pick(r: *Rng, items: anytype) @TypeOf(&items[0]) + pub fn onCircle(r: *Rng) V2 // PVector.random2D, seeded + pub fn fork(r: Rng, key: u64) Rng // an independent stream per subsystem + pub fn random(r: *Rng) std.Random // for std.Random.shuffle and friends +}; +pub const rand = struct { + /// Stateless: the same seed and key give the same number. The key is a + /// tuple of ints. + pub fn at(seed: u64, key: anytype) f32 +}; +``` + +- Opinion for hot reload: one sequential stream makes edits non-local. Add one `random()` call in `update` and every later draw shifts. Prefer `fork(id)` per entity or `rand.at(seed, .{ id, tick })`. Then editing one subsystem leaves the others' randomness alone, which matters when you iterate against a saved State. +- Where: sketch lib, about 120 lines. Hosts: none. Invariant: supports determinism. Every field is plain data, so it migrates by field. + +### P4. `sk.noise`: pure, seeded, with a GLSL twin; `Classic` for parity with the book + +```zig +const n = sk.noise.fbm(s.seed, sk.V2{ x * 0.01, y * 0.01 }, .{}); // ≈ p5 noise(x*.01, y*.01), 0..1 +const g = sk.noise.perlin(s.seed, .{ x, y, t }); // gradient noise, -1..1 +const P = sk.noise.Classic(.processing, 0); // noiseSeed(0), bit for bit +const v = P.get(x, y, 0); +``` + +- `perlin(seed: u32, p: anytype)` is improved gradient noise. It hashes `(seed, lattice)` instead of building a permutation table, so a runtime seed costs nothing and there is no lazy init. `fbm(seed, p, .{ .octaves = 4, .falloff = 0.5, .lacunarity = 2 })` rescales to 0..1 like p5. +- `Classic(comptime gen: enum { processing, p5 }, comptime seed: u64)` is a type whose 4096-float table is built at comptime (16 KiB rodata). `.processing` uses java.util.Random (as `helpers_a.zig` already does); `.p5` uses the LCG from `noise.js:466-505`. It keeps the `abs()` mirror (`PApplet.java:4937`) **only here**, for porting; the docs explain why the default avoids it. +- `sb/shaders/noise.glsl` with the same hash, so a compute flow field and a CPU flow field agree, up to float precision. GPU results never feed `update`. +- Where: sketch lib, about 150 lines, plus the GLSL include (through `addShaders` include paths). Invariant: none. Pure functions are safe in `update` and `draw`. + +### P5. Time: a `sk.Clock` in State, and make `in.dt` honest in `update` + +```zig +pub const Clock = struct { + carry: f64 = 0, // tick seconds not yet stepped + ticks: u64 = 0, // frameCount, for update + seconds: f64 = 0, // millis() / 1000, for update + /// Fixed steps of 1/hz covered by this update's tick events; at most 8 + /// (no spiral of death). + pub fn steps(c: *Clock, in: *const Input, hz: f32) u32 + /// Variable dt: the seconds this update's ticks carry. + pub fn advance(c: *Clock, in: *const Input) f32 +}; +``` + +Both port batches wrote `steps60` by hand. With it, NoC examples that assume +one step per frame run at the book's speed on a 120 Hz display. p5 runs them +at double speed there. + +Host fix (about 10 lines, `Host.zig:243`): in `Host.update`, set `input.dt` +from the `tick` events being fed (their `x`), live and replayed alike. State in +`abi.zig` that `in.now` and `in.frame` are draw-only (or give `update` an +`Input` copy where `now` is recording-relative in both modes). Today a sketch +that integrates `in.dt` in `update` replays wrong, quietly. Same fix in +`sb/src/sketch/web.zig`'s driver. + +- Invariant: **restores** determinism of `update`. + +### P6. `sk.List(T, N)` for State, and element-wise migration of arrays of structs + +```zig +pub const Particle = struct { pos: sk.V2, vel: sk.V2, life: f32 = 1, hue: f32 = 0 }; // added `hue` live +pub const State = struct { particles: sk.List(Particle, 2048) = .{} }; +// update: +_ = s.particles.append(.{ .pos = origin, .vel = s.rng.onCircle() }); +var i: u32 = 0; +while (i < s.particles.len) { if (dead(s.particles.at(i))) s.particles.swapRemove(i) else i += 1; } +``` + +- `List` (sketch lib, about 60 lines): `items: [N]T = undefined, len: u32 = 0`; `view`, `slice`, `at`, `append → bool`, `swapRemove`, `orderedRemove`, `clear`. `view()` clamps `len` to `N`, in case a migration shrank the capacity. +- **The real problem:** `[N]Particle` is one leaf (`sb/src/abi.zig:558-560`, "arrays stay whole"), and `migrate` copies a leaf only when its hash and size match (`sb/src/host/memory.zig:95-110`). Add `hue` to Particle and on reload `items` resets to its default (`undefined`) while `len` (unchanged u32) is **kept**, so the sketch iterates garbage (coordinator, board). Changing the capacity does the same. That is exactly when you want to see the change on the live swarm. With element-wise migration a bare `[N]T` + `n: u32` is enough. `List` is then convenience only. +- Proposal: reflect `[N]struct` as per-field leaves `particles.items[].pos` with `count` and `stride` added to `abi.Field` (an extern on-disk struct, so bump the state-file header version). `migrate` then copies `min(old_count, new_count)` elements field by field. Console and probe learn the path `particles.items[3].pos`. +- Where: `sb/src/layout.zig` and `sb/src/host/memory.zig`, plus console and probe paths; about 200 lines. Web: nothing, since nothing persists there. Invariant: **extends** field-by-field migration. State stays plain data. + +### P7. `sk.V2` and `sk.v2`, plus `sk.map` + +```zig +pub const V2 = @Vector(2, f32); +pub const v2 = struct { + splat, length, lengthSq, dist, normalize, setLength, limit, heading, + fromAngle, rotate, dot, cross, perp, angleBetween, reflect, +}; +pub fn map(v: f32, from: [2]f32, to: [2]f32) f32 // and mapClamped +``` + +Zig has no scalar broadcast (`v * 2` must be `v * @as(V2, @splat(2))`; +see the coordinator's shader note), so `v2.scale(v, s)` and `v2.splat` carry +most of the weight. Use Zig names, and add a one-line PVector→v2 table in the docs (`mag` → +`length`, `setMag` → `setLength`). Lerp is already `tween.lerp`. Sketch lib, +about 80 lines. No invariant. + +### P8. Color: constructors and `mix`, never a mode + +```zig +f.clear(sk.hsv(0.6, 0.3, 0.1)); +pen.with(.{ .fill = .{ .h = s.hue, .s = 0.8, .v = 1 } }).circle(p, 6); // duck-typed HSV +const c = sk.color.mix(a, b, t, .oklab); // lerpColor, in a chosen space +``` + +`hsv`, `hsl`, `oklch` return `abi.Color`. Hue is in **turns** (0..1, wraps), +consistent with the existing 0..1 float channels. `shape.isColor` also +accepts `h/s/v[/a]` and `h/s/l[/a]` fields. Sketch lib, about 120 lines. No +invariant. Avoids Processing's mode-dependent meaning of `fill(a, b, c)`. + +### P9. Blend as a style field, emitted as a stateful command only on change + +```zig +const glow = pen.with(.{ .fill = sk.hsv(0.1, 0.6, 1).alpha(40), .blend = .add }); +for (s.sparks.view()) |sp| glow.circle(sp.pos, 6); +``` + +- (Revised: `screen` dropped. See "Relation to research-love". The modes are `{alpha, add, multiply}`.) +- `abi.Composite = enum { alpha, add, multiply }` and `Command.blend: Composite`. It is stateful like `clip` already is. The Frame emits it only when the Pen's blend differs from the last one emitted, and closes the triangle batch when it changes (Processing flushes on a blend change, `PGraphicsOpenGL.java:6212-6216`). +- Native: `SDL_SetRenderDrawBlendMode` (and texture blend for images): BLEND, ADD, MUL; screen through `SDL_ComposeCustomBlendMode(ONE, ONE_MINUS_SRC_COLOR, ADD, …)`, logged once where the fallback renderer refuses it. Web: `source-over`, `lighter`, `multiply`, `screen`. Reset to `alpha` before overlays, as clip is reset (`Host.zig:304`). About 30 lines native, 5 web. +- Not included: `replace`/`copy`, because canvas `copy` clears outside the shape; difference and exclusion, because SDL fixed-function blending cannot do them. A mode only one host can run breaks the "both hosts" invariant. + +### P10. Offscreen 2D targets (createGraphics) + +```zig +// Session +trail: sk.Image = .none, +drawn: u64 = 0, +// draw +if (ss.trail == .none) ss.trail = f.host.newTarget(960, 600); +if (f.in.jumped) ss.drawn = 0; // seek/load: start the layer over (research-love's Input.jumped) +if (ss.drawn != s.clock.ticks) { // accumulate only when State moved + ss.drawn = s.clock.ticks; + f.target(ss.trail, .{ .clear = null }); // keep last frame's pixels + pen.with(.{ .fill = sk.Color.white.alpha(12) }).rect(.{ .w = 960, .h = 600 }); // fade + for (s.movers.view()) |m| pen.circle(m.pos, 8); + f.target(.none, .{}); +} +f.image(ss.trail, .{ .w = 960, .h = 600 }, .{}); +``` + +- `Host.VTable.newTarget(w, h) Image` creates an `SDL_TEXTUREACCESS_TARGET` texture in `Images` (a streaming texture cannot also be a target). `Command.target: struct { image: Image, clear: ?Color }`, where `.none` means the canvas. **Native must go back to `self.offscreen` when headless** (`Host.zig:529-530`), not to null, and reset the target before overlays. Web: each target image gets its own canvas and context, and the module-level `ctx` is swapped. About 60 lines each. +- Invariant: a target's pixels are **Session** state, presentation only. They are not snapshotted, and after a seek they are wrong until they refill. The pattern above stops pause from repeating the accumulation; document that. Anything that must replay exactly belongs in State (a ring buffer of past positions). + +### P6b. Images under a transform (folded into P2, needs one ABI field) + +`Command.image` gains `quad: ?[3][2]f32 = null` (origin, right, down +corners). Native: `SDL_RenderTextureAffine` (`SDL_render.h:2337`), which +takes exactly those three points. Web: `ctx.setTransform` from the three +points, `drawImage`, then reset. About 15 lines each. Text keeps axis-aligned +cells: the Pen moves its origin only. + +### P11. Rect anchors as constructors (rectMode, ellipseMode) + +```zig +pen.rect(sk.shape.centered(p, .{ 40, 20 })); // rectMode(CENTER) +pen.rect(sk.shape.corners(a, b)); // rectMode(CORNERS) +``` + +Sketch lib, about 20 lines. A call means the same thing wherever it appears. + +### P12. `sk.fx`: a shadertoy pass and stock filters, built on GPU-as-data + +```zig +sk.fx.shade(f, ss.view, shaders.plasma_frag, Plasma{ .t = s.clock.seconds }); // fullscreen +sk.fx.filter(f, .{ .src = ss.trail, .dst = ss.soft, .op = .{ .blur = 4 } }); // filter(BLUR, 4) +``` + +Builds `abi.gpu.Pass` with a built-in attribute-less fullscreen vertex +shader. Filters (blur, threshold, invert, gray, posterize, and feedback, +which reads the previous frame) ship as sketchbook shaders, compiled once +into SPIR-V and WGSL. Needs P10 to filter 2D drawing. Sketch lib plus +shaders, about 250 lines. No ABI change. Live shader editing already works +(`zig build lib --watch` → new hash → new pipeline); nothing to copy from +`loadShader`. + +### P13. Deterministic frame export from a recording (saveFrames done right) + +``` +> export 2 out/frames 60 # recording 2 → out/frames/0000.png …, at its recorded ticks +# in a .script: export 2 out/frames +``` + +Host-only (native): restore the recording's snapshot, then for each recorded +tick run update, draw, and the existing screenshot path +(`Host.zig:319-323`), with an optional `--scale` to render the canvas at N×. +It renders offline and identically every time, at any length. p5's +`saveFrames` is wall-clock `setInterval` and capped at 15 s / 22 fps +(`image.js:631-660`). About 100 lines. Not a Command, so the "both hosts" +rule does not apply. The web has no export. + +### P14. Input sugar (pmouse, clicked) + +```zig +if (in.clicked(.left)) s.target = in.mouse(); // mouse_down in this update's events +s.trail_delta = in.mouse() - in.prevMouse(); // pmouseX / pmouseY +``` + +`Input.prev_mouse_x/y` is set by the host at the start of `update`, before +`track` (`Host.zig:245`; the same in the web driver). It is derived from +events only, so it replays. `mouse()` returns `@Vector(2, f32)`; `clicked` +and `unclicked` mirror `pressed`. About 30 lines in `abi.zig`, 2 lines per +host. + +(Smaller: `f.textWidth(bytes, scale)` = codepoints × 8 × scale, so text can +be centered without an align mode.) + +### Build options: where Processing's global modes go + +Processing and p5 put these choices in mutable runtime globals +(`size()`/`settings()`, `colorMode`, `noiseDetail`, renderer `P2D`/`WEBGL`, +`smooth()`, `pixelDensity`). The owner's rule is that they are per-app build +decisions. Mechanism: `sb.app(.{ ..., .options = .{ ... } })` writes a +generated `sketch_options` module that the sketch lib imports, so each knob +is a comptime constant, the same on native and web. No runtime state, and a +`-D` flag can override it. + +```zig +const app = sb.app(.{ + .name = "flow_field", + .root_source_file = b.path("src/flow_field.zig"), + .options = .{ + .noise = .processing, // .perlin (default) | .processing | .p5: what sk.noise.get(x, y, z) is + .noise_seed = 0, // for the classic tables (comptime, 16 KiB rodata) + .hue = .turns, // .turns | .degrees: what `.h` means in duck-typed colors + .antialias = .fringe, // .none (pixel art) | .fringe: whether the Pen emits AA fringes + .canvas = .{ 640, 360 }, // overrides `pub const width/height` (or -Dcanvas=640x360) + }, +}); +``` + +- **Noise flavour** replaces `Classic(.processing, 0)` from P4: `sk.noise.get` is fixed at build time. A port sets `.noise = .processing` once and gets the book's pictures. `perlin`/`fbm` with an explicit seed stay available. +- **Hue unit / colour range** replaces `colorMode`. It is fixed per app, so `.{ .h = 200 }` can never mean two things in one program. +- **Renderer / AA** replaces `P2D`/`JAVA2D`/`smooth()`: whether the Pen emits fringes, and later which native backend runs `shape` (SDL_RenderGeometry or an MSAA SDL_GPU pipeline). +- **Not build options:** seeds of the simulation (they are State: `rng: sk.Rng = .init(1)`), step rate (a `Clock.steps(in, hz)` argument), and pen style (a value in `draw`). +- Cost: about 40 lines in `sb/build.zig`, nothing in the hosts. Invariant: none. These are compile-time constants. + +--- + +## 3. Do not copy + +1. **Implicit "current renderer" style and matrix state** (`fill()`, `stroke()`, `translate()` mutating a global). In p5 it leaks across frames, because `redraw` resets only the matrix (`structure.js:342`); a pop on an empty stack is silent in p5 (`p5.Renderer.js:151`) and throws in Processing (`PGraphics.java:6294`). The Pen value does all of this with Zig's own scoping. +2. **Modes that change what a call means**: `rectMode`, `ellipseMode`, `imageMode`, `colorMode`. Each is action at a distance. Use constructors and explicit types. +3. **Unseeded or hidden randomness**: Processing's lazy unseeded `Random` (`PApplet.java:4707`), p5's `Math.random` fallback (`random.js:278-282`), `random2D` ignoring the seed (`PVector.java:244`, `p5.Vector.js:3150`), the module-global noise table and gaussian spare (`noise.js:31`, `random.js:18`). In `update` these break replay. In `draw` they make a paused sketch flicker and a replay look different. Every generator is a value in State, or a pure function of a seed you pass. +4. **Not calling `background()` to keep the previous frame.** The host clears and draws again on pause and seek (`Host.zig:285-287`), so accumulation would double on pause and be wrong after a seek. Use a ring buffer in State, or an explicit target (P10) under the "only when State moved" rule. +5. **Event callbacks that mutate globals at arbitrary times**: p5 at DOM time (`keyboard.js:606-623`), Processing after draw (`PApplet.java:2112`). The ordered, recorded `in.events` is the right model. +6. **Wall-clock time in simulation**: `millis()` (`PApplet.java:2887`), rAF `deltaTime` (`main.js:331`), `frameRate(fps)` as the physics rate. Simulation time comes from recorded ticks through `Clock`. (Today's `in.dt`/`in.now` in `update` break this quietly: P5.) +7. **Shaders loaded by path at runtime, with uniforms set by string name**: Processing's HashMap (`PShaderOpenGL.java:742`), p5 ignoring a mistyped name (`p5.Shader.js:1147-1150`). Comptime std140 structs plus build-time compilation catch the typo, and the web host would need naga in the browser. +8. **p5.strands and `modify(hooks)`** (string-hooked shader patching, `p5.Shader.js:425`): a lot of machinery for what an `#include` and a GLSL function already do. +9. **`noLoop` / `loop` / `redraw`**: draw runs every frame and is cheap. A "static" sketch is State that stops changing. A redraw switch would only add a mode. +10. **Variadic overloads** (`fill(gray)`, `fill(r, g, b)`, `random(array)`, `color(...)`): use one signature per function, with duck-typed arguments checked at comptime, as `shape.zig` already does. +11. **One GPU draw per immediate shape** (`p5.Renderer3D.js:528-547`): batch in the Frame instead (P1). +12. **Retained `PShape`/`createShape` trees with mutable children**: retained geometry that needs it is a `Buffer` (`host.newBuffer` and `f.upload`), which already exists and is data. +13. **The `abs()` mirror in classic noise** as the default (`PApplet.java:4937`): keep it only behind `Classic`, for porting. +14. **`saveFrame` as a draw-time side effect**: replays and seeks would fire it again. Export is a host tool over recordings (P13). + +--- + +## Ranking + +1. P1 `.triangles` + Frame tessellation and batching +2. P2 `Pen` value (style + affine; push/pop is a `const`) +3. P5 `Clock`, and fix `in.dt`/`in.now` in `update` (a correctness bug today) +4. P3 `Rng` in State (pinned PCG32), plus `rand.at` keyed randomness +5. P6 `List(T, N)` + element-wise migration of struct arrays +6. P4 `noise` (seeded, pure, GLSL twin, `Classic` for parity) +7. P7 `V2`/`v2` + `map` +8. P8 `hsv`/`oklch`/`mix`, duck-typed HSV +9. P10 offscreen 2D targets (unlocks trails and P12) +10. P9 blend modes both hosts can run ({alpha, add, multiply}) + build options for noise, hue and AA + +Next after these: P13 export, P6b affine images, P12 fx, P14 input sugar, P11 anchors. |
