Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add the change note for the pixel filter and update the native tracer guide (#895)

Nguyen Xuan An1557bcc7f103
diff --git a/changes/895.md b/changes/895.md
new file mode 100644
index 00000000..06a6467b
--- /dev/null
+++ b/changes/895.md
@@ -0,0 +1 @@
+- The Cook `cycles` kernel samples the pixel filter from the Cycles 1024-entry table (`filterType`: `box`, `gaussian` or `blackman-harris`; `filterWidth` 0.01 to 16), and bad filter values now throw instead of falling back to box (#895)
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 31909fc7..8d4e1f58 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -61,7 +61,7 @@ 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).
+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.0027 against 0.0198 for the legacy kernel (Cycles: 0.0031). Three options follow Cycles: `sampler` (`'sobol-burley'` blue-noise pattern by default, `'white'` for the hash sampler), `filterType` and `filterWidth` (`'box'` width 1 by default, `'gaussian'` and `'blackman-harris'` from the Cycles filter table) and `lightSampling` (`'auto'`, `'tree'` or `'uniform'`; the Cycles light tree is used from more than one emitter). It is 2.3 to 3.1 times slower per sample than the legacy kernel before the light tree (0.92 s against 2.86 s on `lit-interior`, 960 by 540, 256 samples), and the light tree adds 16 to 30 percent per sample on top; at equal error against Cycles 5.3 it is 1.2 times faster on `lit-interior` and 3 to 6 percent slower on `many-lights-500`. 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`).