summaryrefslogtreecommitdiff
path: root/examples/noc/notes/impl-vector-perf.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/impl-vector-perf.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz
sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/impl-vector-perf.md')
-rw-r--r--examples/noc/notes/impl-vector-perf.md158
1 files changed, 158 insertions, 0 deletions
diff --git a/examples/noc/notes/impl-vector-perf.md b/examples/noc/notes/impl-vector-perf.md
new file mode 100644
index 0000000..789c8a5
--- /dev/null
+++ b/examples/noc/notes/impl-vector-perf.md
@@ -0,0 +1,158 @@
+# Phase 3: vector-perf
+
+2026-10-30. Three items: fewer draws in the vector GPU backend, NoC 5.12 bin-lattice,
+and a timeline check for the Book of Shaders sketch.
+
+## 1. Vector GPU backend: draw count
+
+### What changed (`lib/sketchbook/src/vector/`)
+
+- **Convex fills are drawn directly.** If a fill's polygons are one convex contour
+ (`Polygons.convex`), its fan from the first point is drawn painted, with no stencil
+ pass. The fan's triangles never overlap, so each sample inside is shaded exactly once,
+ the same samples the stencil pass would have set. The test is exact: every turn goes
+ the same way (straight runs and repeated points are allowed), and the edge direction's
+ x flips sign at most twice, which rules out spirals and doubly wound shapes. The
+ slightest reflex corner falls back to stencil-then-cover. Any paint qualifies (solid
+ or gradient). Strokes never qualify, because they are many pieces.
+- **Fills are batched into layers.** Each layer is up to 4 draws: a nonzero stencil
+ draw, an even-odd stencil draw, one cover draw (all its boxes), then one direct draw
+ (all its convex fans, in order). A fill goes into the lowest layer that keeps the
+ picture the same as drawing every fill alone and in order:
+ - A stencilled fill goes above the highest layer holding an earlier fill whose box
+ overlaps its own.
+ - A direct fill may join that layer, because it is drawn after the layer's covers and
+ after the earlier direct fans.
+
+ So stencilled fills in one layer never overlap, and their stencils and covers cannot
+ mix. Each cover still zeroes its own stencil. Overlap is looked up on a coarse grid of
+ the image (4 px cells, coarser above 64k cells). Each cell holds 1 + the highest layer
+ touching it. The lookup is conservative: fills that share a cell count as
+ overlapping. The draw count follows how deep fills pile up, not how many fills there
+ are.
+- **Per-fill paint moved from a uniform into the vertices.** Cover and direct vertices
+ are `layouts.Painted` (position, colour, gradient index; 28 B):
+ - a solid paint is its premultiplied colour times alpha;
+ - a gradient carries the alpha in all four channels plus an index into a storage
+ buffer of `Paint` blocks.
+
+ `Gpu.upload` (called by `Renderer.present`) makes and grows that buffer through
+ `f.host.newBuffer` and uploads only gradient blocks. Solid fills upload nothing.
+ `Renderer.deinit` frees the buffer. `cover.frag` became `paint.frag` (same maths,
+ `#define paint paints[fill_gradient]`), and the new `paint.vert` passes the paint
+ flat. `layouts.Paint` is now a `.plain` struct (all vec4, so std430 = std140).
+- `Gpu.pass` now takes `*Gpu` (it builds the draws). lib `build.zig`: shader list +
+ `Painted` layout. vecanim `tools/bench.zig`: its stub Host gained `freeBuffer`.
+ README vector paragraph updated.
+
+### Correctness
+
+- The bench screenshots (gpu mode, N=1000 and N=5000, Debug and ReleaseFast) are
+ **byte-identical** before and after.
+- vecanim svgdiff: with the original src/vector swapped back in, the table is identical.
+ **All 72 svgdiff images are byte-identical** old vs new, gradients and opacity
+ included.
+- **Pre-existing failure, not from this change:** case `typst-text` fails for both
+ renderers (cpu mean 1.194, gpu 1.344, limit 1.0). The diff image shows a uniform
+ sub-pixel outline on every glyph, which points to typst 0.15.1 output vs resvg. The
+ coordinator is raising it with the owner. Every other case passes; vecanim e2e
+ passes.
+- Unit tests:
+ - `Polygons`: "convex contours" (square either way, repeated/closing points, straight
+ runs; rejects an L, a bow tie, a pentagram, a square wound twice, a line, a point).
+ - `Gpu`, the batching rules:
+ - a convex fill is one direct draw;
+ - a non-convex fill is stencil + cover;
+ - disjoint fills of both rules share one layer;
+ - convex fills over a ring join its layer, after its covers;
+ - a ring over those goes a layer up, and a convex fill over that ring joins it;
+ - a far-away fill drops back to layer 0;
+ - `layerFor` itself;
+ - gradients go to the paint buffer, and their vertices carry index and alpha;
+ - off-image fills draw nothing.
+- Web: `zig build web` in vecanim translates the new shaders with naga. I could not
+ run WebGPU here: headless Chrome lost its device and fell back to CPU. Runtime on
+ the web host is **untested**. It uses a fragment storage buffer the way
+ scope/waveform already does.
+
+### Numbers (perf.md's bench, rebuilt)
+
+The scratchpad bench from perf.md was gone (tmp was wiped), so I rebuilt it against the
+real library:
+- `n` static boids, each a filled triangle (18×9 px) plus a 1 px stroke, at 640×360;
+- `vector.Renderer(.gpu)`;
+- `--console "set n N"`.
+
+Wall time per frame = (630 frames − 30 frames) / 600, headless. Release numbers come from
+before and after binaries built from the same host commit, run interleaved, 3 rounds. The
+load average was 9–15 from the other agents' builds, so absolute numbers are noisy, but
+the ratios are large.
+
+| build | N | draws before | draws after (layers) | ms/frame before | ms/frame after |
+|---|---:|---:|---:|---|---|
+| ReleaseFast | 1000 | 4000 | 39 (14) | 2.88 / 3.35 / 3.68 | **0.64 / 0.66 / 0.82** |
+| ReleaseFast | 5000 | 20000 | 141 (48) | 18.8 / 20.8 / 24.7 | **3.89 / 4.33 / 4.39** |
+| Debug | 1000 | 4000 | 39 | 10.9 / 10.5 / 14.7 | **7.9 / 7.1 / 6.7** |
+| Debug | 5000 | 20000 | 141 | 55.6 / 56.4 / 55.8 | **38.6 / 25.6 / 25.7** |
+
+ReleaseFast is about 5× faster. What is left at N=1000 (≈0.65 ms) is mostly sketch-side
+tessellation (Drawing builder, `Polygons.fill/stroke`), which perf.md measured at
+≈0.7 µs per boid. Debug gains less, because unoptimised tessellation dominates there.
+For reference, the CPU renderer on the same run was 5.8–6.4 ms (N=1000) in ReleaseFast.
+
+## 2. NoC 5.12 Bin-lattice spatial subdivision (`src/bin_lattice.zig`)
+
+- Written from scratch on sk.math/sk.draw/sk.Clock/sk.List. Behaviour follows the
+ Processing original (`Example_5_12_*`):
+ - 40 px cells (16×9);
+ - binned once per step, with `constrain` at the edges;
+ - each boid looks at the 3×3 cells around its own cell, bounds-checked, in the
+ original's col-then-row order;
+ - boids move in turn and see earlier boids already moved;
+ - grid lines are gray 200, the pointer's 3×3 cells are shaded (255, 50, 50, 100), and
+ mouseDragged adds a boid.
+
+ Starts with **2000** boids (the original had 800).
+- The grid lives in State as a counting sort:
+ - `start[cells + 1]` holds where each cell's run starts in `order`;
+ - `order[max_boids]` holds boid indices in cell order (u16).
+
+ It has no pointers and no per-cell lists: two fixed arrays that save, scrub and migrate
+ like any State. It is rebuilt from positions every step, so a reload that changes
+ `resolution` (and the array lengths) loses nothing. Scripts can read it
+ (`grid.start[144]` = boid count, `grid.order[0]`). Separation, alignment and cohesion
+ are summed in one pass over the neighbours.
+- Drawing is 4 `shape` commands for any number of boids: grid lines, shaded cells, all
+ bodies, all outlines, each an `sk.draw.Tessellation`.
+- Tests: `test/bin_lattice.script` (2000 boids, the grid holds every boid once, regression
+ positions, drag adds 3, the last one flew a step, a move without the button adds none,
+ screenshot looked at: flocks over the grid, 3×3 shading at the pointer).
+ `bin_lattice.timeline.script` (accel_to_mouse template with drags; includes the
+ seek-vs-play screenshot equality). `.reload` edit: bodies gray → blue; the reload script
+ checks boids and grid kept, the screenshots differ, and the replay goes on. Row in
+ noc/build.zig under `// phase 3: vector-perf`.
+- **Frame time, ReleaseFast** (headless wall, 600 frames, 3 runs; load avg ≈ 12):
+ **6.2–6.8 ms/frame**. A perf profile gives: `update` 44% (≈2.8 ms; flocks pack into a
+ few cells, so the 3×3 neighbourhood still holds hundreds of boids), and
+ `sk.draw.Tessellation.finish` + `stroke` + memcpy/arena ≈ 38% (≈2.4 ms, the stroke
+ tessellation of 2000 outlines). The host's `shape` drawing is ≈ 6%.
+
+## 3. sketches/shaders timeline check
+
+`test/timeline.script`, added to the `scripts` list in shaders/build.zig. It records
+keys (right, left, l) and a click while time runs, then checks
+play/seek/mid-seek/step/pause/live-input replays against slot 2 (example 3, zig, and
+time to the bit). It also checks screenshot equality for play vs seek and for play vs
+step. Screenshot looked at: truchet in zig. `zig build e2e` in sketches/shaders passes.
+
+## Status of the "done" checks
+
+- lib/sketchbook `zig build test`: pass.
+- sketches/shaders `zig build e2e`: pass.
+- sketches/vecanim `zig build test`: everything passes except the pre-existing
+ `typst-text` svgdiff case, whose numbers are unchanged.
+- sketches/noc `zig build e2e`: all bin_lattice steps pass. At the time of writing,
+ `noise_walker.reload` and `flappy_bird.reload` fail. Both are other agents' sketches.
+ noise_walker's expected `clock.count` and walker values are one step off, which looks
+ like the lib-features Clock-slack change. flappy_bird's reload script still has
+ placeholder expectations (`bird.y 0`); it is in progress.