summaryrefslogtreecommitdiff
path: root/examples/noc/notes/friction-b.md
blob: 8d5d4309226a2f64232f43eca4d95baa282b39fa (plain) (blame)
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
# Friction log, batch B (porter-b)

Six Nature of Code examples ported to sketchbook as it stands, to measure
the API, not to make nice ports. Each port runs headless under its script
(`zig build e2e`), and I compared each screenshot with what the Processing
sketch draws. All six match: same canvas, dynamics and look, except for
anti-aliasing details.

Line counts are code lines only (no blanks or comments). Processing counts
every `.pde` file in the example. Port counts are the sketch file only.
Everything the ports share lives in `src/helpers_b.zig`: **177 code lines**,
and porter-a reuses its Vec ops, Rng and Pen.

| sketch | Processing | port | + helpers used |
| --- | ---: | ---: | --- |
| the_wave | 18 | 36 | Pen, Canvas, frames60 |
| pendulum | 70 | 63 | Pen, Canvas, frames60, Vec ops |
| system_of_systems | 68 | 73 | Pen, Canvas, frames60, List, Rng |
| flow_field | 133 | 110 | Pen, Canvas, frames60, Noise, Rng, Vec ops |
| flocking | 165 | 118 | Pen, Canvas, frames60, List, Rng, Vec ops |
| wolfram_ca | 38 | 48 | frames60 (draws with `f.fill` only) |

The ports are about as long as the originals *once the helpers exist*. The
cost is in the helpers (177 lines, the same again in porter-a's file) and in
a handful of rules that are easy to get wrong without any error (the
"silent traps" below).

---

## Cross-cutting friction (shows up in every port)

### C1. No shapes: circle, line, polygon, stroke, alpha and transforms all go through `vector`

`Frame` draws axis-aligned filled rects, images and 8px text, and nothing
else. Every Processing primitive these sketches use (`circle`, `line`,
`beginShape/vertex/endShape(CLOSE)`, `stroke`, `strokeWeight`, `fill(g, a)`,
`push/translate/rotate/pop`) needs the vector module. Getting there takes:

1. A `vector` import in the project's build.zig, which is not there by
   default (`sb.app(.{ ..., .imports = &.{.{ .name = "vector", .module =
   sb.modules.vector }} })`). Porter-a and I both made this edit.
2. A `vector.Drawing.Builder` in `f.scratch`, a `vector.Renderer(.cpu|.gpu)`
   kept in Session and built lazily on first draw, a `Drawing.Style` per
   shape, then `finish` → `begin` → `draw` → `present` in that order.
3. An error union on every shape call inside a `void` draw. Every port
   ends up with a `draw` that only calls `paint` and catches its error:
   ```zig
   pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
       paint(s, ss, f) catch |err| f.host.print("draw: {t}", .{err});
   }
   ```

What I wrote (helpers_b.zig `Pen` + `Canvas`, ~50 lines) brings a sketch
back to Processing's level:
```zig
var pen = ss.canvas.begin(f);
pen.stroke = b.gray(0, 255);
pen.weight = 2;
pen.fill = b.gray(127, 127);
try pen.circle(x, y, 48);
pen.transform = b.Affine.translate(p[0], p[1]).mul(.rotate(b.heading(v)));
try pen.polygon(&.{ .{ 8, 0 }, .{ -8, -4 }, .{ -8, 4 } });
try ss.canvas.show(f, &pen, width, height, b.gray(255, 255));
```
**Wish:** a `sk.Pen`-like value in the sketch library: style fields, an
affine, and shape methods that add triangles to scratch. The host should
need only one new command (a triangle shape, as research-love and
research-zig propose), with no Session renderer and no Builder ceremony.
Out-of-memory in scratch should drop the shape and log once, as `f.emit`
already does, so shape calls do not return errors.

### C2. Silent trap: `update` gets batches of ticks, but the input state it sees is from the end of the batch

When a recording plays or a seek happens, `Timeline.tick`/`seekCount` feed many frames'
events to one `update` (Host.zig:229, timeline.zig:148). `in.mouse_x`,
`in.buttons`, `in.held()` and `in.pressed()` describe the end of the batch.
A port that does Processing's obvious thing:
```zig
pub fn update(s: *State, in: *const sk.Input) void {
    step(s);                                  // once per update call
    if (s.dragging) s.angle = angleTo(in.mouse_x, in.mouse_y);
}
```
works live and in every script, and is wrong after a seek: it steps once
for many frames, and every replayed frame sees the final pointer. A
correct port loops over events, steps per tick, and keeps its own copy of
the pointer and button state in State:
```zig
for (in.events) |e| switch (e.kind) {
    .mouse_move => s.mouse = .{ e.x, e.y },        // pendulum.zig
    .mouse_down => s.pressed = true,               // flocking.zig (mouseDragged)
    .mouse_up, .cancel => s.pressed = false,
    .tick => for (0..b.frames60(&s.clock, e)) |_| step(s),
    else => {},
};
```
**Wish:** (a) an iterator `in.frames()` that yields each tick with the
events that came before it and the pointer and buttons as of that tick, or
at least (b) the held buttons on mouse events (`Event` has x/y but no
button mask), and `pressed()`/`held()` variants that take an event index.
Better still, make the end-of-batch fields unreachable from `update`, the
way `update(*Session)` is already a compile error.

### C3. Frame rate: per tick or 60 Hz?

Processing calls `draw()` 60 times a second. Stepping once per tick runs
the simulation 2.4× faster on a 144 Hz display. I started with one step
per tick and then switched to porter-a's idea, a clock in State that
accumulates `tick.x` (dt). I wrote it per event (`frames60(clock, e)`) and
not per update (`steps60(clock, in)`), so that pointer events still fall
between the frames they came between (C2). The first tick has dt = 0, so
60 script frames make 59 steps. Scripts now `expect frames 59`, which reads
as a bug until you know why.

**Wish:** `sk.Clock` (plain data, in State) with `steps(e) -> u32` at a
fixed rate. Also, the first tick should carry a nominal dt, or the scripts
should document that it does not.

### C4. Dynamic collections in State

A particle system or a flock needs a list whose length changes. State
cannot hold pointers, and Zig 0.15+ removed `std.BoundedArray`. I wrote
`List(T, cap)` (`items: [cap]T`, `len: u32`, `append` → bool,
`orderedRemove`, `slice`/`view`, 25 lines). The costs:

- **Capacity is a guess the original never had to make.** Flocking has
  2048 boids, and `mouseDragged` silently stops adding past that.
  System-of-systems has 32 emitters × 136 particles (one particle a frame
  living 128 frames). `update` cannot log, so a full list cannot say so.
- **Size.** In a Debug build `@Vector(2, f32)` is 16 B (research-zig), so a
  particle is 48 B. The system_of_systems State is 210 KB, and its state
  file is **1.77 MB** (live + 7 snapshot slots), most of it empty capacity.
  The flocking state file is 622 KB. A `Vec2 = extern struct { x, y }`
  would halve these.
- **Migration hazard** (verified by research-zig): adding a field to
  `Particle` resets the whole `items` leaf to its default (`undefined`) and
  keeps `len`. Shrinking `cap` keeps a `len` larger than the new capacity.
  So editing the element type during a hot reload leaves garbage particles.
  Processing has no equivalent, but this is the main promise of hot reload.
- Ordered removal while iterating backwards works as in Java
  (`Emitter.run`), but you have to remember to index rather than iterate a
  slice, because `orderedRemove` moves the elements after `i`.

**Wish:** `sk.Bounded(T, cap)` in the sketch library with `append` →
`error.OutOfMemory` (like `ArrayList.appendBounded`), `items()` clamped to
`cap`, and swap/ordered remove. Arrays should also migrate element by
element (research-zig's spec), so changing the element type during a reload
keeps the elements.

### C5. Randomness and noise

This one is easier than expected. `std.Random.DefaultPrng` (Xoshiro256) is
plain data (`s: [4]u64`), sits in State, migrates, and replays bit for bit.
`random(lo, hi)` is one line. But:

- A declared default cannot be random, so Processing's `setup()` becomes
  `pub fn init(s: *State)` (flow_field, flocking). That is fine, but it
  means a field's default is `undefined` until `init` runs
  (`vehicles: [120]Vehicle = undefined`).
- There is no `noise()`. I wrote a 4-octave value noise in Processing's
  style (40 lines), with a 16 KB table built from a seed. Only the seed
  lives in State, and `flow_field` rebuilds the table on each click
  (`noiseSeed(random(10000))`). Porter-a's is Processing-exact, with the
  table built at comptime. See the comparison below.

**Wish:** `sk.Rng` (pinned algorithm, `float(lo, hi)`, `int`, `normal`) and
a pure `sk.noise(seed, x, y, z)` (hash-based, no table, with a GLSL twin).

### C6. Update-then-draw versus Processing's interleaved update-and-show

Processing objects update and draw in one pass (`particle.run()` does
`update(); show();`), and `draw()` can draw *before* it mutates. Sketchbook
runs every update first and then draws from State, so the "same" frame
differs by one step in several places:

- the_wave: `angle = startAngle; startAngle += 0.02; draw(angle)`. The port
  draws `s.start_angle - 0.02`.
- system_of_systems: the particle added at the end of the frame is not
  shown until the next frame, and particles are shown newest first, so the
  port's draw loop starts at `len - 2` and runs backwards.
- pendulum: Processing does `update(); show(); drag();`, so a dragged bob
  is drawn one frame late. The port shows it at once.

None of this can be seen at 60 fps, but each one is a small puzzle when you
aim for an exact port. No API change is needed. It is worth one paragraph
in the README ("draw sees the state after this frame's update").

### C7. Testing and measuring

- `expect` compares formatted text exactly. Floats are therefore unusable
  (pendulum cannot assert an angle), and `@Vector` fields print as
  `<16 bytes>`. Arrays cannot be indexed
  (`emitters.items[0].particles.len`). Every port gained an integer field
  only so a script could look at it (`frames`, `fields_made`, `generation`)
  or asserted only on list lengths.
- Headless runs discard `host.log` (Host.zig:558), and `update` gets no
  clock. To time flocking I added a temporary `host.env` check to `draw`,
  rebuilt, timed whole script runs with `date` and subtracted a baseline
  run. **Wish:** `expect FIELD ~VALUE ±TOL`, indexed paths, logs on stderr
  under `--headless` (or `--log`), and per-phase timings (update, draw,
  present) from the host, like `--profile-gpu`.
- `zig build e2e` is flaky under load. A random 2–8 of the 12 runs fail
  with `LeakedSdlMemory` (SDL Vulkan allocations) and never with a failed
  `expect`. My scripts passed 6/6 sequentially and 8/8 in a parallel batch.
  Also, two concurrent `zig build e2e` runs share state paths and break each
  other (porter-a).

### C8. Small things

- `align` is a keyword, so `boid.align(boids)` became `alignment`.
- `@Vector` math has no scalar broadcast: `v * @as(Vec, @splat(s))`. I
  wrote `scale(v, s)`, plus `mag`, `setMag`, `limit`, `normalize`,
  `heading`, `fromAngle` and `dist` (30 lines). On the other hand,
  `p.position += p.velocity` works on vectors without helpers, which is
  nicer than PVector's `add`.
- `std.math.lerp(0, height, (@sin(a) + 1) / 2)` stands in for `map()`.
- Colours: `vector.Drawing.Color` is straight RGBA in 0..1 (`@Vector(4,
  f32)`), but `Frame.fill` takes `0xRRGGBB` or `r,g,b` structs. That is two
  colour vocabularies in one sketch. I wrote `gray(v, a)` in Processing's
  0..255 units.

---

## Per example

### the_wave (Example 3.9): 18 → 36 lines

- Translucent stroked circles (`fill(127, 127); stroke(0);
  strokeWeight(2); circle(x, y, 48)`) need C1. With the Pen it is the same
  four lines.
- The draw-before-mutate offset (C6): `var angle = s.start_angle - 0.02;`.
- `map(sin(a), -1, 1, 0, height)` became `std.math.lerp(0, height, (@sin(angle) + 1) / 2)`.
- The extra lines are module boilerplate: `name`/`width`/`height`, State,
  Session holding the Canvas, the `draw`/`paint` split (C1), and the 60 Hz
  loop.
- **Wish:** `f.pen()` returning a Pen that draws straight into the frame.

### pendulum (Example 3.11): 70 → 63 lines

- Mouse press, release and drag are handled per event, with the pointer
  copied into State (C2). Processing's `mousePressed()`/`mouseReleased()`
  callbacks map well onto `switch (e.kind)`, which reads better than
  Processing's three global callbacks.
- `line` and a stroked `circle` need C1.
- The hit test needs the bob position. Processing caches it in `show()`. I
  derive it from the angle (`State.bob()`), so draw and update agree
  without storing it.
- The script can only assert `dragging` (bool), not where the bob went
  (C7). I checked the swing by looking at the screenshot.
- **Wish:** `in.frames()` (C2). With it, the State would not need a
  `mouse` field.

### system_of_systems (Example 4.4): 68 → 73 lines

- This is the dynamic-collection test (C4): `ArrayList<Emitter>` of
  `ArrayList<Particle>` became `List(Emitter, 32)` of
  `List(Particle, 136)`. Shape and code read the same as Java, but the
  State is 210 KB (1.77 MB on disk with 8 slots), and the 33rd click does
  nothing, silently.
- Per-particle alpha on fill and stroke (`stroke(0, lifespan)`) works
  through `Drawing.Style` colours. `lifespan` goes negative before removal,
  so the alpha needs a clamp (in `gray`).
- The draw order matches Processing: newest first, and the particle just
  added is not shown yet (C6).
- The script asserts `emitters.len` but cannot reach a particle count
  (C7).
- **Wish:** `sk.Bounded`, migration by element, and a way for `update` to
  report "capacity reached" (a counter in State works, but it is one more
  field per list).

### flow_field (Example 5.4): 133 → 110 lines

- `noise()` and `noiseSeed()` are missing (C5). The noise table is rebuilt
  from a seed on each click.
- `PVector[][] field` became `[cols][rows]f32` of angles, 2.3 KB, which is
  pleasant: a 2D array is plain State, and `for (&ff.field) |*column| for
  (column) |*angle|` reads well.
- The vehicles' rotated triangles are where `Pen.transform` shines:
  `translate(x, y).mul(.rotate(theta))` replaces `push/translate/rotate/pop`
  with a value, so nothing can be left pushed.
- Acceleration lasts a single step in the original (`acc.mult(0)`), so it
  is a local, not State: `v.velocity = limit(v.velocity + steer, maxspeed)`.
- `key == ' '` became `e.kind == .key_down and e.code ==
  @backingInt(sk.Key.space) and e.flags & sk.Event.repeat == 0`. That is
  correct, but long. `in.pressed(.space)` exists but is per batch (C2).
- **Wish:** `e.isPress(.space)` on `Event` (key down, no repeat), `sk.noise`.

### flocking (Example 5.11): 165 → 118 lines

- The flock is a `List(Boid, 2048)` (C4). `mouseDragged` means "move events
  while the button is down", so `pressed` is tracked in State (C2).
- Processing updates boids in place, one after another, so later boids see
  earlier boids' new positions. The port keeps that:
  `for (boids) |*boid| boid.run(boids)`, where `boids` is the slice being
  mutated (Zig allows the alias).
- **Frame time** (headless, 600 frames at a constant count, minus a ramp-up
  baseline, on an RTX 3050 shared with other agents' builds, so ±30 %):

  | boids, build | total / frame | update | draw (CPU vector) | draw (GPU vector, helpers_a `showGpu`) |
  | --- | ---: | ---: | ---: | ---: |
  | 120, Debug | ~3–4 ms | — | — | ~8.7 ms total |
  | 1000, Debug | 37–76 ms | ~18 ms | ~20–58 ms | ~56 ms total |
  | 1000, ReleaseFast | 8.7–11.6 ms | ~4.6 ms | ~4–7 ms | ~9.1 ms total |

  Update (O(n²), three neighbour loops) is fine. Drawing 1000 triangles
  costs as much as the whole simulation, because each one is flattened,
  stroked into polygons and rasterized one at a time (CPU), or turned into
  two stencil-and-cover draws (GPU). The 921 KB `f.pixels` upload per
  frame is small next to that. e2e runs Debug, where 1000 boids is about
  15 fps.
- **Wish:** a batched triangle command. Boids are 3 vertices each, and a
  path renderer with exact coverage is the wrong tool for them.

### wolfram_ca (Example 7.1): 38 → 48 lines

- The only port that needs nothing beyond `f.fill`: black squares on
  white.
- Processing never clears: `background(255)` runs once in `setup()`, and
  each `draw()` paints one more row. Sketchbook draws every frame from
  State, so State keeps the whole history, `[33][64]u1` (2 KB). Here that
  is *better*. It is small, it replays and seeks for free, and it removes
  the need for a persistent canvas. (Porter-a's noise_walker shows the case
  where it is not small.)
- `noLoop()` becomes "stop stepping when `generation == max_rows`". It is
  explicit and fine.
- The stroke of `square()` adds half a pixel all round, drawn as a rect
  inflated by 0.5. A rect API with a stroke would remove that.
- The rule lookup through a string (`Integer.parseInt("" + a + b + c, 2)`)
  became `@as(u3, left) << 2 | @as(u3, me) << 1 | right`, which reads
  better.
- **Wish:** none needed. Optionally `f.stroke(rect, color, width)`.

---

## helpers_a vs helpers_b

Porter-a reused my Vec ops, `Rng` and `Pen`, and added `steps60`, an exact
`noise()`, `showGpu` and `Trail`.

| piece | helpers_a | helpers_b | better, and why |
| --- | --- | --- | --- |
| frame stepping | `steps60(clock, in) u32`, per update, f64 clock | `frames60(clock, e) u32`, per tick event, f32 clock | **B's shape**, A's idea. Per event, the pointer events in a replayed batch stay between the right frames (C2); per update, they all land before the first frame. Both fix the 144 Hz speed-up. |
| noise | Processing-exact: java.util.Random table at comptime, 0 B in State, 3D | Xoshiro table built from a seed in State at call time, 2D, 16 KB per rebuild | **A** for fidelity and cost. **B** only where the seed changes at runtime (flow_field's click). Both lose to a hash noise `noise(seed, x, y, z)`, which needs no table and can have a GLSL twin. |
| redrawn layer | `showGpu`: GPU vector renderer (8× MSAA), transparent over `f.clear` | `Canvas`: CPU vector renderer, `f.pixels` upload, background inside | **Neither clearly.** Measured on flocking (table above), the GPU path is no faster: slower in Debug (56 vs ~37 ms at 1000 boids), similar in ReleaseFast (9.1 vs 8.7–11.6 ms total), because tessellation is on the CPU either way and the GPU path issues two draws per shape. The CPU one is simpler, runs anywhere (wasm too: flocking's web build works unchanged), and is pixel-identical here (GPU screenshot = CPU screenshot). GPU MSAA edges look slightly softer. Choosing at runtime means duplicating the call site for two renderer types (vecanim does this). |
| persistent layer | `Trail`: CPU renderer never cleared, plus a "steps drawn" counter to repaint after a seek | none (wolfram keeps its history in State instead) | Different problems. State history is right when it is small (wolfram, 2 KB). `Trail` is needed when it is not, and its counter guess is what `Input.jumped` would replace. A GPU trail is impossible today: an MSAA pass always clears (gpu.zig:213). |
| bounded list | none (fixed arrays) | `List(T, cap)` | Neither is enough until arrays migrate element by element (C4). |

What the two files show together: both porters, working independently,
wrote the same ~200 lines (Vec ops, Rng, noise, Pen, a stepping clock).
That is the size of the missing layer.

---

## Easier than in Processing

- **Determinism for free** once the RNG is in State. The same script gives
  pixel-identical screenshots run after run, and on CPU and GPU renderers.
  A seek or a replay re-runs flocking exactly, which Processing cannot do.
- **Scripts as tests.** `--fresh` + `click`/`down`/`move`/`key` + `expect` +
  `screenshot` gave every port a regression test in 5–15 lines. The
  pendulum drag, the flocking drag-add count and the flow-field toggle are
  all checked without a window.
- **Transforms as values.** `pen.transform = translate(..).mul(.rotate(..))`
  cannot leak a `push()` without its `pop()`.
- **Event switch over callbacks.** `switch (e.kind)` in `update` keeps
  `mousePressed`/`keyPressed`/`mouseDragged` together, in order, and
  replayable.
- **2D arrays and fixed-size grids** (flow field, CA history) are plain
  State, inspectable with the probe, and they hot-reload.
- **The web build worked unchanged** with the CPU renderer (1 MB wasm).

---

## Ranked: the most impactful gaps across batch B

1. **No shape drawing in `Frame` (C1).** Five of six ports needed the
   vector module: a build.zig import, a Builder, a Renderer in Session, a
   `try` on every shape, and an explicit present. ~70 helper lines, and
   1000 triangles cost as much as the whole flocking simulation. Wanted: a
   Pen layer in the sketch library over one triangle-batch command.
2. **Batched ticks with end-of-batch input (C2).** A silent trap: ports
   that read `in.mouse_x` or step once per `update` pass every live test
   and every script, and break only on seek or replay. Wanted:
   `in.frames()` per-tick iteration, buttons on mouse events, and the
   end-of-batch fields kept out of `update`.
3. **Dynamic collections (C4).** No bounded list type, guessed capacities,
   silent drops, 1.77 MB state files from empty capacity, and garbage after
   a reload that changes the element type. Wanted: `sk.Bounded(T, cap)`
   plus array migration by element.
4. **No fixed-rate clock (C3).** Stepping per tick makes the simulation's
   speed depend on the display. Both porters wrote the same accumulator.
   Wanted: `sk.Clock` in State.
5. **Scripts cannot see floats, vectors or array elements, and headless
   runs hide logs and timings (C7).** Every port grew observability-only
   fields, and profiling meant external stopwatches. Wanted: tolerant
   `expect`, indexed paths, stderr logs and per-phase timing.
6. **No random/noise in the library (C5).** The Rng in State works well.
   Noise is 40–60 lines that every noise sketch rewrites. Wanted: `sk.Rng`
   and a pure `sk.noise(seed, x, y, z)`.
7. **Vector math vocabulary (C8).** `@Vector` has no scalar broadcast, no
   `limit`/`setMag`/`heading`, and it is 16 B in Debug State. Wanted: small
   `sk.v2` functions, and an extern `Vec2` for storage.
8. **Two colour vocabularies (C8).** `0xRRGGBB` for `Frame`, straight 0..1
   `@Vector(4, f32)` for `vector`. Wanted: one `sk.Color` that both accept,
   with Processing-style `gray(v, a)`/`rgb(r, g, b, a)` constructors.

Not a gap, but worth documenting: update-then-draw shifts Processing ports
by one step in places (C6), and the first tick's dt is 0 (C3).