3D engine that AI agents drive
Merge main into the native triangle bound branch (#1041)
Nguyen Xuan Ane6995bb1212a
diff --cc docs/cycles-parity.mdindex 9ae845bd,7cd8cb4b..f3a8ec2e--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@@ -1309,33 -1309,29 +1309,60 @@@ Same scene, same 4096 samples, 192 x 12Jobs that use none of these fields are unchanged: the tables of a flattened job (all of them, including the kernel parameters), the instanced input of a shared-geometry job, and the PNG of a real job on the demo room, a textured scene, a scene with 40 copies of one mesh and a scene with glass and clearcoat have the same bytes as on the base branch (`tests/native-job-materials.test.js`, `bench/job-materials`).+ ## Texture mip levels (#896, slice T2)++ Blender Cycles reads level 0 of an image with bilinear filtering and has no mip mapping in its default path, so level 0 stays the default of Cook. `textureMips: true` (a packing option; `mips: true|false` on one texture) opts in. What existed before this slice: RGBA8 (unorm and sRGB), RGBA32F and RG16F textures packed and sampled by the one `texture_sample`, a 1 GiB pool check, a mip count bit field in the descriptor that nothing wrote or read (the packer took a `mipCount` it never filled, which is gone), and the uv transform, wrap, filter and colour space already in the dedupe key (`tests/native-texture-sampler.test.js`).++ **What it does.** The packer (`texture-mips.mjs`) stores a full chain after level 0, sides halved and rounded down. Level 1 is the integral of the level 0 reconstruction: each of its texels supersamples its footprint at up to 8 x 8 positions (wrap mode respected) and at each one does what the kernel does at level 0 (bilinear on stored values, centres at +0.5, then the sRGB decode), averaging in linear light; an sRGB map is encoded back to bytes, a float map keeps its floats. Levels 2 and up are a 2 x 2 box of the level before (sRGB in linear light, other formats on stored values, an odd last row or column read twice), all in doubles and rounded to the storage format once per level. Averaging sRGB bytes made a minified 30 / 220 checker read 0.205 where the light averages 0.365. Alpha is averaged like a channel, not weighted, so a cutout map should not ask for levels. A nearest map or a one texel map never stores levels. The pool check counts the levels (a third more texels).++ **Level choice.** With any levels stored the packer sets kernel flag `2048`. The integrator then keeps a ray cone per path: the camera pixel angle (twice the length of `camera_up` over the image height; an orthographic camera starts with a pixel wide cone), the cone width at each hit, widened at a bounce by one radian for a diffuse or sheen lobe and by twice the roughness alpha (at most one) for a glossy, coat or glass lobe; the aperture, the pixel filter and the curvature of the surface are not counted. At a hit the footprint in `uv0` units is the cone width, over the square root of the cosine between ray and geometric normal (at least 0.1, the geometric mean of the footprint ellipse), times the uv units per world unit of the triangle, times `max(1/8, 1/sqrt(total samples))` because the samples of a pixel already average over its footprint. The sampler turns that into `log2` of texels (the larger axis after `uv_scale`); at 0 or below it takes the level 0 path unchanged, above it blends the two levels around it. Level 0 stays filter-then-decode (#1030, what Cycles does). A stored level holds the mean light of a footprint, so the kernel decodes each of its four taps before the bilinear blend and the two levels blend in linear light; blending two stored sRGB values and decoding the result would be darker than the light they hold. Alpha tests and bump taps read level 0. The level has no half-level bias: a quad filling half of a 32 x 32 picture reads level 0 at one texel per pixel (the checker survives) and level 1 at two (flat mean 0.5, GPU test in `tests/native-texture-mips.test.js`).++ **Proof 1, byte identity with mips off** (RTX 4090, `texture-mips-identity.sh`, 160 x 90, 16 spp, seed 1): `lit-interior`, `glass`, `brick-graph`, `tex-repeat` and `tex-wraps` on the `legacy` and `cycles` kernels, SHA-256 of the pictures of this branch against a build of the commit it was cut from in the same run: 10 of 10 identical.++ **Proof 2, a minified checker** (`texture-mips-bench.mjs`; a 64 x 64 sRGB checker of 4 texel cells on a floor to the horizon, uniform sky, 320 x 180, 3 seeds; relMSE over the rows below the horizon against a 2048 spp picture of the same scene with levels off):++ | Camera | spp | relMSE levels off | relMSE levels on | Mean of the far rows: reference / off / on | Largest pixel difference on against off |+ | :--- | ---: | ---: | ---: | :--- | ---: |+ | receding to the horizon | 16 | 0.00741 | 0.00293 | 0.2997 / 0.3002 / 0.2991 | 0.23 |+ | receding to the horizon | 64 | 0.00109 | 0.00052 | 0.2997 / 0.2996 / 0.2994 | 0.08 |+ | magnified (30 cm above the floor) | 16 | 0.00060 | 0.00060 | 0.2773 / 0.2773 / 0.2773 | 0 |+ | magnified (30 cm above the floor) | 64 | 0.00009 | 0.00009 | 0.2773 / 0.2773 / 0.2773 | 0 |++ The magnified picture is bit for bit the one with levels off. On the receding floor levels on has 2.5 times lower error at 16 spp and 2.1 times lower at 64. The far rows (the 12 rows nearest the horizon, rows 92 to 103 of 180) are 0.2 percent under the reference at 16 spp and 0.1 percent at 64, inside the 0.5 percent target. The picture `docs/texture-mips-minified-checker.jpg` shows levels off, levels on and the reference at 16 spp. In the six bands of 12 rows below the farthest one the picture with levels on equals the one with levels off to the last digit: with this camera and a 0.5 UV per metre checker only the farthest band reads a level above 0 at 64 spp.++ **Two defects found by checking the chain, and a measurement that misled.** An earlier run reported far-row means of 0.260 and 0.238 for "level 1" and "level 2" forced over the whole picture, 13 and 21 percent under the reference. That number came from the bench, not the kernel: it rendered the level as a stand-alone texture, which the kernel reads as level 0 (stored values blended, then decoded), the very order that is darker for a contrasty map. The bench option is gone. What the packer stores is checked without a GPU (`linearLevelMeans` in the bench): mean linear light of the stored texels, level 0 texels 0.3643, level 0 reconstruction (what the kernel reads at level 0) 0.3154, level 1 and 2 0.3154, levels 3 to 6 0.3140. The kernel read of level 1 is checked on the GPU (`tests/native-texture-mips.test.js`): a contrasty 4 x 4 sRGB map with levels, repeated 8 times over a head-on quad so that a level 1 texel covers a pixel, gives a picture mean within 1 percent of the linear mean of the level 1 texels. The two real defects were in the packer: (1) level 1 sampled each texel at 4 x 4 positions, which is too coarse for a 30 / 220 edge and left its mean 1.6 percent short; it now takes up to 8 x 8 (0.02 percent short; a texture with more than about 1M level 1 texels takes fewer, to bound packing time at about 64M reconstructions); (2) every level was rounded to bytes and the next level built from the rounded one. The chain is now built in doubles and each level is rounded once to the nearest code of the stored value (Math.round, not a truncation). What is left is that rounding: a uniform level 3 or deeper is 0.44 percent under the reconstruction mean, within half a code at this brightness, and a flat grey keeps its byte at every level. The history that led here: averaging sRGB bytes (error 0.043), then linear-light levels with a blend of stored values (0.0081 at 16 spp, worse than off), then decoding each tap before the blend and level 1 from the level 0 reconstruction (0.0030 at 16 spp, far rows 1.3 percent dark), then this table. The cone width is a documented estimate; the aperture, pixel filter and curvature are not counted.++ **Float textures.** RGBA32F and RG16F were already packed and sampled. `tests/native-texture-mips.test.js` shows an HDR float emissive map (value 4 and 2 on a quad that fills the picture) coming out of the kernel unclamped with and without levels, and the packer tests show the formats, the chain of floats and halves and the 1 GiB check with levels.++ Commands: `bash bench/cycles-parity/texture-mips-run-all.sh <dir>` on a machine with a GPU builds this branch and its base, runs `cargo test`, the node tests, the identity check and the bench; `uv run --no-project --with numpy --with pillow python bench/cycles-parity/make-texture-mips-figure.py <dir>/bench docs/texture-mips-minified-checker.jpg --samples 16` draws the picture.+++## Triangle bound of a native scene (#1041)++`buildTraceScene` bounds a scene at 400,000 triangles for the CPU and WebGL tracers, which hold the triangles in JavaScript and in browser memory. A scene built for the native tracer asks for another bound with `maximumTriangles`, an integer from 1 to `MAX_NATIVE_TRACE_TRIANGLES` (4,000,000, the size the large sequence section measured on the card). Two costs are bounded apart: the unique triangles (once per shared geometry, or all triangles of a flattened scene) by `maximumTriangles`, and the triangles with every copy counted by four times that, 16,000,000 at the ceiling. The second bound is a guard and not a measured edge `[inferred: the kernel builds one bottom-level structure per geometry, so a copy costs an instance record]`. A render job on the Cycles-matching kernel passes 1,500,000 (`NATIVE_JOB_MAXIMUM_TRIANGLES` in `scripts/native-bake-page.js`); the legacy kernel keeps 400,000.++A scene under 400,000 triangles packs to the same bytes as before `[measured]`: the SHA-256 of every table of the lit-interior scene (flattened, as v1 tables and as v2 job tables) and of an instanced scene is equal before the change, after it, and with the option set (`bench/cycles-parity/packed-table-hashes.mjs`).++Why the job stops at 1,500,000 and the library at 4,000,000: the job page encodes each packed table as one base64 string, and V8 refuses a string above 536,870,888 characters. The triangle table is about 299 characters per triangle, so it breaks near 1.79 million unique triangles `[inferred from the measurements below]`. A 2,000,000 triangle scene aborted Node in `btoa` and a 4,000,000 one threw `RangeError: Invalid string length`. 1,500,000 leaves 17% under that. Packing in Node for the package API has no such string.++`bench/cycles-parity/native-cap-measure.mjs` builds four rippled grids (two of them used a second time) and packs them the way the job page does, one process per case. It ran on an RTX 4090 box shared with another job, one run per row, so the times are indicative `[measured]`. Memory is Node's `[a Chrome tab has not been measured]`.++| unique triangles | path | scene build s | pack s | base64 s | packed MB | base64 MB (largest table, characters) | JS heap MB | peak RSS MB |+| --- | --- | --- | --- | --- | --- | --- | --- | --- |+| 401,408 | instanced | 0.01 | 1.0 | 3.3 | 85.8 | 114 (119.9 M) | 749 | 1,164 |+| 401,408 | flattened | 0.59 | 1.3 | 3.1 | 85.8 | 114 (119.9 M) | 748 | 1,284 |+| 1,002,528 | instanced | 0.02 | 2.0 | 7.8 | 214.2 | 286 (299.4 M) | 1,856 | 2,617 |+| 1,002,528 | flattened | 1.5 | 3.0 | 8.0 | 214.2 | 286 (299.4 M) | 1,855 | 2,895 |+| 1,499,912 | instanced | 0.02 | 3.3 | 12.3 | 320.4 | 427 (448.0 M) | 2,773 | 3,817 |+| 1,499,912 | flattened | 2.2 | 3.5 | 12.1 | 320.4 | 427 (448.0 M) | 2,773 | 4,222 |+| 2,000,000 | instanced | 0.03 | 4.5 | aborts | 427.3 | over the string limit | 2,738 (no base64) | 3,444 (no base64) |+| 3,998,792 | instanced | 0.05 | 8.1 | fails | 854.2 | over the string limit | 5,381 (no base64) | 6,677 (no base64) |++Tracing the packed input on the card (480 by 270, 16 samples, GPU memory of the process from nvidia-smi, no base64 step):++| unique triangles | instances | traced s | acceleration build s | upload s | GPU memory MB |+| --- | --- | --- | --- | --- | --- |+| 1,002,528 | 7 | 0.54 | 0.03 | 0.04 | 585 |+| 2,000,000 | 7 | 0.95 | 0.10 | 0.13 | 1,235 |+| 3,998,792 | 7 | 1.31 | 0.13 | 0.55 | 1,961 |++Same picture: the 1,002,528 triangle scene (four meshes, two of them shared by a second instance) exported through the job path as instances, and again as a flattened scene of the same parts (about 1.5 million triangles after expansion), gave the same PNG, SHA-256 `165939ce…01404`, both times. The instanced export took 10.7 s and 2.6 GB of peak RSS; the flattened one 19.5 s and 4.2 GB.