Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Document the transparent bounce limits against Cycles at 0, 1, 2 and 8 with a comparison image (#894)

Nguyen Xuan Anb00ad7f21b33
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 66982bf9..d064cf5e 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -47,7 +47,7 @@ Exported losslessly from [`bench/reference/scenes.js`](../bench/reference/scenes
- In **Cycles** (`intern/cycles/scene/integrator.cpp:227`, `kernel/integrator/path_state.h:146`, `shade_surface.h:840-867`), setting `max_bounces = B` stores `kintegrator->max_bounce = B + 1`. Camera hits start at `path.bounce = 0`. Surface direct-light NEE (`integrate_surface_direct_light`) executes at `path.bounce = 0, 1, ..., B` (`B + 1` surface vertices). After sampling the BSDF at `bounce = B`, `bounce` increments to `B + 1 == max_bounce`, which sets `PATH_RAY_TERMINATE_AFTER_TRANSPARENT`: ray `B + 1` is traced **only** to accumulate emission/background MIS if it hits a light or escapes, and terminates immediately on any opaque surface without shading.
- In **67js** ([`packages/render-native/src/kernel.wgsl`](../packages/render-native/src/kernel.wgsl) lines `609-618`, `808-832`, `963-1048`), `tracePath` loops `for (var depth = 0; depth <= bounces; depth++)`, evaluating `addLights` (NEE) at `depth = 0, 1, ..., B` (`B + 1` surface vertices) and exiting after `depth = B` **without** tracing continuation ray `B + 1`.
- **Subtle sky-MIS consequence `[source]` + `[measured]`**: For analytical lights (`point`, `spot`, `area`, `sun`), 67js uses pure NEE (`directWeight = 1 / selectionProbability`), so `bounces = B` matches Cycles `max_bounces = B` vertex-for-vertex (`B + 1` NEE evaluations). For the environment map (`weightMode = 1`), 67js multiplies NEE at `depth = B` by the MIS weight `p_env^2 / (p_env^2 + p_bsdf^2)` (`kernel.wgsl:609-613`) expecting `depth = B + 1` to add the complementary BSDF escape weight `p_bsdf^2 / (p_env^2 + p_bsdf^2)` in `addEscape`, which never runs on the final bounce `depth == B`.
-- **Transparent bounce limit of 0 `[source]`**: with `transparent_max = 0` the Cycles kernel lets the path through the first transparent surface before it terminates, while the Cook kernel stops at the first transparent surface (`integrator.wgsl`, the `max_transparent_bounces == 0` test). The parity scenes use a limit of 8, so none reaches this case.
+- **Transparent bounce limit `[source]` + `[measured]`**: Cycles' `path_state_next` (`kernel/integrator/path_state.h`) counts the transparent surface it passes and sets `PATH_RAY_TERMINATE_ON_NEXT_SURFACE` once the count reaches `transparent_max_bounce`, so a path always passes the first transparent surface, also with a limit of 0 (its own FIXME note), and ends at the next surface with only that surface's emission. A limit of 0 therefore renders the same picture as a limit of 1. Shadow rays may pass `max(transparent_max_bounce - transparent_bounce, 0)` transparent surfaces (`integrate_shadow_max_transparent_hits` in `intersect_shadow.h`), so the surfaces the camera path already passed count against the shadow ray's limit. Both are in the Cook kernel since #894, measured in "Transparent bounce limits" below. Before, Cook stopped at the first transparent surface when the limit was 0, and gave every shadow ray the full limit.
- **Empirical white-furnace sphere check (`color = [0.8, 0.8, 0.8]`, `roughness = 1.0`, `specular = 0.0`, constant `1.0` sky, `128 × 128`, `256` spp) `[measured]`**:
- `B = 0`: Cycles center patch mean = **`0.79971`** (exact `0.8`, because ray `B + 1` completes background MIS) vs 67js = **`0.13334`** (`ratio = 0.16674 ≈ 1/6`, confirming analytically that $(1/4\pi)^2 / ((1/4\pi)^2 + (\cos\theta/\pi)^2)$ integrated over the cosine hemisphere equals `1/6`, so `0.8 / 6 = 0.13333` when ray `B + 1` is omitted).
- `B = 1` and `B = 8`: Cycles = **`0.79971`** vs 67js = **`0.79923`** (**`ratio = 0.9994`**, within `0.06%`), because every ray from the convex sphere escapes at `depth = 1` and completes vertex `0`'s MIS pair.
@@ -563,6 +563,36 @@ Result, Cook `cycles` kernel at 4096 spp, seed 1, 8 bounces, box filter, against
Left Cook, right Cycles 5.3, both 4096 spp, sRGB curve and no tone mapping. The disk, the ellipse with spread 1.2 and the square with spread 0.9 give one soft pool on the floor in both; the two panes of opacity 0.4 and 0.75 cast shadows of the two densities in both.
-The `lit-interior` reference was rendered again with the current `render-cycles.py` (4096 spp, seed 1): relMSE against the stored reference 4.9e-10 (the seed 1 versus seed 2 floor is 0.000285) and mean ratio 1.0000 in all channels, so the stored reference is what the current script produces `[measured]`. The seven-scene parity, cargo, lobe and furnace results above are those of the previous kernel: this change touches no WGSL or Rust.
+The `lit-interior` reference was rendered again with the current `render-cycles.py` (4096 spp, seed 1): relMSE against the stored reference 4.9e-10 (the seed 1 versus seed 2 floor is 0.000285) and mean ratio 1.0000 in all channels, so the stored reference is what the current script produces `[measured]`. The seven-scene parity, cargo, lobe and furnace results above are those of the kernel before "Transparent bounce limits" below; that change was run through all of them again.
-Still open: the `transparent_max = 0` edge (first paragraph of "Bounce-Count Semantics Verification") has not been compared with Cycles on a scene.
+## Transparent bounce limits (#894)
+
+The `transparent_max = 0` edge was the last open point of #894. The reference scene `transparent-bounces` (in `bench/reference/scenes.js`) has three blended layers of opacity 0.5 (red, green, blue, nearest first) in front of a lit grey backdrop that stops short of the top of the frame, where a uniform sky shows. The layers cover different parts of the frame: the left third of the picture sees one layer, the middle third two and the right third three. `bench/cycles-parity/trace-native.mjs` and `render-cycles.py` take `--transparent-bounces N` to set the limit on its own (the other limits stay 8).
+
+Cook `cycles` kernel at 4096 spp, seed 1, box filter, against Cycles 5.3 OptiX at 4096 spp seeds 1 and 2, `run-m1-parity.py` gates, one Modal container per run (NVIDIA A10 before, NVIDIA L4 after; Cook on the NVIDIA adapter) `[measured]`. The seed 1 versus seed 2 floor of the Cycles renders is a relMSE below 1e-6 and a mean ratio of 1.0000 in every setting. The last column is the ratio Cook over Cycles of the sky seen through one layer.
+
+| Limit | State | Mean ratio (R / G / B) | Tiles within 5 % | Tile min / max | FLIP LDR (ceiling) | relMSE | Sky behind one layer | Gates |
+| ---: | --- | --- | ---: | --- | --- | ---: | --- | --- |
+| 0 | before | 0.9675 / 0.9082 / 0.8897 | 52 of 64 | 0.5779 / 1.0029 | 0.0742 (0.0207) | 0.024720 | 0.757 / 0.512 / 0.460 | fail |
+| 0 | after | 1.0017 / 1.0016 / 1.0016 | 64 of 64 | 1.0002 / 1.0029 | 0.0059 (0.0207) | 0.000003 | 1.001 / 1.001 / 1.001 | pass |
+| 1 | before | 1.0017 / 1.0016 / 1.0016 | 64 of 64 | 1.0002 / 1.0029 | 0.0059 (0.0207) | 0.000003 | 1.001 / 1.001 / 1.001 | pass |
+| 1 | after | 1.0017 / 1.0016 / 1.0016 | 64 of 64 | 1.0002 / 1.0029 | 0.0059 (0.0207) | 0.000003 | 1.001 / 1.001 / 1.001 | pass |
+| 2 | before | 1.0034 / 1.0052 / 1.0059 | 64 of 64 | 1.0003 / 1.0385 | 0.0138 (0.0243) | 0.000233 | 1.001 / 1.000 / 1.000 | pass |
+| 2 | after | 1.0012 / 1.0010 / 1.0010 | 64 of 64 | 0.9999 / 1.0023 | 0.0055 (0.0243) | 0.000006 | 1.001 / 1.000 / 1.000 | pass |
+| 8 | before | 1.0011 / 1.0008 / 1.0008 | 64 of 64 | 0.9999 / 1.0020 | 0.0050 (0.0241) | 0.000007 | 1.001 / 1.000 / 1.000 | pass |
+| 8 | after | 1.0011 / 1.0008 / 1.0008 | 64 of 64 | 0.9999 / 1.0020 | 0.0050 (0.0241) | 0.000007 | 1.001 / 1.000 / 1.000 | pass |
+
+What it showed `[measured]`:
+
+- Cycles renders a limit of 0 and a limit of 1 identically (mean 0.54387 / 0.19923 / 0.16623 in both): the first layer is always passed, and the path ends at the second layer, which adds only its emission. The sky behind two layers reads 0.7641 (red) at limits 0 and 1 and 0.8986 at 2; behind three layers 0.8748, 0.9335 at 2 and 0.9863 at 8.
+- Before the fix Cook at a limit of 0 ended the path at the first layer, so the sky behind it was dark (46 to 76 percent of Cycles) and the image mean was 3 to 11 percent low. This is the edge the audit named.
+- A second difference showed at a limit of 2, which the audit had not listed: Cook was 1 to 2 percent too bright behind one layer, because its shadow rays got the full limit while Cycles gives them the limit minus the layers the camera path already passed. The image mean was within the gates (1.003 to 1.006), the tile maximum was 1.0385.
+- Both are fixed in `integrator.wgsl` (`int_trace_shadow` takes the path's transparent count; the two `max_transparent_bounces == 0` tests are gone, with the Cycles function named in the comment). All four limits pass every gate after the change, and the limits 1 and 8 did not move.
+
+![Cook (left) and Cycles 5.3 (right) at transparent limit 0 (top) and 1 (bottom)](cycles-transparent-bounces.jpg)
+
+Both pairs are identical in Cook and in Cycles: left Cook, right Cycles, 4096 spp, sRGB curve and no tone mapping. The lighter patches at the left are the sky behind one layer and the backdrop behind one layer.
+
+With the fix, on one Modal container (NVIDIA A10) `[measured]`: the seven scenes at 4096 spp (box filter) pass 7 of 7 (mean ratios 1.0000 `spot-area`, 1.0008 `light-linking`, 0.9993 `metal`, 0.9979 `glass`, 0.9996 `outdoor-hdri`, 1.0034 `lit-interior`, 1.0009 `many-lights-500`); `area-shapes` (0.9997) and `transparent-shadow` (1.0006) still pass 64 of 64 tiles with the numbers of the table above; `cargo test` 32 passed, 0 failed; the native node tests 84 passed, 0 failed, 1 skipped (it skipped before); `check-lobes.mjs` and `verify-lobes.py` (lobe probes and furnace scenes) exit 0. Against the kernel before the fix, the new test fails all three cases (the limit 0 mean was 3.3 percent off in red, the backdrop at limit 2 0.99 percent).
+
+`tests/native-transparent-bounces.test.js` pins the behaviour on a GPU (it skips without the addon): the image mean and the sky behind one layer at limits 0 and 1, and the image mean and the backdrop behind one layer at limit 2, against the Cycles means above with a tolerance of 0.5 percent.
diff --git a/docs/cycles-transparent-bounces.jpg b/docs/cycles-transparent-bounces.jpg
new file mode 100644
index 00000000..fcc59470
Binary files /dev/null and b/docs/cycles-transparent-bounces.jpg differ