Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Document the chain fixes, the new far-row numbers and the level 1 GPU check (#896)

Nguyen Xuan An222f8eb1f2e0
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 37833b37..eca45d0e 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -1225,7 +1225,7 @@ 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, 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).
+**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`).
@@ -1235,14 +1235,14 @@ Blender Cycles reads level 0 of an image with bilinear filtering and has no mip
| 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 |
+| 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.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.
+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.
-**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.
+**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.
diff --git a/docs/texture-mips-minified-checker.jpg b/docs/texture-mips-minified-checker.jpg
index 8e480767..24c34cbe 100644
Binary files a/docs/texture-mips-minified-checker.jpg and b/docs/texture-mips-minified-checker.jpg differ
diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.md
index 280c5967..e81b25ad 100644
--- a/packages/render-native/FORMAT-v2.md
+++ b/packages/render-native/FORMAT-v2.md
@@ -359,7 +359,7 @@ Total stride: **32 bytes** (`2 × 16 B`), alignment: **16 bytes**.
One sampler reads every descriptor: `texture_sample` in `src/cycles/closure.wgsl`. Shading, bump, normal maps and the alpha tests of the integrator (the opacity of a cutout or blended surface, for camera, bounce and shadow rays) all go through it, so a surface is seen and shaded with the same wrap, filter and format. Wrap `0` repeats, `1` clamps and `2` mirrors in float UV space before the texel lookup; `nearest` picks the texel the wrapped UV falls in, otherwise the four neighbours are blended. `texture_texels` is one storage binding, so the pool of all textures (each texture padded to 16 bytes) must fit the device's storage binding size, at most 1 GiB. `buildNativeInputV2` refuses a pool past 1 GiB and the host refuses one past the device's binding size, each with an error that names the size and the limit. The struct sizes above do not change.
-**Mip levels (opt in).** Level `0` is the texture as given. When the mip count is above `1`, the levels follow level `0` in the same run of words, with no padding between them: level `k` has `max(1, width >> k)` by `max(1, height >> k)` texels, each level stored as level `0` is (`1` word per texel for `RGBA8_*` and `RG16_FLOAT`, `4` for `RGBA32_FLOAT`), and the whole run is padded to 16 bytes once. The kernel finds level `k` by walking from `data_offset` (`texture_level_descriptor`). The packer builds the chain in `texture-mips.mjs`. Level `1` is the integral of the level `0` reconstruction: each level `1` texel supersamples its footprint with 4 x 4 positions (respecting the wrap mode of the texture), at each position reads level `0` exactly as the kernel does (bilinear on the stored values, texel centres at `+0.5`, then the sRGB decode) and averages in linear light; an sRGB map is encoded back to bytes, float maps keep their floats unclamped, alpha is averaged on its stored value like any channel (not weighted). Levels `2` and up are a 2 x 2 box average of the level before, in linear light for an sRGB map and on the stored values for every other format (an odd last row or column is read twice).
+**Mip levels (opt in).** Level `0` is the texture as given. When the mip count is above `1`, the levels follow level `0` in the same run of words, with no padding between them: level `k` has `max(1, width >> k)` by `max(1, height >> k)` texels, each level stored as level `0` is (`1` word per texel for `RGBA8_*` and `RG16_FLOAT`, `4` for `RGBA32_FLOAT`), and the whole run is padded to 16 bytes once. The kernel finds level `k` by walking from `data_offset` (`texture_level_descriptor`). The packer builds the chain in `texture-mips.mjs`. Level `1` is the integral of the level `0` reconstruction: each level `1` texel supersamples its footprint with up to 8 x 8 positions (fewer for a very large texture) (respecting the wrap mode of the texture), at each position reads level `0` exactly as the kernel does (bilinear on the stored values, texel centres at `+0.5`, then the sRGB decode) and averages in linear light; an sRGB map is encoded back to bytes, float maps keep their floats unclamped, alpha is averaged on its stored value like any channel (not weighted). Levels `2` and up are a 2 x 2 box average of the level before, in linear light for an sRGB map and on the stored values for every other format (an odd last row or column is read twice).
A texture stores levels only when `textureMips: true` is passed to the packer (or `mips: true` on that texture; `mips: false` overrides the option). The default is level `0` only, which is what Blender Cycles reads. A nearest-filtered texture or one of a single texel never stores levels. The dedupe key holds the mip count, so one image packed with and without levels is two descriptors. With `kernel_flags` bit `2048` set, the integrator keeps a ray cone per path (width at the ray origin, spread), and a hit passes the sampler the width of the ray footprint in UV units; the sampler turns it into `log2` of the footprint in texels (the larger of the two axes after `uv_scale`), reads level `0` while that is not above `0`, otherwise blends the two levels around it (trilinear) and stops at the last level. Level `0` is filtered on its stored values and decoded after, the order of #1030 (Blender Cycles); a level `1` and up holds the mean light of a footprint, so the kernel decodes each of its four taps before the bilinear blend, and the two levels of the trilinear blend in linear light. Blending two stored sRGB values and decoding the result would darken what the level holds. The alpha tests of the integrator and the bump taps always read level `0`.