3D engine that AI agents drive
Merge origin/main into 896-depth-of-field (#896)
Nguyen Xuan An2166d33b4d0a
diff --cc bench/cycles-parity/trace-native.mjsindex 8881515d,8b727594..88f501d3--- a/bench/cycles-parity/trace-native.mjs+++ b/bench/cycles-parity/trace-native.mjs@@@ -114,7 -114,7 +114,7 @@@ function parseLightSamplingOption(argumfunction parseTraceArguments(argumentList) {if (argumentList.length < 2 || argumentList[0].startsWith('--') || argumentList[1].startsWith('--')) {- throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda] [--grey-diffuse] [--write-depth] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]');- throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda,cpu-cli,cuda-cli] [--grey-diffuse] [--write-depth]');++ throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda,cpu-cli,cuda-cli] [--grey-diffuse] [--write-depth] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]');}return {sceneJsonPath: resolve(argumentList[0]),diff --cc docs/cycles-parity.mdindex 3dba788f,867d655a..2f522794--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@@ -870,23 -887,23 +887,40 @@@ All image gates and the depth gate pasNot covered: the Classroom scene (instancing, 854 instances, depth of field, which the depth comparator does not model: a thin lens changes the ray-to-Z conversion), a scene with a background, and 4096 spp references.+## Depth of field (#896, slice D1)++A camera with an `fStop` is a thin lens in the `cycles` kernel, with Cycles' model: aperture radius `focal length / 1000 / (2 * f-stop)` metres, a disk or a regular polygon of `apertureBlades` corners, and a focus distance measured along the view axis. The kernel already held the lens maths (`camera.wgsl`, a port of Cycles' `camera.h`); this slice connects it: `createCamera` turns `fStop`, `focalLength` or `fov` with `sensorWidth`, `focusDistance`, `apertureBlades` and `apertureRotation` (degrees, Blender's sense) into the aperture fields of the params block. Layout and options: [FORMAT-v2.md](../packages/render-native/FORMAT-v2.md) and the [render-native README](../packages/render-native/README.md#depth-of-field-cycles-kernel). The kernel and the legacy kernel are unchanged. Motion blur is not in Cook; it is a known gap and out of scope for #896.++Depth of field off: the packed params bytes and the random numbers drawn do not change. The lens sample (`lens_uv`) is drawn for every sample whether or not the aperture is above 0, and a pinhole camera writes the same lens words as before (`0`, `10`, `0`, `0`). Measured on an RTX 4090: 128-sample images of `lit-interior` and `glass` (480 x 270, fixed 32 samples per dispatch, seed 3), with this tree and with the base commit's JavaScript on the same addon, have identical SHA-256 for the `cycles` and the `legacy` kernel (4 of 4), and two runs of this tree agree. An earlier run on an L4 gave the same hashes.++Cycles comparison (`dof-depth` scene in `bench/reference/scenes.js`: objects 2 m, 6 m and 15 m from the camera and a grid of small lamps 15 m away; 960 x 540, f/1.0 on a 150 mm wide sensor, a 116 mm lens, focus on the ball 6 m away; the near spheres blur by about 28 pixels, the lamps by about 9; Blender 5.3.0 Cycles OptiX and Cook on one RTX 4090; seed 1, 8 bounces, box filter; `trace-native.mjs` and `render-cycles.py` take the same `--f-stop`, `--focus-distance`, `--aperture-blades`, `--aperture-rotation` (degrees) and `--sensor-width`) `[measured]`:++| Aperture | Cook 4096 spp against Cycles 4096 spp | mean ratio (R / G / B) | relMSE (eps 0.01) | tiles within 5 % |+| --- | --- | --- | ---: | ---: |+| disk | `--f-stop 1 --focus-distance 6` | 0.9996 / 0.9996 / 0.9996 | 3.4e-5 | 45 of 45 |+| hexagon, rotation 15, default focus | same | 0.9995 / 0.9996 / 0.9996 | 3.8e-4 (see below) | 44 of 44 |++Of 64 tiles, 19 (disk) and 20 (hexagon) are too dark to count. For the disk the relMSE equals Cycles' own seed 1 against seed 2 (3.4e-5): Cook sits at Cycles' noise floor. At 256 spp Cook scores 3.0e-4 and Cycles 2.6e-4 against the 4096 reference. The blur is large enough to tell the lens from a pinhole: Cook without a lens against the Cycles disk image scores 7.8e-3 (230 times worse), with 35 of 45 tiles within 5 percent and a tile ratio as low as 0.44. The hexagon score of 3.8e-4 came from a sign difference in the aperture rotation: the kernel turns the polygon the other way from Blender, so Cook at `-15` matched Cycles at `15` (whole-image relMSE 3.3e-5, lamp regions 0.004 against 0.055 for Cook at 15 and 0.03 for Cook at 0 or 30). `createCamera` now flips the sign, so `apertureRotation: 15` means the same as Blender's 15 degrees; the render with the flipped sign was not repeated after that change. Pictures: `artifacts/cook-parity/dof-896-comparison-rtx4090.png` (rows disk and hexagon; Cook and Cycles at 256 spp, Cook and Cycles at 4096, difference times 4) and `dof-896-hexagon-bokeh-crops.png`.++Not covered: anamorphic bokeh (slice D2), lens shift and orthographic cameras (`createCamera` refuses both), the depth pass of a lens camera (not compared), and a re-render of the hexagon after the rotation sign flip.++ ## Progressive film and scene updates (#896, slice S2)++ A native session builds one image over several `render` calls (`accumulate: true`, `targetSamples`, `reset()`, `resolve()`) and applies new material values, lights, selection weights and instance transforms with `update()`. The kernel adds one sample at a time to the film in sample order and the Sobol-Burley sequence is indexed by the whole image's target count, so call boundaries cannot change a sum. The TLAS is rebuilt over the kept BLAS on a transform change (wgpu 30.0.1 has no refit); a change of counts, triangles or mesh topology is refused with a message that says to create a new session.++ Measured on one NVIDIA A10 (480 x 270, 32 samples, `bench/cycles-parity/session-progressive.mjs`):++ | Check | `lit-interior` | `many-lights-500` |+ | --- | --- | --- |+ | Split calls (16+16, 8+15+9; both samplers; path regeneration on and off) equal one call, byte for byte | 8 of 8 | 8 of 8 |+ | `update()` then `render` equals a fresh one-shot of the final input, byte for byte (materials; materials and transforms; back to start) | 3 of 3 | 3 of 3 |+ | New session, cold pipeline | 6721 ms | 6899 ms |+ | New session, pipeline already compiled in the process | 65 ms | 44 ms |+ | Update plus render (4 samples), materials only | 17.5 ms | 43.1 ms |+ | Update plus render, transforms (TLAS rebuilt) | 17.7 ms | 44.9 ms |++ One-shot `traceNative` images (both kernels) and S1 session frames hash the same as origin/main built in the same container.+## Reproducible CommandsRun from the repository root in PowerShell. Set `$env:BLENDER_BIN` if Blender 5.3 is installed outside `C:\Program Files\Blender Foundation\Blender 5.3\blender.exe`, and pass an untracked `<out-dir>` (such as `artifacts/cycles-parity`) so binary `.exr` and `.npy` files stay out of Git: