Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Merge main, keeping both parity sections (#1036)

Nguyen Xuan Anaaeec2a34ead
diff --cc docs/cycles-parity.md
index 299a09f3,c7434869..0d89f013
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@@ -1139,28 -1139,34 +1139,60 @@@ The test (`tests/native-instancing-equi
Scenes without shared geometry did not change. The packed tables (v1 for both kernels, v2 flattened, v2 with `instancing: true` but no sharing, and an instanced scene) and the traced pixels of the `legacy` and `cycles` kernels at 48 x 32 and 16 samples have the same SHA-256 on `origin/main` and on this branch, with both addons built in the same run.
+ ## Why textured surfaces rendered bright (#1030)
+
+ The `cycles` kernel decoded every texel of an 8-bit sRGB map to linear and then filtered the decoded values. Blender Cycles filters the stored 8-bit values and decodes the blend. The decode curve is convex, so a blended texel decoded first is always brighter than one decoded last, and the gap is largest where neighbouring texels differ, at the edges of a checker. The kernel now fetches stored values and decodes the filtered result (`texture_decode_filtered` in `closure.wgsl`). Nearest reads, linear maps and every untextured scene give the same values as before (lit-interior and glass match the base byte for byte on both kernels). Every scene with a filtered sRGB map changes: this is a look change toward Cycles.
+
+ Proof on the smallest scene, `tex-emit-srgb` (an emissive quad seen head on with nothing else in the room, 128 x 128, 256 spp, RTX 4090, Blender 5.3). The mean of the picture in closed form from the texels, for each order of decode and filter, against what each renderer drew (R, G, B):
+
+ | | Mean linear value |
+ | --- | --- |
+ | closed form, decode then filter | 0.47000, 0.36315, 0.19351 |
+ | closed form, filter then decode | 0.44136, 0.34604, 0.17975 |
+ | Cook before | 0.47000, 0.36314, 0.19350 |
+ | Cycles | 0.44144, 0.34608, 0.17978 |
+ | Cook after | 0.44144, 0.34608, 0.17979 |
+
+ `tex-emit-linear` (the same map as a linear map) is 0.64706, 0.58824, 0.42157 in closed form, in Cook and in Cycles, so the sampler's geometry (texel centres, wrap, flip) was right and the colour curve order was the whole gap on opaque maps. `render-cycles.py` now builds a `colorSpace: 'linear'` map as a Non-Color image; before, it always used sRGB, so a linear map could not be compared.
+
+ Cook over Cycles, 2048 spp, 960 x 540, seed 1, mean ratio R, G, B and relMSE (eps 0.01); Cycles seed against seed is 7.9e-7 to 1.7e-6:
+
+ | Scene | Before | After |
+ | --- | --- | --- |
+ | `tex-split-colour` (opaque colour map) | 1.0207, 1.0275, 1.0357; 2.2e-3 | 1.0001, 1.0002, 1.0002; 7.6e-7 |
+ | `tex-split-mask` (colour map with an alpha ramp, cutout) | 1.0182, 1.0246, 1.0234; 1.6e-3 | 1.0131, 1.0110, 1.0145; 1.3e-3 |
+ | `tex-repeat` (both quads) | 1.0396, 1.0388, 1.0512; 3.9e-3 | 1.0131, 1.0065, 1.0099; 1.3e-3 |
+ | `tex-split-room`, `tex-split-flat` (no texture) | 1.000 | 1.000 |
+ | `brick-graph` (graph material with a map) | 0.9817, 0.9880, 0.9925; 1.61e-2 | 0.9817, 0.9879, 0.9923; 1.61e-2 |
+
+ Still open: the mask quad is 1.1 to 1.5 percent bright. Two renders of the diagnostic scenes (`tex-mask-alone`: the mask quad without the backdrop; `tex-mask-opaque-map`: the backdrop plus the same mask material over an opaque map) put it off the texture read: with the backdrop removed the quad is 1.0021, 1.0022, 1.0012 (measured in a build that also blended colour weighted by alpha, which did not move the full scene beyond 0.2 percent, so it was dropped), and with an opaque map under the mask material the whole scene is 1.0001. The ratio map of `tex-split-mask` puts the excess in the columns of the cutout holes and in the strip of backdrop below the quad, where Cook is up to 40 percent brighter: the light that reaches the backdrop past a cutout, not the colour of the quad. The cause there is not known.
+
+ Two known differences from Cycles remain in the read of a map and are not changed here. Cycles premultiplies the stored values of a byte image by alpha before the filter and divides by alpha after it when the alpha output is used; the kernel filters straight colour and alpha independently, which differs only where alpha varies between neighbouring texels. And the packed mean colour of an emissive map (`meanLinearRgb`, used for the radiance of a light sample on a textured emitter) is still the mean of the decoded texels, a few percent above the filtered read on a high-contrast sRGB map.
+
+ Commands: `node bench/cycles-parity/texture-scenes.mjs <dir>` also writes `tex-emit-srgb`, `tex-emit-linear`, `tex-split-*`, `tex-mask-alone` and `tex-mask-opaque-map`; `native-texture-sampler.test.js` holds a GPU-gated test of the seam between a black and a white texel (0.214 linear when blended before decoding, 0.5 when decoded first).
++
+## Native job materials (#1036)
+
+A native render job on the `cycles` kernel used to send v1 material tables, which hold base colour, metallic, roughness, emission, clearcoat, transmission, ior, normal scale, the mask cutoff, subsurface, the light mask and four atlas textures. The page now exports FORMAT-v2 for every `cycles` job (instanced or not) and lays the rest of each material over those fields (`carriedMaterialFields` in `packages/render-native/job-input.mjs`): blend opacity, sheen, `specular` and `specularColor`, anisotropy, iridescence, attenuation, the clearcoat, transmission, sheen, anisotropy and coat normal maps, and the record fields a material may set by their record names. `docs/agent-render-jobs.md` lists what the report still says it ignores.
+
+Same scene, same 4096 samples, 192 x 128, box filter, 8 bounces, seed 1, against Cycles 5.3 (4096 spp, `render-cycles.py`), RTX 4090 `[measured]`. `before` is the v1 tables (what a job sent), `after` the export a job sends now, `bench` the scene packed with `buildNativeInputV2` as the parity benches do. The gates are those of the M1 suite: per-channel mean ratio within 2 percent, 8 x 8 tiles within 5 percent.
+
+| Scene (field) | Mean ratio RGB, before | Mean ratio RGB, after | relMSE (eps 0.01), before | relMSE, after | Tiles within 5 percent, before / after |
+|---|---|---|---|---|---|
+| `blend` (opacity 0.3 pane) | 0.9436, 1.0592, 1.1458 | 0.9997, 0.9998, 0.9998 | 3.81e-2 | 1.12e-5 | 41 / 64 to 64 / 64 |
+| `sheen` (sheenColor, sheenRoughness) | 0.9874, 0.9838, 0.9901 | 0.9996, 0.9996, 0.9996 | 5.33e-3 | 4.74e-6 | 55 / 64 to 64 / 64 |
+| `specular-tint` (specular 0.8, specularColor) | 0.9997, 1.0070, 1.0094 | 0.9997, 0.9997, 0.9997 | 5.68e-3 | 6.77e-6 | 64 / 64 to 64 / 64 |
+| `anisotropy` (0.7, rotated) | 1.0027, 1.0048, 1.0070 | 0.9997, 0.9997, 0.9997 | 2.36e-2 | 7.33e-6 | 55 / 64 to 64 / 64 |
+| `iridescence` (thickness 500, ior 1.4) | 1.0010, 1.0027, 1.0022 | 0.9997, 0.9997, 0.9997 | 7.74e-5 | 6.64e-6 | 64 / 64 to 64 / 64 |
+| `absorption` (attenuation 1 m, green) | 1.1030, 1.0356, 1.0885 | 0.9649, 0.9906, 0.9715 | 1.73e-1 | 1.60e-2 | 48 / 64 to 55 / 64 |
+| `composite` (blend pane over a sheen sphere) | 0.9828, 1.1051, 1.1714 | 0.9997, 0.9998, 0.9998 | 6.73e-2 | 1.14e-5 | 39 / 64 to 64 / 64 |
+
+- The job export and the `bench` packing give the same numbers for every scene except `anisotropy`, so the job path delivers the bench's input. `anisotropy` differs on purpose: the kernel reads the Cycles Principled parameters (a strength that stretches the roughness, a rotation in turns), while a 67js material holds the glTF strength and a rotation in radians. The job converts them as `render-cycles.py` does for Blender; `buildNativeInputV2` on the raw material does not (relMSE 2.26e-2, 55 of 64 tiles, because the lobe is the wrong shape).
+- `absorption` improves by a factor of 11 in relMSE but does not pass the 2 percent mean gate (red 0.9649, blue 0.9715) and has 9 tiles outside 5 percent, in the job export and the bench packing alike. The kernel applies the glTF attenuation exactly (transmittance equals `attenuationColor` after `attenuationDistance`); `render-cycles.py` gives Blender one grey density from the mean log of the colour `[inferred]`, so part of the gap is likely the reference, not the kernel. This was not separated.
+- The v1 tables are still what the legacy kernel and light bakes read. Not carried: `doubleSided` (a job traces every surface two sided, and carrying the 67js default `false` would cull the backs of every material), the `liquid` tag, `occlusionMap`, `lightMap`, `moss` and splat layers, the coat and sheen roughness maps (the record has one slot for each pair), and `thickness`.
+- A scene whose materials cannot be exported whole is traced from the v1 tables for that frame, with the reason in `materialsReason`.
+- Known limits of the carried layers. The kernel reads a coat's weight and roughness from one map and a sheen's tint and roughness from one map, so a clearcoat or sheen colour map is carried only when the layer's roughness is 0 or its roughness map is the same image; otherwise the factor alone is used and the job report says so. An iridescence factor below 1 thins the film (the record holds thickness times the factor) where the rasteriser weights the effect, so the hue differs from a full-strength film; the parity row is at factor 1. An anisotropy map scales the converted Cycles strength, which is not the conversion of the scaled glTF strength, so the lobe shape is approximate where the map is below 1. The record-name fields (`coatTint`, `coatIor`, `thinWalled` and the rest of `RECORD_FIELDS`) are for callers that build parts in code; no MCP material sets them, and a value that is not a finite number, a boolean or an array of finite numbers is refused.
+
+![Opaque pane before, blend pane after, Cycles 5.3 (left to right) for a blend pane over a sheen sphere](native-job-materials.jpg)
+
+Jobs 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`).