3D engine that AI agents drive
Document texture mip levels with the identity check and the minified checker numbers (#896)
Nguyen Xuan Anc85d6cf6ceeb
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex e9b55ecd..8063f353 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -1220,3 +1220,28 @@ Same scene, same 4096 samples, 192 x 128, box filter, 8 bounces, seed 1, againstJobs 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: 2 x 2 box filter, sides halved and rounded down, an odd last row or column read twice. 8-bit linear maps and float maps are averaged on their stored values; an sRGB map is averaged in linear light and encoded back to bytes (averaging the 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, each bilinear on stored values with the sRGB decode after the blend (the order of #1030 at every level). Alpha tests and bump taps read level 0.++**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 | Largest pixel difference on against off |+| :--- | ---: | ---: | ---: | ---: |+| receding to the horizon | 16 | 0.00741 | 0.00812 | 0.22 |+| receding to the horizon | 64 | 0.00109 | 0.00295 | 0.14 |+| magnified (30 cm above the floor) | 16 | 0.00060 | 0.00060 | 0 |+| magnified (30 cm above the floor) | 64 | 0.00009 | 0.00009 | 0 |++The magnified picture is bit for bit the one with levels off (the footprint is below one texel, so the level 0 path runs). **The receding picture is not better with levels on: its error is 1.1 times higher at 16 spp and 2.7 times higher at 64.** The picture `docs/texture-mips-minified-checker.jpg` shows levels off, levels on and the reference at 16 spp. Level 0 with 16 spp is already close to the converged picture here, because a pixel average of 16 jittered bilinear reads of a high contrast checker has little noise left; what levels add is a bias. Row by row (16 spp, inferred from the pictures, not isolated): the bias sits in the farthest rows below the horizon, where the picture with levels is darker than the reference (mean 0.23 to 0.26 against 0.29 in rows 100 to 115 of 180) although the deepest levels hold the exact mean of the light (checked in the chain: byte 163, 0.366 after decode). I did not find the cause. Things tried that did not close the gap: averaging sRGB levels in linear light (before it the error was 0.043 at both sample counts), scaling the footprint with the sample count, and decoding sRGB texels before blending inside a level (0.0078 and 0.0032, the same within noise as 0.0081 and 0.0030). Until the cause is found, `textureMips` is worth turning on only after looking at the result for the scene; it is a way to trade a bias for less texture aliasing at very low sample counts, not an accuracy gain over level 0 with enough samples.++**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.diff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex 8f569fbe..f3e649af 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -66,6 +66,7 @@ Also checked before any ray is traced: samples times pixels times bounces at mos- `buildNativeInput` (the `legacy` kernel) refuses an instanced scene with an error; build the scene without `instancing` for that kernel. `traceNative` with `kernel: "legacy"` refuses a FORMAT-v2 input the same way.- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, `JS67_NATIVE_INSTANCING=off` (flattened triangles on the `cycles` kernel, to compare the two), or a scene where no geometry is shared, the job exports flattened geometry as before; on the `cycles` kernel the materials are still sent whole (next point), and only the legacy kernel reads the v1 tables.- A job sends the materials of an instanced scene and of a flattened one the same way (`buildJobNativeInput` and `buildFlattenedJobNativeInput` in `packages/render-native/job-input.mjs`): what the v1 material tables carry is read from them, and `carriedMaterialFields` lays blend opacity, sheen, specular, anisotropy, iridescence, attenuation and the layer textures over it. A part looks the same whether or not other geometry in the scene is shared, and a material that sets none of those fields packs to the record the v1 tables gave. Every job on the `cycles` kernel is exported as FORMAT-v2; the legacy kernel and light bakes keep the v1 tables.+- Texture mip levels are opt in on the `cycles` kernel: pass `textureMips: true` to the packer (or `mips: true` on one texture) and every linearly filtered texture, RGBA8, sRGB and float, stores a box filtered chain after level 0; the kernel then keeps a ray cone per path and reads the level a hit asks for, blended between two levels. Blender Cycles reads level 0 only, so the default stays level 0 and an existing scene packs and renders byte for byte as before. The pool check counts the levels (a third more texels). The estimate, its limits and the measured error of a minified checker are in `docs/cycles-parity.md` ("Texture mip levels").- When the instanced packer refuses a scene (copies of an emissive mesh that emit different triangles, a singular matrix), the job exports it flattened as before and the report says `instancing: "flattened"` and `instancingReason`. A scene that fails to export no longer marks the native tracer unusable for the process; only a tracer or adapter failure does.- A part with `shadowOnly: true` becomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep one `local_emissive_offset` for all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index.diff --git a/docs/texture-mips-minified-checker.jpg b/docs/texture-mips-minified-checker.jpgnew file mode 100644index 00000000..48be5dc9Binary files /dev/null and b/docs/texture-mips-minified-checker.jpg differ