Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.mjs
index 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.mjs
index 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.mjs
index 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.js
index 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 e
assert.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/
+ );
+ }
+});