3D engine that AI agents drive
Account for the whole cold first draw and guard every kernel's size (#861)
Nguyen Xuan An9c15689726ec
diff --git a/bench/reference/cold-draw.mjs b/bench/reference/cold-draw.mjsindex a7587adc..07da3335 100644--- a/bench/reference/cold-draw.mjs+++ b/bench/reference/cold-draw.mjs@@ -1,4 +1,4 @@-// Splits the first path traced draw of a fresh page into phases (issue #861). One fresh browser page per run, so nothing is warm.+// Splits the first path traced draw of a fresh page into phases (issue #861). One fresh browser per run, so nothing is warm.// node bench/reference/cold-draw.mjs <scene id or recipe.json> [--runs 1] [--width 960] [--height 540]// Run it behind the GPU lock (the card is held for minutes), for example with GPU_LOCK_WEIGHT=heavy.import { readFile } from 'node:fs/promises';@@ -18,19 +18,24 @@ setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);const server = await createServer({ server: { host: '127.0.0.1', port: 0, fs: { strict: false } }, logLevel: 'silent' });await server.listen();const serverUrl = `http://127.0.0.1:${server.httpServer.address().port}`;-const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding'] });try {for (let run = 0; run < runs; run++) {+ // A fresh browser per run: pages of one browser share the driver program cache, so a later page would start warm.+ const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding'] });const page = await browser.newPage({ viewport: { width: 960, height: 540 } });page.on('pageerror', error => console.log('PAGE ERROR', error.message));page.setDefaultTimeout(0);await page.goto(`${serverUrl}/bench/reference/harness.html`, { timeout: 180000 });await page.waitForFunction(() => window.profileColdFirstDraw, null, { timeout: 180000 });+ const wallStart = performance.now();const result = await page.evaluate(([scene, tracerOptions]) => window.profileColdFirstDraw(scene, tracerOptions), [source, options]);+ // The phases must add up to the wall time of the call within 5 s (issue #861); the gap is time spent outside a named phase.+ result.wallSeconds = Number(((performance.now() - wallStart) / 1000).toFixed(2));+ const allPhases = Object.values(result.phases).reduce((sum, seconds) => sum + seconds, 0);+ result.unexplainedSeconds = Number((result.wallSeconds - allPhases).toFixed(2));console.log(JSON.stringify(result));- await page.close();+ await browser.close();}} finally {- await browser.close();await server.close();}diff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex d097f834..47a1e462 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -205,3 +205,5 @@ WebGPU backend, same setup (2026-11-09, `--backend webgpu`, median of 200 frames### Cold first draw (issue #861)The first path traced draw of a fresh page on the `gpu` backend took 108 s for one sample of `lit-interior` (960 by 540, RTX 3060, ANGLE on Direct3D 11, a profile with no shader cache, `bench/reference/cold-draw.mjs`). All of it was the driver building the kernel: scene load, BVH, packing and texture upload together took 0.15 s, linking took 73.9 s and the first dispatch another 34.1 s (the driver finishes its work on first use), while every later draw took 7 to 35 ms. The compiler inlines each call, and `addLights` called the emitter sampling and the shadow ray from four places, so the traversal was built five times. `addLights` now has one loop for "every emitter" and "one chosen emitter" and the kernel holds one shadow ray (`tests/path-tracer-gpu-kernel-size.test.js` counts the call sites of each variant and the size of the plain kernel). After the change three cold runs on the loaded machine took 27.4, 35.6 and 46.6 s (15.6 to 25.4 s linking, 11.6 to 21.1 s first dispatch), and the old and new kernels compiled side by side in one page took 36 and 7.8 s, 23 and 6.5 s. The progressive tracer at 320 by 180 first step with the random, importance and tree kernels went from 22.9, 18.5 and 38.7 s to 10.3, 9.2 and 14.1 s. The cold first draw is not yet reliably under 30 s: the two places that trace rays (the camera path and the shadow ray) are still two copies of the traversal, and merging them is the next cut. The images of `lit-interior` and `spot-area` at 1, 4 and 8 samples with the random, importance and tree kernels are byte for byte the same as before (18 PNGs, MD5). A second page of the same browser session starts in 0.14 s, since the driver program cache is shared, and the compiled kernel is kept per page by `getKernel`. The `webgpu` backend compiles its kernel in about 0.5 s.++Measured after the merge, three cold runs of `lit-interior` at 960 by 540, each in a fresh browser behind the GPU lock (`bench/reference/cold-draw.mjs lit-interior --runs 3`; the bench starts one browser per run, since pages of one browser share the driver program cache and a later page starts in 0.1 s): the wall time of the call was 9.56, 9.54 and 10.17 s. Link and wait for completion took 4.06 to 4.32 s, the first dispatch with its readback 5.35 to 5.76 s, and every other named phase (scene load, module import, trace scene and BVH, context, source, compile and link submit, scene and texture upload, uniforms and targets) added up to 0.04 s. The named phases cover the wall time to within 0.06 s (the bench prints `wallSeconds` and `unexplainedSeconds`). The kernel is 45 KB, one program per scene. `tests/path-tracer-gpu-kernel-size.test.js` now holds a source size limit for each of the eight kernel variants, one `main` per kernel and one place that builds a program, so a larger kernel or a second program fails the test.diff --git a/tests/path-tracer-gpu-kernel-size.test.js b/tests/path-tracer-gpu-kernel-size.test.jsindex 4a70894c..06fc0100 100644--- a/tests/path-tracer-gpu-kernel-size.test.js+++ b/tests/path-tracer-gpu-kernel-size.test.js@@ -1,4 +1,5 @@import assert from 'node:assert/strict';+import { readFileSync } from 'node:fs';import test from 'node:test';import { buildFragmentSource } from '../src/path-tracer-gpu-shader.js';@@ -34,7 +35,21 @@ for (const [name, variant] of Object.entries(VARIANTS)) {});}-test('the plain kernel stays under its source size', () => {- const kilobytes = buildFragmentSource().length / 1024;- assert.ok(kilobytes < 48, `the plain kernel is ${kilobytes.toFixed(1)} KB; it was 46 KB when the cold first draw measured 27 s`);+// Measured source sizes in KB (plain 45.3, subsurface 50.3, texelBake 45.5, blueNoise 45.3, importance 45.3, tree 49.5, radianceCache 47.4,+// everything 56.4); each limit leaves about 1.5 KB. The plain kernel measured 27 s cold at 46 KB.+const SIZE_LIMIT_KILOBYTES = { plain: 47, subsurface: 52, texelBake: 47, blueNoise: 47, importance: 47, tree: 51, radianceCache: 49, everything: 58 };++for (const [name, variant] of Object.entries(VARIANTS)) {+ test(`the ${name} kernel stays under its source size`, () => {+ const kilobytes = buildFragmentSource(variant).length / 1024;+ assert.ok(kilobytes < SIZE_LIMIT_KILOBYTES[name], `the ${name} kernel is ${kilobytes.toFixed(1)} KB, limit ${SIZE_LIMIT_KILOBYTES[name]} KB; measure bench/reference/cold-draw.mjs before raising it`);+ });+}++test('one scene links one kernel: the gpu backend builds a program from one place and every kernel has one main', () => {+ const backend = readFileSync(new URL('../src/path-tracer-gpu.js', import.meta.url), 'utf8');+ assert.equal(backend.match(/= createProgram\(gl,/g).length, 1, 'createProgram(gl, variant) is called from one place');+ for (const variant of Object.values(VARIANTS)) {+ assert.equal(buildFragmentSource(variant).match(/void main\s*\(/g).length, 1);+ }});