# 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.