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