summaryrefslogtreecommitdiff
path: root/examples/noc/notes/friction-a.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/friction-a.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz
sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/friction-a.md')
-rw-r--r--examples/noc/notes/friction-a.md369
1 files changed, 369 insertions, 0 deletions
diff --git a/examples/noc/notes/friction-a.md b/examples/noc/notes/friction-a.md
new file mode 100644
index 0000000..83bafaa
--- /dev/null
+++ b/examples/noc/notes/friction-a.md
@@ -0,0 +1,369 @@
+# Friction log, batch A (porter-a)
+
+Six Nature of Code examples, ported from Processing to sketchbook.
+
+LOC is counted as non-blank, non-comment lines. "+helpers" is the share of
+`src/helpers_a.zig` (128 code lines) and `src/helpers_b.zig` that the port uses.
+All six run in `zig build e2e`, and I checked every screenshot by eye.
+
+| sketch | original | port | uses |
+|---|---|---|---|
+| random_walk | 33 | 45 | steps60 |
+| noise_walker | 30 | 44 | steps60, noise, map, Trail, B's Pen |
+| bouncing_ball | 21 | 36 | steps60, showGpu, B's Pen |
+| accel_to_mouse | 36 | 35 | steps60, showGpu, B's Pen + Vec ops |
+| fluid_resistance | 96 | 86 | steps60, showGpu, B's Pen + Vec ops + Rng |
+| angular_forces | 82 | 83 | steps60, showGpu, B's Pen + Vec ops + Rng |
+
+Once the helpers exist, the ports are about as long as the originals, and
+the physics code is shorter: `s.velocity += s.acceleration` beats
+`velocity.add(acceleration)`. The cost is the roughly 250 helper lines across
+A and B, which every new sketchbook user would have to write again. Without
+them, each port would need its own ~40-line circle/stroke pipeline.
+
+---
+
+## 1. random_walk (Example 0.1)
+
+**Processing:** `background(255)` once in `setup()`, then `point(x, y)` each
+frame on a canvas that is never cleared.
+
+**Friction**
+
+- **No persistent canvas.** The host's 2D canvas is redrawn from scratch every
+ frame, and leaving out `f.clear` gives undefined swapchain contents. The
+ trail has to live somewhere:
+ - Keeping it in Session does not survive a replay or a seek, because Session
+ is not snapshotted.
+ - Recomputing it in draw would mean replaying the PRNG from the start every
+ frame.
+ - What I did: keep the trail in **State** as a bitset, and paint it into an
+ image every frame.
+ ```zig
+ trail: std.StaticBitSet(width * height) = .empty, // 28.8 KB of State
+ ...
+ const rgba = f.scratch.alloc([4]u8, width * height) catch return;
+ @memset(rgba, .{ 255, 255, 255, 255 });
+ var it = s.trail.iterator(.{});
+ while (it.next()) |i| rgba[i] = .{ 0, 0, 0, 255 };
+ f.pixels(ss.image, width, height, std.mem.sliceAsBytes(rgba), .{});
+ f.image(ss.image, .{ .x = 0, .y = 0, .w = width, .h = height }, .{});
+ ```
+ This is correct under replay, but only because a walk's history happens to
+ fit in a bitmap. Every frame uploads a 920 KB texture to show one new pixel.
+- **No `point()`, and no 1-px primitive except `f.fill` with a 1x1 rect.** With
+ no persistent canvas to draw on, it would not have helped anyway.
+- **Debug build performance.** My first draw loop was
+ `for (rgba, 0..) |*px, i| px.* = if (s.trail.isSet(i)) ...`, over 230 k
+ pixels. It took about **0.5 s per frame** in the default Debug build, so the
+ 600-frame e2e looked hung. I lost about 20 minutes to this, partly because
+ `ptrace` attach is blocked here, so the only way to get a stack was to start
+ the program under gdb and interrupt it. Processing users never meet this
+ kind of trap.
+- **The PRNG must live in State.** `rng: std.Random.DefaultPrng = .init(1)` was
+ easy, and calling `s.rng.random().uintLessThan(u8, 4)` worked. My first try,
+ `uintLessThan(u2, 4)`, does not compile, because 4 does not fit in a `u2`.
+ Small, but it is the kind of thing `floor(random(4))` never asks you.
+- **The 60 Hz draw loop is my job.** `update` runs once per display frame,
+ which may be 144 Hz. Processing runs 60 steps a second. I wrote `steps60`,
+ which accumulates the tick dt in a `clock: f64` State field. Every port
+ needs it:
+ ```zig
+ for (0..h.steps60(&s.clock, in)) |_| { ... one Processing frame ... }
+ ```
+ **Gotcha:** the first frame's tick has dt = 0, so 600 script frames make 599
+ steps. The script expects `steps 599`.
+
+**Wished-for API:** `f.layer(id, .{ .keep = true })` or `Frame.target(img)`:
+an offscreen image that the frame draws into and that keeps its contents,
+plus `Input.jumped` (true after a load, seek or reload) to signal "repaint
+from state". Also `sk.FixedStep(60)`, a plain-data clock in State with
+`steps(in)`.
+
+## 2. noise_walker (Example 0.6)
+
+**Processing:** `noise(t)`, `map()`, and `circle()` with fill and stroke, with
+no `background()` in draw, so the circles pile up into a trail.
+
+**Friction**
+
+- **No `noise()`.** I ported Processing's `PApplet.noise` exactly: 4 octaves,
+ 0.5 falloff, and the half-degree cos table. I fill its 4096-entry table at
+ **comptime** with `java.util.Random`'s LCG, so the values are what
+ `noiseSeed(0)` would give:
+ ```zig
+ const perlin: [4096]f32 = blk: { @setEvalBranchQuota(100_000); ... seed = (seed *% 0x5DEECE66D +% 0xB) & mask; ... };
+ ```
+ That is 60 lines. B's `Noise` fills the table with Xoshiro at
+ `Noise.init(seed)`, and the State keeps only the seed, so the 16 KB table is
+ rebuilt each time it is needed. B also drops z. **Mine is better for
+ fidelity and cost:** the values match Processing and nothing is rebuilt.
+ **B's is better if the seed must change at runtime** (`noiseSeed(n)`). A
+ library `sk.noise` should be a pure function of `(seed, x, y, z)`, using
+ hashing rather than a table, so it is stateless and can have a GLSL twin.
+- **No `map()`.** It is a one-liner, but every port writes it.
+- **Circles with stroke need the vector module.** That means adding a
+ `vector` import in build.zig (porter-b and I both made the same edit at the
+ same moment), a `Drawing.Builder`, a `Renderer` kept in Session, and an
+ error union on every builder call inside a `void` draw. B's `Pen` covers
+ this.
+- **The persistent canvas, again, and worse this time.** The trail cannot be
+ rebuilt from a bitmap. It could be recomputed from the frame number, but
+ only by replaying the whole walk. I wrote `Trail`, a CPU renderer in
+ Session that is never cleared, plus a **shadow walker** in Session that
+ draw steps forward to paint only the new circles:
+ ```zig
+ const r = ss.trail.begin(f, width, height, s.frame_count, hb.gray(255, 255)) orelse return;
+ if (ss.trail.drawn == 0) ss.shadow = .{};
+ for (ss.trail.drawn..s.frame_count) |_| { ss.shadow.step(); pen.circle(ss.shadow.x, ss.shadow.y, 48) catch break; }
+ ss.trail.end(f, &pen, s.frame_count);
+ ```
+ So draw re-runs the simulation, and `frame_count < drawn` is my guess at
+ whether the user went back in time. It would miss a jump to a different
+ timeline at a higher frame count, such as a snapshot taken from another
+ run. The script checks the rewind path with `console save 1` …
+ `console load 1`, and the screenshot shows the repainted 2 s trail.
+- **A GPU trail is impossible.** `vector.Renderer(.gpu)` renders 8x MSAA, and
+ `host/gpu.zig:213` always clears a multisampled pass (`clear = null` is
+ ignored), so the trail has to be CPU: 920 KB uploaded per frame. No
+ documentation mentions this. I found it by reading the host.
+
+**Wished-for API:** `sk.noise(x, y, z)` / `sk.Noise{ .seed }`, and
+`sk.map`. Retained layers (see 1) that the host keeps on the GPU, with
+`Input.jumped` to signal a repaint.
+
+## 3. bouncing_ball (Example 1.2)
+
+**Processing:** 21 lines: `background`, `PVector.add`, and `circle` with
+stroke.
+
+**Friction**
+
+- **The circle costs a whole renderer.** For one stroked circle the port
+ needs a `Session { layer: ?vector.Renderer(.gpu) = null }`, a Pen built in
+ scratch memory, and `showGpu`. Inside `showGpu`: lazy init with
+ `f.session` and `f.host`, `finish`, `begin` with a transparent clear,
+ `draw`, `present`. That is 10 lines of plumbing written once, but a first
+ sketch has to discover all of it:
+ ```zig
+ f.clear(0xffffff);
+ var pen: hb.Pen = .{ .b = .init(f.scratch), .fill = hb.gray(127, 255), .stroke = hb.gray(0, 255), .weight = 2 };
+ pen.circle(s.position[0], s.position[1], 48) catch {};
+ h.showGpu(&ss.layer, f, &pen, width, height);
+ ```
+- **Two pipelines that do not compose.** `f.clear` and `f.fill` are host
+ primitives, while the vector layer is an image drawn over them. The draw
+ order is clear (commands run in order), but layering a translucent vector
+ shape *under* a host rect would take a second layer.
+- **`@Vector(2, f32)` vs inspection.** I chose `@Vector` for PVector math
+ (`s.position += s.velocity`). But `expect position ...` shows
+ `<16 bytes>`, because layout leaves keep vectors and arrays whole. So I
+ added a `bounces: u32` field just for the script. With a
+ `struct { x, y }`, `expect` would see the fields, but the arithmetic would
+ have to be written out field by field. **You cannot have both.**
+- **Indexing is worse than PVector names.** `s.position[0]` reads worse than
+ `position.x`. A vector type with named lanes does not exist in Zig.
+ (Swizzles aside, `v.x` is not available on `@Vector`.)
+- **Easier than Processing:** the state is two vectors in a struct. Hot
+ reload keeps the ball where it was while I edit the bounce code, and
+ replay works for free.
+
+**Wished-for API:** `sk.Vec2` = `@Vector(2, f32)` with free functions (`mag`,
+`setMag`, `limit`, `heading`, `fromAngle`, `dist`), and the layout/console
+learning to show `@Vector` and small arrays element-wise (`position[0]`, or
+`position` → `{250, 220}`). Then `f.circle(center, d, .{ .fill, .stroke,
+.weight })` as a host command (Canvas2D has `arc`, and SDL can take
+`RenderGeometry` triangles), with no Session renderer.
+
+## 4. accel_to_mouse (Example 1.10)
+
+**Processing:** `mouseX`/`mouseY`, plus `normalize`, `mult`, `limit` and
+`add`.
+
+**Friction**
+
+- **The mouse is fine:** `in.mouse_x`/`in.mouse_y` are there in update and
+ replay correctly. Before any event the mouse is at (0, 0), as in
+ Processing.
+- **No scalar broadcast:** `dir * 0.2` does not compile, so I wrote
+ `hb.scale(dir, 0.2)` or `dir * @as(Vec, @splat(0.2))`. Every force formula
+ pays this tax.
+- **The script needs a scalar to wait on.** I wanted `await` on "the mover
+ reached the mouse". There is no tolerance compare for floats, and vectors
+ are opaque, so I added `caught: bool` (distance < 24) to State:
+ ```
+ move 560 300
+ await caught true
+ ```
+ It works well and reads nicely, but it is test-only state.
+- **Easier than Processing:** the script drives the mouse
+ (`move 560 300`) and the run is deterministic, so a "does it chase the
+ mouse" test was 7 lines. Processing has nothing like it.
+
+**Wished-for API:** `expect position.x ~250 0.5` (a tolerance), or
+`await dist(position, mouse) < 24` (expressions are probably too much). At
+least make `@Vector` lanes addressable.
+
+## 5. fluid_resistance (Example 2.5)
+
+**Processing:** an array of `Mover` objects, a `Liquid`, `random(0.5, 3)`,
+`mousePressed()`, `fill(127, 127)` (alpha), `rect` with `noStroke`.
+
+**Friction**
+
+- **Random initial state needs `init`.** `setup()` calls `reset()`, which
+ calls `random()`. In sketchbook, defaults are comptime, so the random reset
+ goes into `pub fn init(s: *State)`. That part is easy and documented. But
+ the PRNG seed is fixed (`.init(25)`), unlike Processing's time seed.
+ Seeding from `host.clock()` in `init` should be safe, since init is not
+ replayed, but nothing says so explicitly.
+- **`mousePressed()` is an event scan:**
+ ```zig
+ for (in.events) |e| if (e.kind == .mouse_down) { reset(s); s.resets += 1; };
+ ```
+ This is fine, if lower level. `in.pressed(key)` exists for keys, but there
+ is no `in.clicked(button)` for the mouse.
+- **The update/draw split changes the order of operations slightly.**
+ Processing calls `show()` *before* `checkEdges()`, so a mover is drawn
+ below the floor for the one frame it bounces. In the port, update clamps
+ first, so draw sees the clamped position. This difference cannot be seen,
+ but a faithful port could not reproduce Processing's order without storing
+ a "drawn position".
+- **Arrays of structs cannot be inspected.** `movers[0].position` is not a
+ field path, so `resets` and `frame_count` exist only for the script.
+- **Alpha works:** `hb.gray(127, 127)` → `Drawing.Color` with a = 0.5,
+ blended correctly over both white and the 220-gray liquid in the
+ screenshot.
+- **The liquid is one `f.fill` rect** under the vector layer. That is the
+ nicest line in the port.
+- **Easier than Processing:** a fixed-size `[9]Mover` is ordinary Zig, and
+ `@splat(.{})` makes the default. Methods on `Mover` and `Liquid` read like
+ the Java.
+
+**Wished-for API:** `in.clicked(.left)` / `in.mouseDown(.left)` next to
+`pressed`. Console and `expect` paths into arrays (`movers.3.position`).
+A documented "init may use `host.clock()` to seed".
+
+## 6. angular_forces (Example 3.2)
+
+**Processing:** `push(); translate(); rotate(); circle(); line(); pop();`,
+`constrain`, and `fill(175, 200)` for the attractor.
+
+**Friction**
+
+- **Transforms exist, but only as an explicit affine on each shape.** B's
+ Pen has a `transform` field, and the vector geom `Affine` composes:
+ ```zig
+ pen.transform = Affine.translate(m.position[0], m.position[1]).mul(.rotate(m.angle));
+ pen.circle(0, 0, m.radius * 2) catch {};
+ pen.line(0, 0, m.radius, 0) catch {};
+ ...
+ pen.transform = .identity; // pop()
+ ```
+ This is honest and more explicit than a matrix stack, and I like it. The
+ only snag is that forgetting the reset leaks the transform into later
+ shapes, which is exactly the bug a `pop()` prevents. A by-value Pen (copy =
+ push) would fix that.
+- **Processing's style state leaks across frames.** `strokeWeight(2)` set in
+ `Mover.show()` still applies when the attractor is drawn on the next frame,
+ so the attractor really has weight 2 from frame 2 on. Being explicit avoids
+ this kind of hidden global. The port uses weight 2 throughout.
+- **`catch {}` on every shape.** The Pen's `circle`/`line` return `!void`
+ because the builder allocates, but draw returns `void`. Fourteen
+ `catch` arms across this batch (8 in the ports, 6 in helpers_a).
+- **Positions spread over the whole canvas need `init` and the PRNG**, as in
+ 5. **`constrain` is `std.math.clamp`:** fine.
+
+**Wished-for API:** `sk.Pen` as a value with `translate`/`rotate` methods that
+return a new Pen, so that pop is just a copy going out of scope. Shape calls
+that do not fail, recording into scratch and dropping on OOM with one log
+line, like `Frame.emit` already does.
+
+---
+
+## Helpers: A vs B, and which design wins
+
+I adopted B's Vec ops, `Rng`, `random`, `gray` and `Pen`, and deleted my own
+copies: my `Style` struct passed to each call, `setMag`/`limit`/`range`. What
+is left in `helpers_a.zig`:
+
+| piece | A | B | better |
+|---|---|---|---|
+| Pen style | mine: `Style` value passed per call | stateful `Pen` fields like Processing | **B's** for porting speed. A by-value `Style` composes better for push/pop. A library Pen should be a value (copy = push). |
+| noise | comptime `java.util.Random` table, matches `noiseSeed(0)`, 3D | runtime Xoshiro table from a seed, 2D | **A's** for fidelity and zero runtime cost. B's allows a runtime seed. The library should hash, not use a table. |
+| fixed step | `steps60(&clock, in)` | none (one step per update) | **A's**: B's dynamics run 2.4x fast on a 144 Hz display. |
+| canvas | `showGpu` (GPU, 8x MSAA, transparent, redrawn) + `Trail` (CPU, accumulating, repaints on seek back) | `Canvas` (CPU, clears to bg each frame) | Different jobs: GPU for redraw-every-frame, CPU only where pixels must persist. |
+| List(T, cap) | not needed (fixed arrays) | yes | B's. None of my examples grows a list. |
+
+---
+
+## Ranked summary: the gaps that cost the most
+
+1. **There is no shape drawing in the Frame API.** It has no circle, line,
+ stroke, alpha shapes or transforms. Five of the six ports need circles with
+ strokes, and the only route is the vector module: a build.zig import, a
+ Renderer in Session, a Drawing per frame, and a layer image. That is about
+ 40 lines of helpers, plus 14 `catch` arms across the batch. *Wish:*
+ `f.circle/line/rect/polygon(…, .{ .fill, .stroke, .weight, .transform })`
+ as host commands, or an `sk.Pen` value backed by one `Command.shape`.
+2. **Nothing persists across frames, and nothing tells the sketch it jumped
+ in time.** Accumulating sketches (random walk, noise walker, and anything
+ with trails) need a bitmap in State or a shadow simulation in Session plus
+ a "steps drawn" heuristic to repaint. Multisampled GPU passes always clear,
+ so trails are forced onto the CPU, at a 920 KB upload per frame. *Wish:*
+ retained offscreen targets that draw commands can render into,
+ `Input.jumped`, and a documented recipe for repainting from State.
+3. **Scripts and the console cannot see `@Vector` fields or array elements,
+ and compare floats as exact text.** Every port grew a scalar just for its
+ test (`frame_count`, `bounces`, `caught`, `resets`). The idiomatic math
+ type (`@Vector`) is the one that inspection cannot see. *Wish:* lanes and
+ elements as field paths (`position[0]`, `movers[3].mass`), plus
+ `expect field ~value tol`.
+4. **There is no fixed-rate step.** Per-tick physics runs at the display's
+ rate, and the first tick has dt = 0. *Wish:* `sk.FixedStep` /
+ `sk.Clock(60)` as plain data in State.
+5. **There is no noise, map or random-in-range.** `noise` is about 60 lines to
+ do right. *Wish:* a pure `sk.noise(seed, x, y, z)` with a GLSL twin, plus
+ `sk.map` and an `sk.Rng` with `float(lo, hi)`.
+6. **PVector ergonomics.** There is no scalar broadcast (`v * 0.2` fails),
+ `v[0]` instead of `v.x`, and no `mag`/`setMag`/`limit`/`heading` outside
+ `vector.geom`, which has `length`/`normalize` but is a different module.
+ *Wish:* `sk.vec` with those free functions, re-exported from `sketch`.
+7. **Debug builds make per-pixel draw loops unusably slow** (0.5 s/frame for
+ 230 k `isSet` calls), and a slow script looks exactly like a hang. *Wish:*
+ build e2e and run steps with `-Doptimize=ReleaseSafe` by default for
+ sketches, as a build.zig option. A frame-time warning from the headless
+ host would also help, such as "frame 20 took 480 ms".
+8. **Concurrent e2e runs collide.** The per-sketch script state path in
+ .zig-cache is fixed, so two `zig build e2e` runs at once fail with "store
+ is open in another process", and then **segfault** in
+ `SDL_DestroyRenderer` on the error path (`host/Host.zig:118` errdefer).
+ The crash is a bug in its own right. *Wish:* a unique state path per run,
+ and an errdefer order that does not cancel a GPU command buffer from a
+ half-made renderer.
+9. **`zig build e2e` is flaky under load.** Each full run, 2–8 random
+ sketches (A's and B's alike) fail with `LeakedSdlMemory` from SDL's Vulkan
+ allocations at exit (`host/root.zig:74`), never with a failed `expect`.
+ The same scripts run one after another: 0 failures in 16 runs. This is a
+ leak check that depends on parallelism, and it makes "e2e must pass"
+ unreliable. *Wish:* the SDL leak check opt-in for scripts, or the
+ underlying Vulkan teardown fixed.
+10. **Small papercuts:**
+ - There is no `in.clicked(button)`.
+ - It is undocumented whether `init` may read `host.clock()` for a seed.
+ - `uintLessThan(u2, 4)` does not compile.
+ - The `vector` module needs a build.zig import, which every sketch that
+ draws anything round will need.
+
+**Easier than Processing**
+
+- Deterministic replay, and scripts that drive the mouse and check state. A
+ 7-line "chases the mouse" test, and a test that rewinds to a snapshot and
+ checks the trail repaint, are impossible to write in Processing.
+- Hot reload keeps the simulation running while I edit forces.
+- Fixed arrays of plain structs with methods read like the Java and need no
+ `new`.
+- `@Vector` arithmetic (`velocity += acceleration`) is shorter than
+ `PVector.add`.
+- The vector renderer's quality: anti-aliased 8x MSAA, correct alpha, and
+ round caps. The output looks like Processing's.