3D engine that AI agents drive
Make the Cycles film sum independent of the dispatch split (#1006)
Nguyen Xuan Anbb56b671183b
diff --git a/changes/1006.md b/changes/1006.mdnew file mode 100644index 00000000..347e7e69--- /dev/null+++ b/changes/1006.md@@ -0,0 +1 @@+- The Cook native renderer gives the same image for the same scene, seed and settings whatever the dispatch split, so two renders no longer differ in a few bytes (#1006)diff --git a/packages/render-native/README.md b/packages/render-native/README.mdindex 6cb1144a..cdf774f4 100644--- a/packages/render-native/README.md+++ b/packages/render-native/README.md@@ -37,3 +37,5 @@ Cook's `cycles` kernel samples with Cycles' Sobol-Burley blue-noise pattern (`sa## DispatchesThe Cook kernel splits a render into dispatches that each aim for about 0.5 s, sized from the time of the previous one, so a heavy scene does not run past the driver timeout and lose the device. `samplesPerDispatch` fixes the batch instead. A lost device raises an error that names the dispatch and how to lower the work per dispatch. The split is tested in `tests/dispatch.rs` (`cargo test --test dispatch`).++The split does not change the image. The `cycles` kernel carries each pixel's running sums through a dispatch and adds one sample at a time in sample order, so the float32 additions into the film come in the same order whether a dispatch draws 1 sample or 64, and two renders of the same scene, seed and settings are byte-identical even when their time-sized splits differ. The `legacy` kernel draws one sample per dispatch and adds it straight to the film, so it has the same property. `tests/native-dispatch-determinism.test.js` renders with different `samplesPerDispatch` values and compares the bytes. A fixed `samplesPerDispatch` of 1 gives the same bytes as before this change; larger batches now match it instead of adding a per-dispatch partial sum.diff --git a/packages/render-native/src/cycles/integrator.wgsl b/packages/render-native/src/cycles/integrator.wgslindex 4ec6fe39..ceb2b125 100644--- a/packages/render-native/src/cycles/integrator.wgsl+++ b/packages/render-native/src/cycles/integrator.wgsl@@ -707,10 +707,16 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {let filter_glossy_enabled = kernel_params.filter_glossy > 0.0;let inv_filter_glossy = select(1.0e30, 1.0 / max(kernel_params.filter_glossy, 1.0e-8), filter_glossy_enabled);- var batch_radiance = vec3<f32>(0.0);- var batch_depth = 0.0;- var batch_albedo = vec3<f32>(0.0);- var batch_normal = vec3<f32>(0.0);+ // The running sums start from what the film holds and take one sample at a time in sample order. That is the same+ // sequence of float additions as adding every sample straight to the film, so the image does not depend on where one+ // dispatch ends and the next begins (summing a batch from zero first would regroup the additions per split).+ let film_radiance_and_depth = film_accumulation[pixel_index];+ var batch_radiance = film_radiance_and_depth.xyz;+ var batch_depth = film_radiance_and_depth.w;+ let film_albedo_lane = film_accumulation[pixel_count + pixel_index];+ let film_normal_lane = film_accumulation[2u * pixel_count + pixel_index];+ var batch_albedo = film_albedo_lane.xyz;+ var batch_normal = film_normal_lane.xyz;var taken_in_batch = 0u;for (var s = 0u; s < sample_count; s += 1u) {@@ -1097,9 +1103,9 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {}if (taken_in_batch > 0u) {- film_accumulation[pixel_index] += vec4<f32>(batch_radiance, batch_depth);- film_accumulation[pixel_count + pixel_index] += vec4<f32>(batch_albedo, 0.0);- film_accumulation[2u * pixel_count + pixel_index] += vec4<f32>(batch_normal, 0.0);+ film_accumulation[pixel_index] = vec4<f32>(batch_radiance, batch_depth);+ film_accumulation[pixel_count + pixel_index] = vec4<f32>(batch_albedo, film_albedo_lane.w);+ film_accumulation[2u * pixel_count + pixel_index] = vec4<f32>(batch_normal, film_normal_lane.w);film_accumulation[3u * pixel_count + pixel_index] = stats;}}diff --git a/tests/native-dispatch-determinism.test.js b/tests/native-dispatch-determinism.test.jsnew file mode 100644index 00000000..f18d83d0--- /dev/null+++ b/tests/native-dispatch-determinism.test.js@@ -0,0 +1,95 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildNativeInputV2, findNativeAddon, traceNative } from '../packages/render-native/index.mjs';+import { buildNativeInput } from '../packages/render-native/pack-input.mjs';+import { createCamera } from '../src/path-tracer.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';+import * as pack from '../src/path-tracer-gpu-pack.js';++const skipWithoutAddon = findNativeAddon() === null ? 'the native addon is not built' : false;++const UNIT_QUAD = {+ positions: new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0]),+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),+ colors: new Float32Array(12).fill(1),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+};++const FLOOR = {+ positions: new Float32Array([-1, 0, 1, 1, 0, 1, 1, 0, -1, -1, 0, -1]),+ normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+};++const IMAGE_OPTIONS = { width: 24, height: 16, samples: 64, bounces: 3, seed: 11 };+const RESULT_PLANES = ['rgba', 'albedo', 'normal', 'depth', 'variance'];++function horizontalQuadMatrix(scale, height, facesUp) {+ const upOrDown = facesUp ? 1 : -1;+ return [scale, 0, 0, 0, 0, 0, -upOrDown * scale, 0, 0, upOrDown * scale, 0, 0, 0, height, 0, 1];+}++// A lit floor with two emissive ceiling quads, so light picking and several bounces take part.+function buildRoomScene() {+ return {+ materials: [{ color: [0.6, 0.6, 0.6], roughness: 0.8 }, { color: [1, 0.95, 0.9], emission: 5, roughness: 1 }],+ instances: [+ { geometry: UNIT_QUAD, matrix: horizontalQuadMatrix(8, 0, true), materialIndex: 0 },+ { geometry: UNIT_QUAD, matrix: horizontalQuadMatrix(2, 3, false), materialOverride: 1 },+ { geometry: UNIT_QUAD, matrix: horizontalQuadMatrix(1, 2, false), materialOverride: 1 },+ ],+ };+}++function bytesOf(result, plane) {+ const values = result[plane];+ return Buffer.from(values.buffer, values.byteOffset, values.byteLength);+}++function assertSameBytes(first, second, message) {+ for (const plane of RESULT_PLANES) {+ assert.ok(bytesOf(first, plane).equals(bytesOf(second, plane)), `${message}: the ${plane} plane differs`);+ }+}++test('the cycles kernel gives the same bytes whatever the samples per dispatch', { skip: skipWithoutAddon }, () => {+ const camera = createCamera({ eye: [0, 2.2, 6], target: [0, 0.5, 0], fov: 45 }, IMAGE_OPTIONS.width, IMAGE_OPTIONS.height);+ const input = buildNativeInputV2(buildRoomScene(), camera, IMAGE_OPTIONS);+ const traceWith = (samplesPerDispatch) => traceNative(input, { ...IMAGE_OPTIONS, kernel: 'cycles', samplesPerDispatch });+ const oneAtATime = traceWith(1);+ assert.equal(oneAtATime.samplesPerDispatch, 1);+ assert.ok(oneAtATime.rgba.every(Number.isFinite));+ for (const samplesPerDispatch of [5, 16, 64]) {+ const split = traceWith(samplesPerDispatch);+ assert.equal(split.samplesPerDispatch, samplesPerDispatch);+ assertSameBytes(oneAtATime, split, `${samplesPerDispatch} samples per dispatch against 1`);+ }+});++test('the cycles kernel gives the same bytes when adaptive sampling stops pixels early, whatever the split', { skip: skipWithoutAddon }, () => {+ const camera = createCamera({ eye: [0, 2.2, 6], target: [0, 0.5, 0], fov: 45 }, IMAGE_OPTIONS.width, IMAGE_OPTIONS.height);+ const adaptiveOptions = { ...IMAGE_OPTIONS, samples: 128, noiseThreshold: 0.05 };+ const input = buildNativeInputV2(buildRoomScene(), camera, adaptiveOptions);+ const oneAtATime = traceNative(input, { ...adaptiveOptions, kernel: 'cycles', samplesPerDispatch: 1 });+ const split = traceNative(input, { ...adaptiveOptions, kernel: 'cycles', samplesPerDispatch: 37 });+ assertSameBytes(oneAtATime, split, '37 samples per dispatch against 1 with a noise threshold');+});++test('two renders that size their own dispatches from timing give the same bytes', { skip: skipWithoutAddon }, () => {+ const camera = createCamera({ eye: [0, 2.2, 6], target: [0, 0.5, 0], fov: 45 }, IMAGE_OPTIONS.width, IMAGE_OPTIONS.height);+ const input = buildNativeInputV2(buildRoomScene(), camera, IMAGE_OPTIONS);+ const first = traceNative(input, { ...IMAGE_OPTIONS, kernel: 'cycles' });+ const second = traceNative(input, { ...IMAGE_OPTIONS, kernel: 'cycles' });+ assertSameBytes(first, second, 'two untimed-split renders');+});++test('the legacy kernel draws one sample per dispatch, so two renders give the same bytes', { skip: skipWithoutAddon }, () => {+ const camera = createCamera({ eye: [0, 1, 4], target: [0, 1, 0], fov: 50 }, IMAGE_OPTIONS.width, IMAGE_OPTIONS.height);+ const parts = [{ name: 'floor', geometry: FLOOR, material: { color: [0.5, 0.5, 0.5] } }];+ const input = buildNativeInput(buildTraceScene(parts, {}), camera, IMAGE_OPTIONS, pack);+ const first = traceNative(input, { ...IMAGE_OPTIONS, kernel: 'legacy' });+ const second = traceNative(input, { ...IMAGE_OPTIONS, kernel: 'legacy' });+ assertSameBytes(first, second, 'two legacy renders');+});