3D engine that AI agents drive
Name the cause of the GPU bake's extra light and pin the backends' agreement (closes #412)
Nguyen Xuan An80f37425abf3
diff --git a/docs/light-bake.md b/docs/light-bake.mdindex 003929d2..78f119ba 100644--- a/docs/light-bake.md+++ b/docs/light-bake.md@@ -47,7 +47,7 @@ import { bakeLightmapsAsync } from '67js/addons/light-bake-gpu';const { parts: bakedParts, report } = await bakeLightmapsAsync(parts, lighting, { backend: 'gpu', samples: 512, bounces: 2 });```-`backend` is `cpu` (the default and the reference) or `gpu`, named as for the path tracer's `backend`. `bakeLightmapsAsync` takes the same arguments and options as `bakeLightmaps` and resolves with the same `{ parts, report }`; the synchronous `bakeLightmaps` throws a `TypeError` for `gpu` and names this addon. A GPU bake rasterizes the texels as the CPU bake does, then sends all covered texels of all parts to the path tracer's kernel in one batch (`src/light-bake-gpu.js`, `src/path-tracer-gpu.js`): the kernel starts a cosine weighted path at each texel, follows `bounces` hits with the tracer's own lights, materials and maps, and returns the light that arrives. The albedo, smoothing, dilation, sky visibility and the baked parts then come from the same code as on the CPU. It is its own addon (`67js/addons/light-bake-gpu`), so the CPU bake and the core bundle do not carry it. It needs a page with WebGL2 and float render targets (`EXT_color_buffer_float`, `EXT_float_blend`) and throws without them. It takes up to 1,024 parts where the CPU bake takes 256 (`MAX_GPU_BAKE_PARTS`; the texel and ray work limits are the same). It does not take a light with `affects` (the kernel has no light linking) or `skyOnly`, and `report` adds `gpu` and `gpuCompileSeconds` (the kernel compiles once per page). The GPU result is not byte identical to the CPU one: the CPU gatherer treats every part as a diffuse surface, while the kernel also follows specular lobes, clear coat and glass, and it draws other random numbers.+`backend` is `cpu` (the default and the reference) or `gpu`, named as for the path tracer's `backend`. `bakeLightmapsAsync` takes the same arguments and options as `bakeLightmaps` and resolves with the same `{ parts, report }`; the synchronous `bakeLightmaps` throws a `TypeError` for `gpu` and names this addon. A GPU bake rasterizes the texels as the CPU bake does, then sends all covered texels of all parts to the path tracer's kernel in one batch (`src/light-bake-gpu.js`, `src/path-tracer-gpu.js`): the kernel starts a cosine weighted path at each texel, follows `bounces` hits with the tracer's own lights, materials and maps, and returns the light that arrives. The albedo, smoothing, dilation, sky visibility and the baked parts then come from the same code as on the CPU. It is its own addon (`67js/addons/light-bake-gpu`), so the CPU bake and the core bundle do not carry it. It needs a page with WebGL2 and float render targets (`EXT_color_buffer_float`, `EXT_float_blend`) and throws without them. It takes up to 1,024 parts where the CPU bake takes 256 (`MAX_GPU_BAKE_PARTS`; the texel and ray work limits are the same). It does not take a light with `affects` (the kernel has no light linking) or `skyOnly`, and `report` adds `gpu` and `gpuCompileSeconds` (the kernel compiles once per page). The GPU result is not byte identical to the CPU one: the CPU gatherer treats every part as a diffuse surface, while the kernel also follows specular lobes, clear coat and glass, and it draws other random numbers. On a room of diffuse surfaces the two agree to about 1 percent; a rough dielectric adds about 3 percent of light on the GPU and a glossy floor about 5 (see "Why the GPU light is brighter").The bake traces cosine-weighted paths from each texel through up to `bounces` reflections. Each hit adds its own emission and the direct light it receives from the point lights and the sun, with shadow rays. A texel stores that light times its own albedo. Direct light is not baked: it stays live, so shadows and moving lights keep working. The stored light is only what has bounced at least once, so a scene needs the same lights at run time that it gave the bake.@@ -120,4 +120,19 @@ The `lit-interior` reference scene (25,648 texels at the defaults) bakes in abou| GPU | 128 | 11.1 M | 0.26 | 1.049 | 0.056 || GPU | 512 | 44.2 M | 0.70 | 1.054 | 0.055 |-The recipe preset `standard` resolves to 81 samples, 3 bounces and 4.86 texels per unit on this scene (4.7 M path steps, 1.7 s on the CPU), so the GPU bake at 512 samples runs 9.4 times those path steps in 0.70 s. The kernel compiles once per page and that takes 7.4 s, which comes on top of the first GPU bake of a page (a cold `run.mjs` row measured 32 s for the bake with the compile, other sessions using the machine). The GPU light is about 5 percent above the CPU's and the gap does not shrink with samples (0.056 at 128, 0.055 at 512, against 0.018 for the CPU's own noise at 128), so it is a bias, not noise; the likely cause (inferred, not isolated) is that the CPU gatherer treats every part as a diffuse surface, while the kernel also traces the specular lobe of a rough dielectric. Score of the baked `lit-interior` against Cycles (FLIP, 960 by 540, same Cycles frame): CPU bake 0.1129, GPU bake at 512 samples 0.0914.+The recipe preset `standard` resolves to 81 samples, 3 bounces and 4.86 texels per unit on this scene (4.7 M path steps, 1.7 s on the CPU), so the GPU bake at 512 samples runs 9.4 times those path steps in 0.70 s. The kernel compiles once per page and that takes 7.4 s, which comes on top of the first GPU bake of a page (a cold `run.mjs` row measured 32 s for the bake with the compile, other sessions using the machine). The GPU light is about 5 percent above the CPU's and the gap does not shrink with samples (0.056 at 128, 0.055 at 512, against 0.018 for the CPU's own noise at 128), so it is a bias, not noise. Its cause is the specular lobe, which the two backends model differently on purpose (see "Why the GPU light is brighter" below). Score of the baked `lit-interior` against Cycles (FLIP, 960 by 540, same Cycles frame): CPU bake 0.1129, GPU bake at 512 samples 0.0914.++#### Why the GPU light is brighter (issue #412)++Measured 2026-11-04 on a closed 8 m room with one lamp (6 walls, 4,098 to 1,836 texels each, `texelsPerUnit` 8, 3 bounces, RTX 3060). Light summed over all texels, GPU divided by CPU:++| Surfaces | GPU / CPU | Bounces and samples |+| --- | --- | --- |+| diffuse only (`ior` 1, no specular lobe) | 1.006 (floor 1.003, ceiling 1.001, walls 1.008 to 1.011) | 3 bounces, 512 samples |+| diffuse only, direct light of the first hit | 1.006 (floor 1.001, ceiling 1.000, walls 1.012 to 1.019) | 1 bounce, 512 samples |+| rough dielectric walls (`roughness` 1, default `ior` 1.5) | 1.029 (1.018 to 1.051 by part) | 3 bounces, 128 samples |+| the same with a glossy floor (`roughness` 0.25) | 1.048 (1.025 to 1.087 by part) | 3 bounces, 128 samples |++The CPU gatherer treats every part as a Lambertian surface of its diffuse albedo. The kernel evaluates the tracer's own material: the diffuse part shrinks by the Fresnel share and the specular lobe (a GGX lobe of F0 0.04 at the default `ior`, the colour for a metal) reflects light from the other surfaces towards the texel. With the lobe switched off the two backends agree to 0.6 percent over the room; the 0.1 to 1.9 percent that is left sits on the walls, not on floor and ceiling, does not move with the lamp radius (0.05 or 0.001), and is not isolated. Every other suspect from #412 was ruled out by that diffuse-only room: the first bounce's cosine weighting, emission and sky (neither is present), the bounce count (both follow `bounces` hits), and Russian roulette (starts after the third hit, so it never runs at 3 bounces or fewer). A texel offset or normal that was wrong would show on the diffuse room too, and it does not beyond the residual above.++Both are right for their own model. The GPU light is the one a path tracer such as Cycles also sees, which is why it scores nearer to Cycles on `lit-interior` (0.0914 against 0.1129); the CPU light is the diffuse-only reference. Use the CPU backend for a lightmap with no light from specular surfaces, and the GPU backend when rooms hold glossy floors, metal or clear coat. `tests/light-bake-backends.test.js` keeps the diffuse agreement under 1 percent and the GPU's extra light on a glossy room above 1.5 percent.diff --git a/tests/light-bake-backends.test.js b/tests/light-bake-backends.test.jsnew file mode 100644index 00000000..e74ba22f--- /dev/null+++ b/tests/light-bake-backends.test.js@@ -0,0 +1,116 @@+// The two light bake backends against each other (issue #412): on a room whose surfaces are diffuse only, the CPU gatherer and the+// GPU kernel must bring the same light to the texels. A surface with a specular lobe is where they differ on purpose (the GPU+// kernel follows the lobe, the CPU gatherer treats every part as Lambertian), and the second test pins the size of that gap.+// It runs the GPU kernel in headless Chrome (SwiftShader, no GPU) from the Vite dev server, and skips when Chrome cannot start.+import test from 'node:test';+import assert from 'node:assert/strict';+import { spawn } from 'node:child_process';++// Measured 2026-11-04 on an RTX 3060, a closed 8 m room with one lamp, 512 samples, 3 bounces: diffuse-only surfaces (ior 1)+// gave a GPU to CPU light ratio of 1.0034 on the floor, 1.0014 on the ceiling and 1.008 to 1.011 on the walls (0.6 percent over+// the room). The same room with the default ior 1.5 gave 1.029, and 1.048 with a glossy floor.+// This test's smaller room on SwiftShader (256 samples) gave 1.0046 for diffuse surfaces and 1.0766 for a glossy dielectric.+const DIFFUSE_AGREEMENT = 0.01;+const SPECULAR_GAP_AT_LEAST = 0.015;+const PORT = 5188;++async function startServer() {+ const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--host', '127.0.0.1', '--port', String(PORT), '--strictPort'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });+ await new Promise((resolve, reject) => {+ const timeout = setTimeout(() => reject(new Error('The dev server did not start.')), 30000);+ server.stdout.on('data', (data) => {+ if (/ready in/.test(data.toString())) {+ clearTimeout(timeout);+ resolve();+ }+ });+ server.on('exit', (code) => {+ clearTimeout(timeout);+ reject(new Error(`The dev server exited ${code}.`));+ });+ });+ return server;+}++// Bakes a closed room on both backends and returns GPU light divided by CPU light, summed over every texel of every part.+async function bakeRoomOnBothBackends(material) {+ const { box } = await import('/src/geometry.js');+ const { bakeLightmapsAsync } = await import('/src/light-bake-gpu.js');+ const cube = box(0, 1);+ const placed = (name, translation, scale, color) => ({+ name,+ geometry: cube,+ matrix: new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]),+ material: { tag: 'surface', metallic: 0, emission: 0, color, ...material },+ });+ const parts = [+ placed('floor', [0, -0.05, 0], [4, 0.1, 4], [0.45, 0.32, 0.22]),+ placed('ceiling', [0, 2.55, 0], [4, 0.1, 4], [0.7, 0.68, 0.62]),+ placed('back', [0, 1.25, -2.05], [4, 2.7, 0.1], [0.7, 0.68, 0.62]),+ placed('front', [0, 1.25, 2.05], [4, 2.7, 0.1], [0.7, 0.68, 0.62]),+ placed('left', [-2.05, 1.25, 0], [0.1, 2.7, 4], [0.55, 0.25, 0.2]),+ placed('right', [2.05, 1.25, 0], [0.1, 2.7, 4], [0.2, 0.35, 0.5]),+ ];+ const lighting = { pointLights: [{ position: [0, 2, -0.3], color: [1, 0.9, 0.75], intensity: 8, radius: 0.05, castShadow: true }], keyColor: [0, 0, 0], lightDirection: [0, 1, 0] };+ const options = { samples: 256, bounces: 3, texelsPerUnit: 6 };+ const radianceOf = (part) => {+ const texture = part.material.lightMap ?? part.material.emissiveMap;+ const peak = part.material.lightMap ? part.material.lightMapScale : part.material.emission;+ const bytes = texture.image.data;+ let sum = 0;+ for (let texel = 0; texel < bytes.length / 4; texel++) {+ for (let channel = 0; channel < 3; channel++) {+ const encoded = bytes[texel * 4 + channel] / 255;+ sum += (encoded <= 0.04045 ? encoded / 12.92 : ((encoded + 0.055) / 1.055) ** 2.4) * peak;+ }+ }+ return sum;+ };+ const total = (baked) => baked.parts.reduce((sum, part) => sum + radianceOf(part), 0);+ const cpu = await bakeLightmapsAsync(parts, lighting, { ...options, backend: 'cpu' });+ const gpu = await bakeLightmapsAsync(parts, lighting, { ...options, backend: 'gpu' });+ return total(gpu) / total(cpu);+}++async function withPage(context, run) {+ let chromium;+ try {+ ({ chromium } = await import('playwright'));+ } catch {+ context.skip('playwright is not installed');+ return;+ }+ const server = await startServer();+ let browser;+ try {+ try {+ browser = await chromium.launch({ headless: true, args: ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--enable-webgl', '--ignore-gpu-blocklist'] });+ } catch (error) {+ context.skip(`Chrome did not start: ${error.message.split('\n')[0]}`);+ return;+ }+ const page = await browser.newPage({ viewport: { width: 320, height: 180 } });+ page.setDefaultTimeout(0);+ await page.goto(`http://127.0.0.1:${PORT}/`);+ await run(material => page.evaluate(bakeRoomOnBothBackends, material));+ } finally {+ await browser?.close();+ server.kill();+ }+}++test('on a room of diffuse surfaces the CPU and GPU bakes bring the same light', { timeout: 600000 }, async (context) => {+ await withPage(context, async (ratioFor) => {+ const ratio = await ratioFor({ roughness: 1, ior: 1 });+ console.log(JSON.stringify({ diffuseGpuToCpu: ratio }));+ assert.ok(Math.abs(ratio - 1) < DIFFUSE_AGREEMENT, `GPU light is ${ratio} times the CPU light`);+ });+});++test('a specular lobe makes the GPU bake brighter than the CPU one, which has none', { timeout: 600000 }, async (context) => {+ await withPage(context, async (ratioFor) => {+ const ratio = await ratioFor({ roughness: 0.25, ior: 1.5 });+ console.log(JSON.stringify({ glossyGpuToCpu: ratio }));+ assert.ok(ratio - 1 > SPECULAR_GAP_AT_LEAST, `GPU light is ${ratio} times the CPU light`);+ });+});