3D engine that AI agents drive
Merge origin/main
Nguyen Xuan An24b7048b3a0e
diff --cc bench/runtime/PROFILE.mdindex 7acd1894,d2629e48..a87ec1d3--- a/bench/runtime/PROFILE.md+++ b/bench/runtime/PROFILE.md@@@ -278,25 -278,49 +278,72 @@@ Inferred, not isolated: SwiftShader sti**What to try next.** Measure the two full-screen passes against the vertex stage on `large-mesh` and `many-materials` with a profile that does not depend on the machine state (pin the cores, or count instructions), since the lit shader is no longer the proven bottleneck. Draw the environment background only where no mesh covers the pixel was already tried on 2026-11-01 and moved nothing.+ ## Remeasure on current main, and one exact change that did not pay (2026-11-03, branch `perf/swiftshader-ratio`, issue #74)++ Method: `bench/runtime/run.mjs --cpu-only --frames 8`, one scene and one engine per process, 67js and three.js alternated inside each round, 3 rounds, below-normal priority. CPU load was sampled for 1 s before each pair: 2 to 41 percent (the machine was quiet, other sessions mostly idle). The RTX 3060 showed 0 percent busy before the GPU runs. The driver script is not kept in the repository.++ **Frame on SwiftShader, default settings (4 samples, HDR target), milliseconds, medians of 3 (measured):**++ | Scene | 67js | three.js | Ratio median | Ratio range |+ | --- | --- | --- | --- | --- |+ | `instanced-objects` | 174 | 32 | 5.4 | 5.2 to 5.6 |+ | `many-materials` | 568 | 181 | 3.1 | 2.7 to 3.2 |+ | `many-lights` | 443 | 153 | 2.9 | 2.9 |+ | `moving-shadows` | 77 | 20 | 3.8 | 3.7 to 5.8 |+ | `large-mesh` | 557 | 198 | 2.8 | 2.8 to 2.9 |+ | `skinned-characters` | 191 | 27 | 7.5 | 6.9 to 7.7 |+ | `transparency` | 431 | 52 | 8.3 | 8.2 to 8.9 |+ | `large-outdoor` | 243 | 816 | 0.30 | 0.30 to 0.32 |++ So `large-mesh`, `many-lights` and `large-outdoor` are at or under 3, `many-materials` is at 3.1 (range 2.7 to 3.2), and `instanced-objects`, `moving-shadows`, `skinned-characters` and `transparency` are 3.8 to 8.3. The scenes with fewer fragments per triangle fall behind most, which fits a fixed per-fragment cost plus MSAA (inferred).++ **First frame on the RTX 3060** (`--gpu-only`, empty profile, 2 runs per scene, milliseconds, measured): `instanced-objects` 229, 204; `many-materials` 268, 222; `many-lights` 197, 266; `transparency` 235, 210; `moving-shadows` 265, 210; `large-mesh` 389, 365; `skinned-characters` 267, 265; `large-outdoor` 257, 248. Every scene is under 1 s (the worst is 389). The "under 1 s" target holds.++ **Where `transparency` (the worst ratio) goes** (`67js-ldr-one-sample`, 202 ms against `three-one-sample` 22 ms, so MSAA and HDR are not the cause; measured, 1 to 2 runs each):++ | Variant (picture wrong in each) | Frame (ms) |+ | --- | --- |+ | Nothing | 202 |+ | Blend batches not drawn | 42 |+ | Fragment shader returns the base colour right after `surfaceAlpha` | 30 |+ | `shadowVisibility` returns 1.0 | 114 to 136 |+ | Shadow filter skipped where the surface faces away from the sun | 191 |++ Both engines draw 288,000 triangles, and 67js draws them in 4 draw calls against 301. The blend pass is 80 percent of the frame and nearly all of it is the lit fragment shader across 300 overlapping layers; the sun shadow filter is 40 to 45 percent of that. `skinned-characters` with the same facing test: 130 to 80 ms (`67js-ldr-one-sample`, upper bound, picture wrong).++ **One change tried, pixel identical, not kept.** Take the 36 shadow fetches only where the sun lights the surface (`dot(normal, lightDirection) > 0`), or where another term reads `visibility` directly (floor, canopy, grass, sheen, clear coat, moss, and the room occlusion, which needed `room` to be computed before the call). `illuminate` returns nothing when that dot product is not positive, so the result is the same. PNG bytes were identical to the merge base in all 8 scenes. Default settings, 3 alternated rounds, ms:++ | Scene | Before | After |+ | --- | --- | --- |+ | `skinned-characters` | 185, 188, 193 | 181, 179, 184 |+ | `transparency` | 430, 435, 429 | 430, 601 (load), 436 |+ | `many-materials` | 578, 580, 593 | 572, 599, 575 |+ | `instanced-objects` | 178, 175, 170 | 173, 167, 167 |+ | `large-mesh` | 559, 560, 550 | 552, 546, 575 |++ The best case is 3 percent on `skinned-characters` and the rest is noise, so it was reverted. The 38 percent in the table above was with MSAA and HDR off; with them on, the cost the facing test skips is a small part of the frame.++ **Where this leaves the target.** Not met: four scenes are above 3 and `many-materials` is on the line. The remaining gap in `transparency` and `skinned-characters` is the lit fragment shader itself (fragment cost per covered pixel), and the measured exact changes in this file (this one, the three on 2026-11-03, the two on 2026-11-01) each move under 5 percent. The routes that remain change pixels or the frame format: no MSAA, `R11F_G11F_B10F` (20 percent on `instanced-objects`, mean 0.13 to 0.59 levels, not run through `npm run reference`), fewer shadow taps, or a shader with fewer terms for blended parts.+++## Sun shadow as one comparison fetch per tap (2026-11-03)++Measured on `perf/blended-shadow-taps` at 960 by 540, SwiftShader, `--cpu-only --frames 6`, Chrome headless. Each row alternates the old build, the new build and three.js in one window for 3 rounds, so machine load cancels; the machine ran at about 12 percent CPU from other sessions between runs. Frame in ms, then the median ratio to three.js (all three medians in the same window).++The shadow depth texture now has `TEXTURE_COMPARE_MODE` and linear filtering, and the shader samples it as `sampler2DShadow`. One fetch returns the 2 by 2 percentage-closer result that four `texelFetch` calls and a `step` each used to build by hand, so the 9-tap filter is 9 fetches, not 36. Edges clamp the same way.++| Scene | Before (ms) | After (ms) | three.js (ms) | Ratio before to after |+| --- | --- | --- | --- | --- |+| `transparency` | 424 to 431 | 364 to 367 | 51 to 52 | 8.4 to 7.1 |+| `skinned-characters` | 186 to 192 | 159 to 165 | 25 to 26 | 7.6 to 6.6 |+| `instanced-objects` | 171 to 177 | 100 to 148 | 31 to 32 | 5.5 to 4.0 |+| `moving-shadows` | 70 to 72 | 65 | 19 | 3.8 to 3.5 |+| `many-materials` | 561 to 570 | 478 to 490 | 173 to 175 | 3.25 to 2.79 |+| `many-lights` | 439 to 445 | 392 to 397 | 150 to 153 | 2.89 to 2.59 |+| `large-mesh` | 550 to 554 | 475 to 481 | 196 to 205 | 2.79 to 2.44 |+| `large-outdoor` | 239 to 258 | 229 to 243 | 787 to 804 | 0.31 to 0.29 |++`instanced-objects` has the widest spread after the change (100 to 148), so its ratio is a range of about 3.2 to 4.7. The 8 scenes keep their pictures: `npm run reference -- --skip-blender` scores all 23 reference scenes within 0.0001 of the stored scores against Cycles and EEVEE (largest move -0.0001), on both the GPU and SwiftShader renders. Nine rows of `baseline.json` changed in the fourth digit and were updated.++Not kept: 4 taps in place of 9 (two by two, spaced 3.5 texels) took `transparency` from 366 to 351 ms, 4 percent, for a smaller and different filter. The remaining distance on `transparency` (7.1 times) and `skinned-characters` (6.6 times) is not the shadow filter any more; they stay above the issue 74 target of 3 times.++The fog volume shares the shadow texture and now reads it through the comparison sampler, so its single tap is filtered over 2 by 2 texels where it was nearest. The main program also sets every 2D sampler to unit 1 when it links, because an unset sampler reads unit 0 and one unit may not hold two sampler types.