3D engine that AI agents drive
Document the Cycles-matching kernel, its parity and its speed (#894)
Nguyen Xuan Anaff06fdeab8d
diff --git a/changes/894.md b/changes/894.mdnew file mode 100644index 00000000..5b7be2ec--- /dev/null+++ b/changes/894.md@@ -0,0 +1 @@+- Cook, the native path tracer, has an opt-in `cycles` kernel (`kernel: 'cycles'` or `JS67_NATIVE_KERNEL=cycles`) that matches Blender Cycles 5.3 on six reference scenes; the default image does not change (#894)diff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex f82194fa..ced763e3 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -248,14 +248,14 @@ Rendered on RTX 3060 (`wgpu 30.0.1` Vulkan `EXPERIMENTAL_RAY_QUERY`) at `960 ×| Scene | All Gates | Mean Ratio `(R, G, B)` (`±2%`) | `8 × 8` Tiles Within `±5%` | Tile `[min, max]` | `FLIP_LDR` | Ceiling | `FLIP_HDR` | `relMSE` | Setup / Sampling (s, GPU contention) || --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |-| `spot-area` | **Pass** | `[1.0000, 1.0000, 1.0000]` | `47 / 47` | `[0.9993, 1.0008]` | `0.0071` | `0.0239` | `0.0148` | `0.000043` | `0.385` / `205.19` (`shared`) |-| `light-linking` | **Pass** | `[1.0009, 1.0007, 1.0009]` | `64 / 64` | `[0.9994, 1.0028]` | `0.0100` | `0.0228` | `0.0136` | `0.000113` | `0.425` / `291.65` (`shared`) |-| `metal` | **Pass** | `[0.9995, 0.9995, 0.9996]` | `64 / 64` | `[0.9935, 1.0068]` | `0.0055` | `0.0237` | `0.0061` | `0.005437` | `0.528` / `278.65` (`shared`) |-| `glass` | **Pass** | `[0.9976, 0.9979, 0.9983]` | `64 / 64` | `[0.9823, 1.0000]` | `0.0073` | `0.0234` | `0.0094` | `0.000076` | `0.445` / `423.51` (`shared`) |+| `spot-area` | **Pass** | `[1.0000, 1.0000, 1.0000]` | `47 / 47` | `[0.9992, 1.0009]` | `0.0071` | `0.0239` | `0.0148` | `0.000043` | `0.385` / `205.19` (`shared`) |+| `light-linking` | **Pass** | `[1.0009, 1.0007, 1.0009]` | `64 / 64` | `[0.9993, 1.0028]` | `0.0100` | `0.0228` | `0.0136` | `0.000113` | `0.425` / `291.65` (`shared`) |+| `metal` | **Pass** | `[0.9995, 0.9995, 0.9996]` | `64 / 64` | `[0.9935, 1.0059]` | `0.0055` | `0.0237` | `0.0061` | `0.005437` | `0.528` / `278.65` (`shared`) |+| `glass` | **Pass** | `[0.9976, 0.9979, 0.9983]` | `64 / 64` | `[0.9822, 1.0000]` | `0.0073` | `0.0234` | `0.0094` | `0.000076` | `0.445` / `423.51` (`shared`) || `outdoor-hdri` | **Pass** | `[0.9995, 0.9996, 0.9998]` | `64 / 64` | `[0.9987, 1.0001]` | `0.0029` | `0.0215` | `0.0032` | `0.000016` | `0.898` / `130.37` (`shared`) |-| `lit-interior` | **Pass** | `[1.0032, 1.0035, 1.0034]` | `64 / 64` | `[1.0003, 1.0082]` | `0.0217` | `0.0365` | `0.0238` | `0.000543` | `0.584` / `521.67` (`shared`) |+| `lit-interior` | **Pass** | `[1.0032, 1.0035, 1.0034]` | `64 / 64` | `[1.0004, 1.0082]` | `0.0217` | `0.0365` | `0.0238` | `0.000543` | `0.584` / `521.67` (`shared`) |-- **GPU contention note `[measured]`**: All six `4096`-spp Cook renders ran at `BelowNormal` priority under `gpu-lock` while `3–5` concurrent light-slot GPU processes (Blender, Node, Chrome/FFmpeg) shared the RTX 3060 (`gpuExclusive = false`, pre-run card VRAM `1,240–1,955 MiB`, card utilization `100%`). Cold Vulkan SPIR-V pipeline compilation of the concatenated `10`-file Cycles WGSL kernel measured **`60.9 s`** once per driver cache (`0.15–0.18 s` warm).+- **GPU contention note `[measured]`**: All six `4096`-spp Cook renders ran at `BelowNormal` priority under `gpu-lock` while `3–5` concurrent light-slot GPU processes (Blender, Node, Chrome/FFmpeg) shared the RTX 3060 (`gpuExclusive = false`, pre-run card VRAM `1,240–1,955 MiB`, card utilization `100%`). Cold Vulkan SPIR-V pipeline compilation of the Cycles WGSL kernel measured **`60.9 s`** once per driver cache before the speed work below, and about **`20 s`** after it (`0.15–0.18 s` warm). The sampling times in this table were taken before that speed work, on a shared card; the per-sample times are in the next section.- **Closed Phase A bias gaps `[source]` + `[measured]`**:- **Solid-angle spherical cap & analytic emitter MIS** ([`lights.wgsl`](../packages/render-native/src/cycles/lights.wgsl), [`integrator.wgsl`](../packages/render-native/src/cycles/integrator.wgsl)): eliminates the `+2.80%` ceiling hotspot and `-2.06%` tabletop deficit on `lit-interior`, tightening per-part ratios to `[1.0014, 1.0061]` and all `64 / 64` tiles to `[1.0003, 1.0082]`.- **Principled v2 closures** ([`closure.wgsl`](../packages/render-native/src/cycles/closure.wgsl)): dielectric & conductor multiscatter GGX (`table_ggx_E` / `E_avg`), F82 metallic tint, full microfacet glass reflection/refraction with Beer-Lambert volume absorption, clearcoat albedo scaling, and sheen bring `metal` (`relMSE` `1.638` → `0.00544`) and `glass` (`relMSE` `0.00546` → `0.000076`) into sub-percent agreement with Cycles 5.3.@@ -305,6 +305,37 @@ The two `anisotropic-ggx-*` probes (white base color, metallic `1`, roughness `0| `furnace-scene-coat` | `0.9994` | `1.0011` | `0.9981` | **Pass** || `furnace-scene-sheen` | `0.9993` | `1.0008` | `0.9986` | **Pass** |+### Selecting the kernel++The native tracer runs the legacy kernel unless you ask for the Cycles-matching kernel (Cook's `cycles` kernel). Pass `kernel: 'cycles'` to `traceNative`, or set the environment variable `JS67_NATIVE_KERNEL=cycles` for a process; an explicit `kernel` option wins over the variable. Any other name throws an error that lists the two valid names. The `cycles` kernel reads a FORMAT-v2 scene pack ([`FORMAT-v2.md`](../packages/render-native/FORMAT-v2.md)), the legacy kernel a v1 pack, and passing one to the wrong kernel throws. The default image of every existing caller does not change.++```js+import { traceNative } from '@codepawlhq/67js-render-native';++const result = traceNative(sceneInput, { width: 960, height: 540, samples: 256, kernel: 'cycles' });+```++### Speed of the `cycles` kernel++Sampling time, `960 x 540`, `256` samples, `8` bounces, RTX 3060, interleaved runs through `gpu-lock`, two runs each `[measured]`:++| Scene | Legacy kernel | `cycles` kernel | `cycles` / legacy |+| --- | --- | --- | --- |+| `lit-interior` | `0.92 s`, `0.93 s` | `2.86 s`, `2.86 s` | `3.1x` |+| `metal` | `0.57 s`, `0.58 s` | `1.34 s`, `1.34 s` | `2.3x` |++The `cycles` kernel is `2.3` to `3.1` times slower per sample than the legacy kernel and is opt-in. Its first version took `30.8 s` on `lit-interior` and `17.2 s` on `metal`; the speed work (per-scene kernel specialization, lookup tables in a storage buffer, passing closures and lobes by pointer, removing a scratch array) left the images bit-identical at the same seed and cut the compiled SPIR-V from `936 KB` to `306 KB`. A target of `2x` the legacy time was not reached.++Against Cycles 5.3 OptiX on `lit-interior`, `256` samples took `11.4 s` (measured in an earlier session on the same machine). Relative MSE against the Cycles `4096`-sample reference at `256` samples on `lit-interior`:++| Renderer | `relMSE` at `256` samples |+| --- | --- |+| Legacy kernel | `0.0198` |+| `cycles` kernel | `0.0065` |+| Cycles 5.3 OptiX | `0.0031` |++These are per-sample times on one scene. An equal-error comparison between the `cycles` kernel and Cycles has not been measured directly, so nothing here says Cook is faster than Cycles in general. The Cycles `lit-interior` reference was not re-rendered with the current script (its scene file and image are byte-identical to the earlier run).+---## Reproducible Commandsdiff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex 9a5171c4..31909fc7 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -61,6 +61,8 @@ The same scene and options give the same bytes. Random numbers come from a hash`backend: "native"` is an agent render job setting, not a `renderPathTracedImage` option: [`packages/render-native`](../packages/render-native/README.md) runs the same kernel on Vulkan ray queries. On the demo room at 1920 by 1080 and 64 samples an MCP image job took 25 to 35 s with native against 58 s with gpu (trace alone 2.7 to 3.1 s against 38.8 s; the rest is the page export, the wavelet denoise and the PNG), FLIP 0.0047 between them. A missing package, binary or adapter falls back to gpu with a note in the job report. `maxSeconds` is honoured: past it the native trace stops and the job fails, as on the other backends, instead of rerunning on gpu; `noiseThreshold` is too (the kernel applies the CPU stop rule per pixel, so `averageSamples` falls below `samples`; the `gpu` and `webgpu` backends still draw every sample). Volume fog and subsurface scattering are in the native kernel, compiled in only for a scene that uses them; `bench/native-tracer/scenes.mjs` draws the reference scenes on native and on the WebGPU megakernel for a FLIP comparison. Alpha cutouts (`alphaMode: "mask"`) work: cutout triangles are their own geometry and the kernel confirms a hit only when the colour map alpha reaches the cutoff, with no step limit. In a dense cutout scene native is the more correct tracer: the CPU and WebGL2 shadow ray takes the first hit the traversal finds, not the nearest, and when that hit is a transparent texel it skips occluders it had not reached yet, so those backends leak light (300 leaf cards: native vs cpu FLIP 0.043, and 0.0002 once the CPU shadow ray takes the nearest hit; bench/native-tracer/cutout-bisect.mjs shows one card agrees exactly). The steps before: up to 8 layers deep (`bench/native-tracer/cutout.mjs`: 300 masked leaf cards trace in 0.1 s at 640 by 360 and 64 samples). See [agent-render-jobs.md](agent-render-jobs.md#path-tracer).+The native package has two kernels. The default `legacy` kernel is the one described above. Pass `kernel: 'cycles'` to `traceNative` (or set `JS67_NATIVE_KERNEL=cycles`) for the opt-in kernel that follows Blender Cycles 5.3: on six reference scenes at 4096 samples it matches Cycles within 1 percent of the mean and within 1.8 percent on every 8 by 8 tile, and its error at 256 samples on `lit-interior` is 0.0065 against 0.0198 for the legacy kernel (Cycles: 0.0031). It is 2.3 to 3.1 times slower per sample than the legacy kernel (0.92 s against 2.86 s on `lit-interior`, 960 by 540, 256 samples). Tables, method and the equal-error caveat are in [cycles-parity.md](cycles-parity.md#selecting-the-kernel).+`backend: 'cpu'` (the default) is the reference: it reuses `src/triangle-bvh.js` and `src/ray-query.js`, runs on workers in the job page next to the scene, needs no GPU, and gives the same bytes for the same scene and options. It measured 25 to 238 seconds for a 960 by 540 still at 32 samples on a Ryzen 5 5600X with four threads, while another session also loaded the machine (table in `bench/reference/README.md`).`backend: 'gpu'` (issue #302) runs the same algorithm in a WebGL2 fragment shader (`src/path-tracer-gpu.js`, loaded only for this backend, so a CPU render and the core bundle do not carry it). The BVH, triangles, materials, maps, lights and the environment table are packed into float textures (`src/path-tracer-gpu-pack.js`), the random numbers are the same integer hash and PCG stream as the CPU tracer and are drawn in the same order, and each sample adds into four float targets (colour and depth, albedo, normal, luminance and its square) that feed the same denoiser. Float32 maths and a 24-bit random value make the pixels differ a little from the CPU tracer: FLIP (LDR) of GPU against CPU at the same seed was 0.0001 to 0.0018 on the 16 path tracer reference scenes at 480 by 270 and 32 samples. It needs a page with WebGL2, `EXT_color_buffer_float` and `EXT_float_blend`, and throws without them, so choose it only where those exist. It traces everything the CPU tracer does (lights with linking, all materials and maps including emissive maps, glass, volume fog, the sky); it does not use `noiseThreshold` (every pixel draws every sample) or `threads`, and a sample that produced a NaN or an infinity counts as black. The first still of a page compiles the kernel (13 to 30 s), later ones reuse it.