Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Update the mip docs, picture and level-selection numbers for the integrated level 1 chain (#896)

Nguyen Xuan An03223bdae812
diff --git a/changes/896-texture-mips.md b/changes/896-texture-mips.md
index d4a470b5..a96b5022 100644
--- a/changes/896-texture-mips.md
+++ b/changes/896-texture-mips.md
@@ -1 +1 @@
-- The native `cycles` kernel can read texture mip levels: `textureMips: true` stores a box filtered chain after level 0 and picks the level from a ray cone (off by default, so pictures match Blender Cycles and every existing scene stays byte-identical) (#896)
+- The native `cycles` kernel can read texture mip levels: `textureMips: true` stores a mip chain after level 0 and picks the level from a ray cone (off by default, so pictures match Blender Cycles and every existing scene stays byte-identical) (#896)
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 8063f353..37833b37 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -1225,22 +1225,24 @@ Jobs that use none of these fields are unchanged: the tables of a flattened job
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).
+**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 4 x 4 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). 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, 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.
+**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 | 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 |
+| 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.00296 | 0.2997 / 0.3002 / 0.2957 | 0.22 |
+| receding to the horizon | 64 | 0.00109 | 0.00054 | 0.2997 / 0.2996 / 0.2964 | 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 (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.
+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.0 times lower at 64. The picture `docs/texture-mips-minified-checker.jpg` shows levels off, levels on and the reference at 16 spp. The far rows (rows 92 to 179 of 180, below the horizon) are 1.3 percent darker with levels on than the reference at 16 spp and 1.1 percent at 64 spp, while levels off is within 0.2 percent; across the three seeds the relMSE spread is under 3 percent, so that small darkening is a bias of the levels and not seed noise. It is not what drives the error (the error halves), but the far-row mean does not match the reference to within noise.
+
+**Where the remaining bias sits (inferred from a forced level, not proven).** The bench can force level N for the whole picture (a bench option, not a public one). Far-row mean by forced level, reference 0.2997: level 0 0.2999, level 1 0.2601, level 2 0.2382, levels 3 to 6 0.2952. Levels 3 and up, the ones the far rows actually read, are 1.5 percent under the reference, which is the size of the darkening in the table; so the residual is in the stored deep levels (8-bit sRGB quantisation of a mean, or the 4 x 4 integral of level 1 carried up by boxes), not in the blend or in the level choice. Forcing level 1 or 2 over the whole picture is 13 and 21 percent dark; I did not find why (a whole-picture level 1 or 2 reads texels that are still checker cells, so it also tests the bilinear read of cells narrower than the pixel, which the selection never asks of the far rows). The history that led here: the first averaging of 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 building level 1 from the level 0 reconstruction (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.
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index f3e649af..ad644665 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -66,7 +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").
+- 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 mip chain after level 0 (level 1 integrates the level 0 reconstruction, the rest are 2 x 2 boxes); 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.jpg
index 48be5dc9..8e480767 100644
Binary files a/docs/texture-mips-minified-checker.jpg and b/docs/texture-mips-minified-checker.jpg differ