Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Match the firefly clamp across Cook backends in the tier bench (#936)

Nguyen Xuan An12fa1a94f76d
diff --git a/bench/tiers/README.md b/bench/tiers/README.md
index a310f201..8249fbc3 100644
--- a/bench/tiers/README.md
+++ b/bench/tiers/README.md
@@ -19,6 +19,8 @@ node bench/tiers/make-table.mjs <work directory>/matrix-960.json
How the equal-error statements are made: an error that is limited by noise falls as 1/N, so the relMSE at 1,024 samples is about a quarter of the one at 256. When a scene's 1,024-sample error is above 0.4 times its 256-sample error, `make-table.mjs` calls it bias-limited and prints the measured values without a ratio; it does the same when the Cycles 256-sample error that serves as the target is itself bias-limited. A ratio is extrapolated only from 1,024 samples and only on the other scenes. Cook webgpu was measured at 256 samples only, so it gets its per-sample speed against native and the difference between its image and native's at equal samples, never an equal-error figure.
+Firefly clamp (#936): the committed matrix ran Cook native with `fireflyClamp` 1e9 and Cook webgpu with 1000 (the cap of the JS API), so the linear relMSE of the two is not comparable on scenes with fireflies. On `metal` at 256 samples native at 1e9 measured 2.02 and at 1000 measured 0.02107, webgpu at 1000 measured 0.02106: the same kernel code and the same pixels, 10 pixels carry 97 percent of the 1e9 error. Cycles (clamps off) has the same shape: 10 pixels carry 98 percent of its 0.0298. `run-all.mjs` now passes one `--firefly-clamp` (default 1000) to every Cook backend and records it in each cell. Read linear relMSE on firefly scenes with that clamp in mind; display relMSE and FLIP are not affected. Rerun the matrix to refresh the committed figures.
+
The table below this section, and the equal-error section after it, are the earlier single-scene result, measured on a shared card. Where they disagree with the matrix, the matrix is right; their equal-error figures extrapolated as 1/N without the check above.
## Result (lit-interior, shared card, 2026-11-11)
diff --git a/bench/tiers/run-all.mjs b/bench/tiers/run-all.mjs
index ec8eb2dc..8ebc1090 100644
--- a/bench/tiers/run-all.mjs
+++ b/bench/tiers/run-all.mjs
@@ -34,6 +34,8 @@ const reportOnly = flagPresent('--report-only');
const resultsPath = resolve(valueAfter('--results', join(workDirectory, `matrix-${width}.json`)));
const blenderBinary = process.env.BLENDER_BIN ?? 'C:/Program Files/Blender Foundation/Blender 5.3/blender.exe';
const skipScoring = flagPresent('--no-score');
+// Cook native, webgpu, gpu and cpu all get this firefly clamp. 1000 is the cap of the JS API, so it is the only value every backend accepts (#936).
+const fireflyClamp = Number(valueAfter('--firefly-clamp', 1000));
const BASE_ORDER = ['glaze-draft', 'glaze-realtime', 'eevee-lowest', 'eevee-default', 'cook-native', 'cycles', 'cook-webgpu'];
const OPTIONAL_ORDER = [flagPresent('--with-cook-gpu') ? 'cook-gpu' : null, flagPresent('--with-cook-cpu') ? 'cook-cpu' : null].filter(Boolean);
@@ -135,7 +137,7 @@ function planCell(scene, sceneJson, engine, samples, repetition, directory) {
}
if (engine === 'cook-native' || engine === 'cycles') {
const traceCommand = engine === 'cook-native'
- ? ['node', 'bench/cycles-parity/trace-native.mjs', sceneJson, prefix, '--samples', String(samples), '--bounces', '8', '--seed', '1', '--firefly-clamp', '1000000000', '--noise-threshold', '0']
+ ? ['node', 'bench/cycles-parity/trace-native.mjs', sceneJson, prefix, '--samples', String(samples), '--bounces', '8', '--seed', '1', '--firefly-clamp', String(fireflyClamp), '--noise-threshold', '0']
: [blenderBinary, '-b', '--factory-startup', '--python', 'bench/cycles-parity/render-cycles.py', '--', sceneJson, prefix, '--samples', String(samples), '--bounces', '8', '--seed', '1', '--width', String(width), '--height', String(height)];
return {
command: measuredCommand(prefix, traceCommand),
@@ -144,7 +146,7 @@ function planCell(scene, sceneJson, engine, samples, repetition, directory) {
const processMetrics = await readJson(`${prefix}.metrics.json`);
return {
metrics: {
- samples, samplingSeconds: report.samplingSeconds, totalTraceSeconds: report.totalTraceSeconds, perSampleMilliseconds: (report.samplingSeconds / samples) * 1000,
+ samples, fireflyClamp: engine === 'cook-native' ? fireflyClamp : null, samplingSeconds: report.samplingSeconds, totalTraceSeconds: report.totalTraceSeconds, perSampleMilliseconds: (report.samplingSeconds / samples) * 1000,
primaryMilliseconds: report.samplingSeconds * 1000, primaryName: 'sampling, all samples',
processWallSeconds: processMetrics.wallSeconds, cardDeltaMebibytes: processMetrics.peakVramDeltaMegabytes, peakRamMegabytes: processMetrics.peakRamMegabytes,
},
@@ -165,7 +167,7 @@ function planCell(scene, sceneJson, engine, samples, repetition, directory) {
return {
metrics: {
samples, samplingSeconds, totalTraceSeconds: report.report.tracedSeconds, compileSeconds, perSampleMilliseconds: (samplingSeconds / samples) * 1000,
- primaryMilliseconds: samplingSeconds * 1000, primaryName: 'sampling, all samples', cardDeltaMebibytes: report.card.deltaMebibytes,
+ primaryMilliseconds: samplingSeconds * 1000, primaryName: 'sampling, all samples', cardDeltaMebibytes: report.card.deltaMebibytes, fireflyClamp: 1000,
},
image: { path: `${cookPrefix}.npy`, kind: 'linear-npy' },
};
diff --git a/bench/tiers/run-cook.mjs b/bench/tiers/run-cook.mjs
index 2d1cfe57..da03bd7e 100644
--- a/bench/tiers/run-cook.mjs
+++ b/bench/tiers/run-cook.mjs
@@ -1,7 +1,7 @@
// Cook (the path tracer) with the cpu, gpu (WebGL2) and webgpu backends on a reference scene, at a ladder of sample counts, in headless Chrome.
// [${GPU_LOCK}] node bench/tiers/run-cook.mjs <output directory> <scene> --backend cpu|gpu|webgpu --samples 16,64,256 [--repetitions 3] [--width 960] [--height 540] [--threads 8]
// Files: <scene>-cook-<backend>-s<samples>-r<n>.npy (linear RGB float32, rows from the top, as the Cycles script writes) and .json (the tracer's report,
-// wall time, and the card memory polled around the trace). Settings: 8 bounces, seed 1, no denoiser, fireflyClamp 1e9, noiseThreshold 0.
+// wall time, and the card memory polled around the trace). Settings: 8 bounces, seed 1, no denoiser, fireflyClamp 1000 (the JS API cap; page.js).
import { execFile } from 'node:child_process';
import { mkdir, writeFile } from 'node:fs/promises';
import { constants, setPriority } from 'node:os';
diff --git a/tests/cook-kernel-parity.test.js b/tests/cook-kernel-parity.test.js
new file mode 100644
index 00000000..96591e78
--- /dev/null
+++ b/tests/cook-kernel-parity.test.js
@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+import { MEGAKERNEL_SOURCE } from '../src/path-tracer-webgpu-kernel.js';
+
+const NATIVE_KERNEL_SOURCE = readFileSync(new URL('../packages/render-native/src/kernel.wgsl', import.meta.url), 'utf8');
+
+// The metal lobe (specular colour, visible normal sampling, masking, the microfacet term) and the firefly clamp.
+// Cook native and Cook webgpu must give the same error on the metal reference scene at the same clamp (#936).
+const SHARED_FUNCTIONS = [
+ 'schlick',
+ 'schlickColor',
+ 'smithMasking',
+ 'ggxDistribution',
+ 'roughnessToAlpha',
+ 'sampleVisibleNormal',
+ 'microfacetTerm',
+ 'dielectricSpecularAlbedo',
+ 'evaluateSurface',
+ 'sampleSurface',
+ 'mirrorWeight',
+ 'addRadiance',
+];
+
+function extractFunction(source, name) {
+ const start = source.indexOf(`\nfn ${name}(`) + 1;
+ assert.notEqual(start, 0, `fn ${name} is missing`);
+ const firstBrace = source.indexOf('{', start);
+ let depth = 0;
+ for (let index = firstBrace; index < source.length; index += 1) {
+ if (source[index] === '{') depth += 1;
+ if (source[index] === '}') depth -= 1;
+ if (depth === 0) return source.slice(start, index + 1).replace(/\s+/g, ' ');
+ }
+ throw new Error(`fn ${name} is not closed`);
+}
+
+for (const name of SHARED_FUNCTIONS) {
+ test(`${name} is the same WGSL in Cook native and Cook webgpu`, () => {
+ assert.equal(extractFunction(MEGAKERNEL_SOURCE, name), extractFunction(NATIVE_KERNEL_SOURCE, name));
+ });
+}
+
+test('both kernels clamp only the radiance of bounces after the first, by the same peak rule', () => {
+ const clamp = extractFunction(NATIVE_KERNEL_SOURCE, 'addRadiance');
+ assert.match(clamp, /if \(depth > 0\)/);
+ assert.match(clamp, /amount \*= params\.cameraAndClamp\.z \/ peak/);
+});
+
+test('the tier bench gives every Cook backend the same firefly clamp and records it', () => {
+ const driver = readFileSync(new URL('../bench/tiers/run-all.mjs', import.meta.url), 'utf8');
+ assert.match(driver, /'--firefly-clamp', String\(fireflyClamp\)/);
+ assert.match(driver, /fireflyClamp: 1000/);
+ assert.doesNotMatch(driver, /1000000000/);
+});