diff options
Diffstat (limited to 'examples/noc/notes/impl-vector-perf.md')
| -rw-r--r-- | examples/noc/notes/impl-vector-perf.md | 158 |
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. |
