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.mdindex 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.jsonHow 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.mjsindex 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.mjsindex 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.jsnew file mode 100644index 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/);+});