3D engine that AI agents drive
Bisect the native cutout gap: the CPU and WebGL2 shadow ray leaks light (issue #626)
Nguyen Xuan An70563f62481e
diff --git a/bench/native-tracer/cutout-bisect.mjs b/bench/native-tracer/cutout-bisect.mjsnew file mode 100644index 00000000..31166945--- /dev/null+++ b/bench/native-tracer/cutout-bisect.mjs@@ -0,0 +1,74 @@+// Bisects a native cutout difference: one disc-masked card facing the camera, lit only by its own emission (no lights, no+// bounces), so the image is the alpha silhouette. With --ground the card also hangs over a ground plane lit by a sun, which+// adds the shadow rays. Prints how many pixels native and the CPU tracer disagree on (a pixel is "on" above half brightness).+// node bench/native-tracer/cutout-bisect.mjs <output directory> [--ground] [--size 256]+import { mkdir, writeFile } from 'node:fs/promises';+import { resolve } from 'node:path';+import { buildNativeInput, traceNative } from '../../packages/render-native/index.mjs';+import { encodePng } from '../../src/export-png.js';+import * as pack from '../../src/path-tracer-gpu-pack.js';+import { createCamera, renderPathTracedImage, toneMapToRgba8 } from '../../src/path-tracer.js';+import { buildTraceScene } from '../../src/path-tracer-scene.js';++const argumentsGiven = process.argv.slice(2);+const outputDirectory = resolve(argumentsGiven[0]);+const withGround = argumentsGiven.includes('--ground');+const sizeIndex = argumentsGiven.indexOf('--size');+const size = sizeIndex >= 0 ? Number(argumentsGiven[sizeIndex + 1]) : 256;+const options = { width: size, height: size, samples: 32, bounces: 1, seed: 0, fireflyClamp: 20 };++const TEXTURE_SIZE = 64;+const data = new Uint8Array(TEXTURE_SIZE * TEXTURE_SIZE * 4);+for (let row = 0; row < TEXTURE_SIZE; row++) {+ for (let column = 0; column < TEXTURE_SIZE; column++) {+ const inside = Math.hypot((column + 0.5) / TEXTURE_SIZE - 0.5, (row + 0.5) / TEXTURE_SIZE - 0.35) < 0.4;+ data.set([255, 255, 255, inside ? 255 : 0], (row * TEXTURE_SIZE + column) * 4);+ }+}+const texture = { image: { data, width: TEXTURE_SIZE, height: TEXTURE_SIZE }, colorSpace: 'srgb', wrapS: 33071 };++function quad(corners) {+ return {+ positions: new Float32Array(corners.flat()),+ 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]),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++const cardMaterial = { color: [1, 1, 1], emissiveColor: [1, 1, 1], emission: withGround ? 0 : 1, roughness: 1, map: texture, alphaMode: 'mask', alphaCutoff: 0.5 };+const parts = [{ name: 'card', geometry: quad([[-1, 0.2, 0], [1, 0.2, 0], [1, 2.2, 0], [-1, 0.2 + 2, 0]].map((corner, index) => (index === 3 ? [-1, 2.2, 0] : corner))), material: cardMaterial }];+if (withGround) {+ const ground = quad([[-4, 0, 4], [4, 0, 4], [4, 0, -4], [-4, 0, -4]]);+ ground.normals = new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]);+ parts.push({ name: 'ground', geometry: ground, material: { color: [0.8, 0.8, 0.8], roughness: 1 } });+}+const environment = { keyColor: withGround ? [3, 3, 3] : [0, 0, 0], lightDirection: [0.3, 0.9, 0.3], pointLights: [], areaLights: [] };+const cameraDescription = withGround ? { eye: [0, 3, 5], target: [0, 0.8, 0], fov: 50 } : { eye: [0, 1.2, 4], target: [0, 1.2, 0], fov: 40 };++await mkdir(outputDirectory, { recursive: true });+const scene = buildTraceScene(parts, environment);+const camera = createCamera(cameraDescription, size, size);+const traced = traceNative(buildNativeInput(scene, camera, options, pack), options);+const linear = new Float32Array(size * size * 3);+for (let pixel = 0; pixel < size * size; pixel++) linear.set(traced.rgba.subarray(pixel * 4, pixel * 4 + 3), pixel * 3);+const native = toneMapToRgba8(linear, size, size, { viewTransform: 'aces', look: null });+const reference = (await renderPathTracedImage({ parts, environment, camera: cameraDescription }, { ...options, backend: 'cpu', denoise: false, threads: 8 })).rgba;+await writeFile(`${outputDirectory}/bisect-native${withGround ? '-ground' : ''}.png`, encodePng(native, size, size));+await writeFile(`${outputDirectory}/bisect-cpu${withGround ? '-ground' : ''}.png`, encodePng(reference, size, size));++let nativeOn = 0;+let referenceOn = 0;+let disagree = 0;+let meanDifference = 0;+for (let pixel = 0; pixel < size * size; pixel++) {+ const nativeValue = native[pixel * 4 + 1];+ const referenceValue = reference[pixel * 4 + 1];+ meanDifference += Math.abs(nativeValue - referenceValue) / 255;+ const nativeIsOn = nativeValue > 127;+ const referenceIsOn = referenceValue > 127;+ nativeOn += nativeIsOn ? 1 : 0;+ referenceOn += referenceIsOn ? 1 : 0;+ disagree += nativeIsOn === referenceIsOn ? 0 : 1;+}+console.log(JSON.stringify({ withGround, size, nativeOn, referenceOn, disagree, meanDifference: meanDifference / (size * size) }));diff --git a/bench/native-tracer/cutout.mjs b/bench/native-tracer/cutout.mjsindex 8159f8bf..060b31ad 100644--- a/bench/native-tracer/cutout.mjs+++ b/bench/native-tracer/cutout.mjs@@ -23,7 +23,7 @@ function valueAfter(flag, fallback) {const label = argumentsGiven.includes('--opaque') ? '-opaque' : argumentsGiven.includes('--solid') ? '-solid' : '';const leafCount = Number(valueAfter('--leaves', 300));const options = { width: Number(valueAfter('--width', 960)), height: Number(valueAfter('--height', 540)),- samples: Number(valueAfter('--samples', 64)), bounces: 4, seed: 0, fireflyClamp: 20 };+ samples: Number(valueAfter('--samples', 64)), bounces: Number(valueAfter('--bounces', 4)), seed: 0, fireflyClamp: 20 };import { CUTOUT_CAMERA, CUTOUT_ENVIRONMENT, buildCutoutParts } from './cutout-scene.js';diff --git a/bench/native-tracer/run.mjs b/bench/native-tracer/run.mjsindex cdccdb4a..047b7238 100644--- a/bench/native-tracer/run.mjs+++ b/bench/native-tracer/run.mjs@@ -50,7 +50,7 @@ const traceStarted = performance.now();const result = traceNative(input, options);const wallSeconds = (performance.now() - traceStarted) / 1000;-const { rgba, ...numbers } = result;+const { rgba, albedo, normal, depth, variance, ...numbers } = result;const linear = new Float32Array(options.width * options.height * 3);for (let pixel = 0; pixel < options.width * options.height; pixel++) {linear.set(rgba.subarray(pixel * 4, pixel * 4 + 3), pixel * 3);diff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex 6703b53c..378e97bf 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -58,7 +58,7 @@ The same scene and options give the same bytes. Random numbers come from a hash## Choosing a backend-`backend: "native"` is an agent render job setting, not a `renderPathTracedImage` option: [`packages/render-native`](../packages/render-native/README.md) runs the same kernel on Vulkan ray queries. On the demo room at 1920 by 1080 and 64 samples an MCP image job took 25 to 35 s with native against 58 s with gpu (trace alone 2.7 to 3.1 s against 38.8 s; the rest is the page export, the wavelet denoise and the PNG), FLIP 0.0047 between them. A missing package, binary or adapter falls back to gpu with a note in the job report. `maxSeconds` is honoured: past it the native trace stops and the job fails, as on the other backends, instead of rerunning on gpu; `noiseThreshold` is not (the native trace always runs its samples). Alpha cutouts (`alphaMode: "mask"`) work: the acceleration structure is opaque and the kernel steps through transparent texels, up to 8 layers deep (`bench/native-tracer/cutout.mjs`: 300 masked leaf cards trace in 0.1 s at 640 by 360 and 64 samples). See [agent-render-jobs.md](agent-render-jobs.md#path-tracer).+`backend: "native"` is an agent render job setting, not a `renderPathTracedImage` option: [`packages/render-native`](../packages/render-native/README.md) runs the same kernel on Vulkan ray queries. On the demo room at 1920 by 1080 and 64 samples an MCP image job took 25 to 35 s with native against 58 s with gpu (trace alone 2.7 to 3.1 s against 38.8 s; the rest is the page export, the wavelet denoise and the PNG), FLIP 0.0047 between them. A missing package, binary or adapter falls back to gpu with a note in the job report. `maxSeconds` is honoured: past it the native trace stops and the job fails, as on the other backends, instead of rerunning on gpu; `noiseThreshold` is not (the native trace always runs its samples). Alpha cutouts (`alphaMode: "mask"`) work: cutout triangles are their own geometry and the kernel confirms a hit only when the colour map alpha reaches the cutoff, with no step limit. In a dense cutout scene native is the more correct tracer: the CPU and WebGL2 shadow ray takes the first hit the traversal finds, not the nearest, and when that hit is a transparent texel it skips occluders it had not reached yet, so those backends leak light (300 leaf cards: native vs cpu FLIP 0.043, and 0.0002 once the CPU shadow ray takes the nearest hit; bench/native-tracer/cutout-bisect.mjs shows one card agrees exactly). The steps before: up to 8 layers deep (`bench/native-tracer/cutout.mjs`: 300 masked leaf cards trace in 0.1 s at 640 by 360 and 64 samples). See [agent-render-jobs.md](agent-render-jobs.md#path-tracer).`backend: 'cpu'` (the default) is the reference: it reuses `src/triangle-bvh.js` and `src/ray-query.js`, runs on workers in the job page next to the scene, needs no GPU, and gives the same bytes for the same scene and options. It measured 25 to 238 seconds for a 960 by 540 still at 32 samples on a Ryzen 5 5600X with four threads, while another session also loaded the machine (table in `bench/reference/README.md`).