3D engine that AI agents drive
Make pathRegeneration the default of the cycles kernel (#897)
Nguyen Xuan An2ff721a0aff1
diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjsindex 457390f8..d983a3fd 100644--- a/bench/cycles-parity/trace-native.mjs+++ b/bench/cycles-parity/trace-native.mjs@@ -102,7 +102,7 @@ function parseLightSamplingOption(argumentList) {function 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] [--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] [--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] [--grey-diffuse] [--write-depth]');}return {sceneJsonPath: resolve(argumentList[0]),@@ -123,7 +123,8 @@ function parseTraceArguments(argumentList) {envCompensation: parseNumberOption(argumentList, '--env-compensation', 0, 0),directLighting: String(readFlagValue(argumentList, '--direct-lighting', 'both')),lightTreeProbe: argumentList.includes('--light-tree-probe'),- pathRegeneration: argumentList.includes('--path-regeneration'),+ // On by default; `--path-regeneration` stays accepted for old command lines.+ pathRegeneration: !argumentList.includes('--no-path-regeneration'),filterWidth: parseNumberOption(argumentList, '--filter-width', 1.0, 0.01),clampDirect: parseNumberOption(argumentList, '--clamp-direct', 0, 0),clampIndirect: parseNumberOption(argumentList, '--clamp-indirect', 0, 0),diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjsindex 8b212e9d..f1014add 100644--- a/packages/render-native/index.mjs+++ b/packages/render-native/index.mjs@@ -65,6 +65,9 @@ export function resolveNativeKernel(kernel) {return selectedKernel;}+// The `cycles` kernel starts a pixel's next sample as soon as a path ends unless the caller passes `pathRegeneration: false`.+const DEFAULT_PATH_REGENERATION = true;+/*** Traces the input on the GPU and resolves linear RGBA float data (`rgba`, width * height * 4, rows from the top, the* average of `samples` paths) with the adapter name and timings in seconds. `maxSeconds` makes the trace fail once it has@@ -72,7 +75,7 @@ export function resolveNativeKernel(kernel) {*/export function traceNative(input, options = {}) {validatePackOptions(options, 'traceNative', true);- const { sampler, lightSampling } = resolveSamplingOptions(options, 'traceNative');+ resolveSamplingOptions(options, 'traceNative');validatePathRegenerationOption(options.pathRegeneration, 'traceNative');const { width, height, samples, maxSeconds, kernel, samplesPerDispatch, bootstrapKernel, denoise } = options;const selectedKernel = resolveNativeKernel(kernel);@@ -88,29 +91,7 @@ export function traceNative(input, options = {}) {}return addon.traceScene(input, { width, height, samples, maxSeconds, kernel: selectedKernel });}- let v2Input = input?.schemaVersion === FORMAT_V2_VERSION- ? input- : upgradeNativeInputV1ToV2(input, options);- const explicitFilterGlossy = options.filterGlossy ?? options.blurGlossy;- if (input?.schemaVersion === FORMAT_V2_VERSION && explicitFilterGlossy !== undefined) {- const rawFilterGlossy = Number(explicitFilterGlossy);- const resolvedFilterGlossy = Number.isFinite(rawFilterGlossy) && rawFilterGlossy > 0 ? rawFilterGlossy : 0.0;- const patchedParams = new Uint8Array(v2Input.kernelParams);- new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength).setFloat32(KERNEL_PARAMS_V2_FILTER_GLOSSY_BYTE_OFFSET, resolvedFilterGlossy, true);- v2Input = { ...v2Input, kernelParams: patchedParams };- }- if (input?.schemaVersion === FORMAT_V2_VERSION && hasFilterOptions(options)) {- v2Input = { ...v2Input, kernelParams: withFilterOptions(v2Input.kernelParams, options) };- }- if (input?.schemaVersion === FORMAT_V2_VERSION && sampler !== undefined) {- v2Input = { ...v2Input, kernelParams: withSamplerFlag(v2Input.kernelParams, sampler) };- }- if (input?.schemaVersion === FORMAT_V2_VERSION && options.pathRegeneration !== undefined) {- v2Input = { ...v2Input, kernelParams: withPathRegenerationFlag(v2Input.kernelParams, options.pathRegeneration) };- }- if (input?.schemaVersion === FORMAT_V2_VERSION && lightSampling !== undefined) {- v2Input = { ...v2Input, kernelParams: withLightSamplingFlag(v2Input, lightSampling) };- }+ const v2Input = prepareCyclesInput(input, options);return addon.traceSceneCycles(v2Input, {width,height,@@ -200,6 +181,39 @@ function withSamplerFlag(kernelParams, sampler) {return patchedParams;}+/**+ * Builds the FORMAT-v2 input of the `cycles` kernel from a v1 or v2 input and the trace options, patching the kernel flags+ * the options set. Exported for tests; not part of the public API.+ */+export function prepareCyclesInput(input, options = {}) {+ const { sampler, lightSampling } = resolveSamplingOptions(options, 'traceNative');+ let v2Input = input?.schemaVersion === FORMAT_V2_VERSION+ ? input+ : upgradeNativeInputV1ToV2(input, options);+ const explicitFilterGlossy = options.filterGlossy ?? options.blurGlossy;+ if (input?.schemaVersion === FORMAT_V2_VERSION && explicitFilterGlossy !== undefined) {+ const rawFilterGlossy = Number(explicitFilterGlossy);+ const resolvedFilterGlossy = Number.isFinite(rawFilterGlossy) && rawFilterGlossy > 0 ? rawFilterGlossy : 0.0;+ const patchedParams = new Uint8Array(v2Input.kernelParams);+ new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength).setFloat32(KERNEL_PARAMS_V2_FILTER_GLOSSY_BYTE_OFFSET, resolvedFilterGlossy, true);+ v2Input = { ...v2Input, kernelParams: patchedParams };+ }+ if (input?.schemaVersion === FORMAT_V2_VERSION && hasFilterOptions(options)) {+ v2Input = { ...v2Input, kernelParams: withFilterOptions(v2Input.kernelParams, options) };+ }+ if (input?.schemaVersion === FORMAT_V2_VERSION && sampler !== undefined) {+ v2Input = { ...v2Input, kernelParams: withSamplerFlag(v2Input.kernelParams, sampler) };+ }+ v2Input = {+ ...v2Input,+ kernelParams: withPathRegenerationFlag(v2Input.kernelParams, options.pathRegeneration ?? DEFAULT_PATH_REGENERATION),+ };+ if (input?.schemaVersion === FORMAT_V2_VERSION && lightSampling !== undefined) {+ v2Input = { ...v2Input, kernelParams: withLightSamplingFlag(v2Input, lightSampling) };+ }+ return v2Input;+}+// Exported for tests; not part of the public API.export function withPathRegenerationFlag(kernelParams, pathRegeneration) {const patchedParams = new Uint8Array(kernelParams);diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex dd2d2940..7a73d5a8 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -1632,7 +1632,7 @@ export function resolveSamplingOptions(options, callerName) {export function validatePathRegenerationOption(pathRegeneration, callerName) {if (pathRegeneration !== undefined && typeof pathRegeneration !== 'boolean') {throw new TypeError(- `${callerName}: \`pathRegeneration\` must be true, false (default) or left out, got ${JSON.stringify(pathRegeneration)}.`+ `${callerName}: \`pathRegeneration\` must be true, false or left out (the "cycles" kernel defaults to true), got ${JSON.stringify(pathRegeneration)}.`);}}diff --git a/tests/native-path-regeneration.test.js b/tests/native-path-regeneration.test.jsindex 59e195a6..56772c9f 100644--- a/tests/native-path-regeneration.test.js+++ b/tests/native-path-regeneration.test.js@@ -1,12 +1,21 @@import assert from 'node:assert/strict';import test from 'node:test';-import { withPathRegenerationFlag } from '../packages/render-native/index.mjs';+import {+ buildNativeInput,+ buildNativeInputV2,+ prepareCyclesInput,+ traceNative,+ withPathRegenerationFlag,+} from '../packages/render-native/index.mjs';import {KERNEL_FLAG_PATH_REGENERATION,KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET,STRUCT_STRIDES_V2,validatePathRegenerationOption,} from '../packages/render-native/pack-input-v2.mjs';+import { createCamera } from '../src/path-tracer.js';+import * as pack from '../src/path-tracer-gpu-pack.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';function readKernelFlags(kernelParams) {const view = new DataView(kernelParams.buffer, kernelParams.byteOffset, kernelParams.byteLength);@@ -38,3 +47,62 @@ test('pathRegeneration accepts true, false and undefined, and rejects anything eassert.throws(() => validatePathRegenerationOption('on', 'caller'), /`pathRegeneration` must be true, false/);assert.throws(() => validatePathRegenerationOption(1, 'caller'), TypeError);});++function makeCardScene() {+ const parts = [{+ name: 'card',+ geometry: {+ 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]),+ },+ material: { color: [0.6, 0.5, 0.4], roughness: 0.7 },+ }];+ const scene = buildTraceScene(parts, {});+ const camera = createCamera({ eye: [0, 0, 4], target: [0, 0, 0], fov: 45 }, 16, 16);+ return { scene, camera };+}++const traceOptions = { width: 16, height: 16, samples: 1 };++test('the cycles kernel turns path regeneration on unless the caller says false', () => {+ const { scene, camera } = makeCardScene();+ const v2Input = buildNativeInputV2(scene, camera, traceOptions);+ assert.equal(readKernelFlags(v2Input.kernelParams) & KERNEL_FLAG_PATH_REGENERATION, 0, 'the packer leaves the flag to traceNative');++ const byDefault = prepareCyclesInput(v2Input, traceOptions);+ assert.equal(readKernelFlags(byDefault.kernelParams) & KERNEL_FLAG_PATH_REGENERATION, KERNEL_FLAG_PATH_REGENERATION);++ const explicitTrue = prepareCyclesInput(v2Input, { ...traceOptions, pathRegeneration: true });+ assert.equal(readKernelFlags(explicitTrue.kernelParams), readKernelFlags(byDefault.kernelParams));++ const explicitFalse = prepareCyclesInput(v2Input, { ...traceOptions, pathRegeneration: false });+ assert.equal(readKernelFlags(explicitFalse.kernelParams) & KERNEL_FLAG_PATH_REGENERATION, 0);+ assert.equal(+ readKernelFlags(explicitFalse.kernelParams) | KERNEL_FLAG_PATH_REGENERATION,+ readKernelFlags(byDefault.kernelParams),+ 'false clears only the regeneration bit'+ );+});++test('a v1 input upgraded for the cycles kernel also defaults to path regeneration and honours false', () => {+ const { scene, camera } = makeCardScene();+ const v1Input = buildNativeInput(scene, camera, traceOptions, pack);+ const byDefault = prepareCyclesInput(v1Input, traceOptions);+ const explicitFalse = prepareCyclesInput(v1Input, { ...traceOptions, pathRegeneration: false });+ assert.equal(readKernelFlags(byDefault.kernelParams) & KERNEL_FLAG_PATH_REGENERATION, KERNEL_FLAG_PATH_REGENERATION);+ assert.equal(readKernelFlags(explicitFalse.kernelParams) & KERNEL_FLAG_PATH_REGENERATION, 0);+});++test('the legacy kernel ignores pathRegeneration and still refuses a FORMAT-v2 input', () => {+ const { scene, camera } = makeCardScene();+ const v2Input = buildNativeInputV2(scene, camera, traceOptions);+ for (const pathRegeneration of [undefined, true, false]) {+ assert.throws(+ () => traceNative(v2Input, { ...traceOptions, kernel: 'legacy', pathRegeneration }),+ /Cannot pass a FORMAT-v2 scene input to kernel "legacy"|native tracer is not built/+ );+ }+});