1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
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.
|