Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add the LUT license header and verification script, report the effective samplesPerDispatch and correct the parity notes (#894)

Nguyen Xuan An9c4e028c1e70
diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjs
index a7564f4a..ac56420f 100644
--- a/bench/cycles-parity/trace-native.mjs
+++ b/bench/cycles-parity/trace-native.mjs
@@ -153,6 +153,7 @@ async function runCli() {
height: options.height,
samples: options.samples,
averageSamples: traced.averageSamples,
+ samplesPerDispatch: traced.samplesPerDispatch ?? null,
bounces: options.bounces,
seed: options.seed,
filterType: options.filterType,
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 286b2cc7..f82194fa 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -7,7 +7,7 @@ All claims below are tagged `[measured]` (from benchmark artifacts produced by [
## Summary Verdict
- **Per-sample speed vs equal-error speed (`T_eq`) `[measured]`**: On `lit-interior` (`960 × 540`, `8` bounces, unclamped, undenoised), 67js `render-native` traces `256` samples in **`2.101 s`** median sampling time (`2.381 s` total trace) vs **`11.371 s`** (`13.456 s` total trace) in Cycles 5.3 OptiX — **`5.41×` faster per sample (`0.185×` time)**. However, at `256` samples 67js has **`6.33×` higher `relMSE`** (`0.019762` vs `0.003121`) and still has not reached Cycles' 256-spp error at `1024` samples (`0.005135`). Extending the 67js ladder to `2048` (`0.002679`) and `4096` (`0.001453`) samples brackets Cycles' 256-spp `relMSE` at **`1,740.5` samples (`6.80×` as many samples)**, giving **`T_eq = 10.331 s` sampling (`T_eq / T_cycles = 0.909×`)** and **`12.886 s` total trace (`0.958×`)**. Nearly the entire `5.4×` raw ray-tracing speed lead on this 3,072-triangle room is consumed by higher Monte Carlo variance (no light tree on bounces, white-noise PCG instead of Sobol + blue noise).
-- **Setup latency (`T_sync`), RAM, and VRAM `[measured]`**: Warm per-call setup is **`0.244 s`** median in 67js (`0.026 s` JS pack + `0.164 s` Vulkan adapter/device + `0.005 s` WGSL compile + `0.009 s` upload + `0.002 s` BLAS/TLAS) vs **`2.012 s`** in headless Blender/Cycles (`~1.80 s` Python/mesh build + `~0.21 s` Cycles OptiX sync), even though 67js recreates its `wgpu` device, pipeline, and acceleration structures on every call. Peak process-tree RSS is **`287.0 MiB`** in 67js vs **`590.2 MiB`** in Blender (`0.49×`). Cycles reports **`Mem: 351.0 MiB`** peak render memory; uncontended 67js runs at `2048–4096` spp measure **`211–433 MiB`** card VRAM delta (`769–998 MiB` total card VRAM above a `558–565 MiB` desktop baseline).
+- **Setup latency (`T_sync`), RAM, and VRAM `[measured]`**: Warm per-call setup is **`0.244 s`** median in 67js (`0.026 s` JS pack + `0.164 s` Vulkan adapter/device + `0.005 s` WGSL compile + `0.009 s` upload + `0.002 s` BLAS/TLAS) vs **`2.012 s`** in headless Blender/Cycles (`~1.80 s` Python/mesh build + `~0.21 s` Cycles OptiX sync), with the `wgpu` device, bind group layout, lookup table buffer and compiled pipelines cached for the life of the Node process (a pipeline cache of at most 32 kernels, dropped when the device is lost); the device and adapter figure above was measured before that cache, and only the scene buffers and the acceleration structures are built again on each call. Peak process-tree RSS is **`287.0 MiB`** in 67js vs **`590.2 MiB`** in Blender (`0.49×`). Cycles reports **`Mem: 351.0 MiB`** peak render memory; uncontended 67js runs at `2048–4096` spp measure **`211–433 MiB`** card VRAM delta (`769–998 MiB` total card VRAM above a `558–565 MiB` desktop baseline).
- **Radiometric bias (`[measured]`)**: At `4096` samples against Cycles `4096` spp (`Seed 1`, whose `Seed 1` vs `Seed 2` noise floor is `relMSE = 0.000285`), 67js global per-channel mean ratios are **`R = 1.0104, G = 1.0090, B = 1.0068`** (`+1.04% R, +0.90% G, +0.68% B`, scalar `1.0092`), and **all `64 / 64` tiles** in an `8 × 8` grid lie within `1 ± 0.05` (`min = 0.9849`, `median = 1.0034`, `max = 1.0280`). Fitting `relMSE(N) = B_bias + V / N` across `16..4096` spp isolates a systematic bias plateau **`B_bias = 0.000542`** (`~1.9×` the 4096-spp reference noise floor) driven by sphere point-light falloff near the ceiling (`+2.8%`) and missing multiscatter GGX + light-sphere reflections on the glossy table (`-2.1%`).
---
@@ -47,6 +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.
- **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.
diff --git a/packages/render-native/src/cycles/luts.rs b/packages/render-native/src/cycles/luts.rs
index c0be118a..0d4faf53 100644
--- a/packages/render-native/src/cycles/luts.rs
+++ b/packages/render-native/src/cycles/luts.rs
@@ -1,5 +1,13 @@
-// Auto-generated by extract_luts.py — do not edit by hand.
-// Source: packages/render-native/src/cycles/{bsdf_glass,bsdf_microfacet,closure}.wgsl
+/* SPDX-FileCopyrightText: 2009-2010 Sony Pictures Imageworks Inc., et al. All Rights Reserved.
+ * SPDX-FileCopyrightText: 2011-2026 Blender Foundation
+ *
+ * SPDX-License-Identifier: BSD-3-Clause AND Apache-2.0
+ *
+ * Lookup tables translated from Open Shading Language and Blender Cycles (kernel/closure/bsdf_microfacet.h,
+ * kernel/closure/bsdf_sheen.h, kernel/util/lookup_table.h) through the inline WGSL tables of bsdf_glass.wgsl,
+ * bsdf_microfacet.wgsl and closure.wgsl. Do not edit by hand.
+ * `uv run --no-project python packages/render-native/tools/verify-cycles-luts.py` checks that every word equals those
+ * original tables (read from the commit before they moved here) and prints ALL IDENTICAL. */
/// Static LUT words uploaded to `@group(0) @binding(12)` as a read-only storage buffer.
/// Layout:
diff --git a/packages/render-native/src/lib.rs b/packages/render-native/src/lib.rs
index 8a30b1e7..0ffe5796 100644
--- a/packages/render-native/src/lib.rs
+++ b/packages/render-native/src/lib.rs
@@ -136,6 +136,8 @@ pub struct NativeTraceResult {
pub variance: Float32Array,
/// The mean number of samples a pixel drew: below the requested count when `noise_threshold` stopped converged pixels.
pub average_samples: f64,
+ /// The samples each dispatch drew, as given or as chosen automatically (Cycles kernel only; absent for the legacy kernel).
+ pub samples_per_dispatch: Option<u32>,
pub adapter: String,
pub backend: String,
/// "EXPERIMENTAL_RAY_QUERY" when the device the trace ran on was opened with ray queries (the tracer needs them).
@@ -192,6 +194,7 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resu
depth: Float32Array::new(resolved.depth),
variance: Float32Array::new(resolved.variance),
average_samples: resolved.average_samples,
+ samples_per_dispatch: None,
adapter: prepared.adapter_name,
backend: prepared.backend_name,
features: prepared.features,
@@ -254,6 +257,7 @@ pub fn trace_scene_cycles(input: NativeTraceInputV2, options: NativeCyclesTraceO
depth: Float32Array::new(resolved.depth),
variance: Float32Array::new(resolved.variance),
average_samples: resolved.average_samples,
+ samples_per_dispatch: Some(samples_per_dispatch),
adapter: prepared.adapter_name,
backend: prepared.backend_name,
features: prepared.features,
diff --git a/packages/render-native/tools/verify-cycles-luts.py b/packages/render-native/tools/verify-cycles-luts.py
new file mode 100644
index 00000000..9f6b3891
--- /dev/null
+++ b/packages/render-native/tools/verify-cycles-luts.py
@@ -0,0 +1,96 @@
+"""Checks that the Cycles lookup tables in src/cycles/luts.rs equal the inline WGSL switch tables they replaced, word for word.
+
+Usage: uv run --no-project python packages/render-native/tools/verify-cycles-luts.py [reference-commit]
+
+The reference commit is the last one whose bsdf_glass.wgsl, bsdf_microfacet.wgsl and closure.wgsl still carry the
+tables inline (default 27ab0de0, the parent of the change that moved them into luts.rs). Those tables were translated
+from the Cycles kernel lookup tables, so a match proves luts.rs holds the same numbers. Prints one line per table and
+ends with ALL IDENTICAL or MISMATCH; the exit code is 0 only for ALL IDENTICAL.
+"""
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+DEFAULT_REFERENCE_COMMIT = "27ab0de0"
+PACKAGE_DIRECTORY = Path(__file__).resolve().parent.parent
+CYCLES_DIRECTORY = PACKAGE_DIRECTORY / "src" / "cycles"
+TOTAL_WORDS = 29712
+
+# (file, function name, lanes per entry, word offset in the shared buffer, word count)
+TABLES = [
+ ("bsdf_glass.wgsl", "bsdf_glass_lut_e_u32", 4, 0, 16384),
+ ("bsdf_glass.wgsl", "bsdf_glass_lut_eavg_u32", 4, 16384, 1024),
+ ("bsdf_microfacet.wgsl", "bsdf_mf_lut_small_u32", 4, 17408, 1040),
+ ("bsdf_microfacet.wgsl", "bsdf_mf_lut_thin_film_rgb", 3, 18448, 1536),
+ ("bsdf_microfacet.wgsl", "bsdf_mf_lut_ior_s_u32", 4, 19984, 8192),
+ ("closure.wgsl", "closure_lut_sheen_u32", 4, 28176, 1536),
+]
+
+
+def read_reference_source(reference_commit, file_name):
+ result = subprocess.run(
+ ["git", "-C", str(PACKAGE_DIRECTORY), "show", f"{reference_commit}:./src/cycles/{file_name}"],
+ capture_output=True, text=True, encoding="utf-8",
+ )
+ if result.returncode != 0:
+ sys.exit(f"Cannot read src/cycles/{file_name} at commit {reference_commit}. Pass a commit that still has the inline tables.")
+ return result.stdout
+
+
+def function_span(source, name):
+ start = source.index(f"fn {name}(")
+ end = source.index("\n}\n", start) + 3
+ return start, end
+
+
+def parse_inline_table(source, name, lanes, word_count):
+ start, end = function_span(source, name)
+ words = [0] * word_count
+ outer = None
+ entry_pattern = re.compile(r"case (\d+)u: \{(?: v = vec\d<u32>\(([^)]*)\); \})?")
+ entries_seen = 0
+ for line in source[start:end].splitlines():
+ match = entry_pattern.match(line.strip())
+ if not match:
+ continue
+ if match.group(2) is None:
+ outer = int(match.group(1))
+ continue
+ index = outer * 64 + int(match.group(1))
+ values = [int(token.strip().rstrip("u"), 16) for token in match.group(2).split(",")]
+ assert len(values) == lanes, (name, index, values)
+ for lane, value in enumerate(values):
+ words[index * lanes + lane] = value
+ entries_seen += 1
+ return words, entries_seen
+
+
+def read_rust_words():
+ text = (CYCLES_DIRECTORY / "luts.rs").read_text(encoding="utf-8")
+ body = text[text.index(f"CYCLES_LUT_WORDS: [u32; {TOTAL_WORDS}] = [") :]
+ body = body[: body.index("];")]
+ return [int(token, 16) for token in re.findall(r"0x[0-9a-fA-F]+", body)]
+
+
+def verify(reference_commit):
+ rust_words = read_rust_words()
+ assert len(rust_words) == TOTAL_WORDS, len(rust_words)
+ sources = {}
+ all_identical = True
+ for file_name, name, lanes, offset, word_count in TABLES:
+ if file_name not in sources:
+ sources[file_name] = read_reference_source(reference_commit, file_name)
+ words, entries = parse_inline_table(sources[file_name], name, lanes, word_count)
+ identical = words == rust_words[offset : offset + word_count]
+ all_identical = all_identical and identical
+ print(f"{name}: entries={entries} words={word_count} identical={identical}")
+ print("ALL IDENTICAL" if all_identical else "MISMATCH")
+ return all_identical
+
+
+if __name__ == "__main__":
+ commit = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_REFERENCE_COMMIT
+ sys.exit(0 if verify(commit) else 1)