3D engine that AI agents drive
Native tracer: texel bake for recipe bakes, maxSeconds on native jobs, cutout bench (issue #626)
Nguyen Xuan An8d29ee07551c
diff --git a/bench/native-tracer/cutout.mjs b/bench/native-tracer/cutout.mjsnew file mode 100644index 00000000..e4bfef26--- /dev/null+++ b/bench/native-tracer/cutout.mjs@@ -0,0 +1,98 @@+// Alpha cutouts on the native tracer: a ground plane under a few hundred masked leaf cards (a green disc in a transparent+// square, alphaMode "mask") is traced by the native ray query tracer and by the CPU tracer, the reference that has always+// stepped through cutouts. Run it through gpu-lock.+// node bench/native-tracer/cutout.mjs <output directory> [--leaves 300] [--samples 64] [--width 960] [--height 540]+// Writes cutout-native.png, cutout-cpu.png and cutout.json (seconds); score the pair with bench/webgpu-tracer/flip.py.+import { mkdir, writeFile } from 'node:fs/promises';+import { constants, setPriority } from 'node:os';+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]);++function valueAfter(flag, fallback) {+ const index = argumentsGiven.indexOf(flag);+ return index >= 0 ? argumentsGiven[index + 1] : fallback;+}++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 };++const TEXTURE_SIZE = 64;++// A green disc in a transparent square: texels outside the disc have alpha 0, so a cutout that is ignored shows squares.+function leafTexture() {+ 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 offsetX = (column + 0.5) / TEXTURE_SIZE - 0.5;+ const offsetY = (row + 0.5) / TEXTURE_SIZE - 0.5;+ const inside = Math.hypot(offsetX, offsetY) < 0.45;+ data.set([60, 170, 70, inside ? 255 : 0], (row * TEXTURE_SIZE + column) * 4);+ }+ }+ return { image: { data, width: TEXTURE_SIZE, height: TEXTURE_SIZE }, colorSpace: 'srgb', wrapS: 33071 };+}++function quad(center, along, across, size) {+ const corners = [[-1, -1], [1, -1], [1, 1], [-1, 1]].map(([first, second]) => center.map((value, axis) => value + (along[axis] * first + across[axis] * second) * size));+ const normal = [along[1] * across[2] - along[2] * across[1], along[2] * across[0] - along[0] * across[2], along[0] * across[1] - along[1] * across[0]];+ return {+ positions: new Float32Array(corners.flat()),+ normals: new Float32Array([...normal, ...normal, ...normal, ...normal]),+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++let randomState = 12345;+function random() {+ randomState = (randomState * 1664525 + 1013904223) >>> 0;+ return randomState / 4294967296;+}++function tiltedAxes() {+ const angle = random() * Math.PI * 2;+ const tilt = (random() - 0.5) * 1.6;+ const along = [Math.cos(angle), 0, Math.sin(angle)];+ const across = [-Math.sin(angle) * Math.cos(tilt), Math.sin(tilt), Math.cos(angle) * Math.cos(tilt)];+ return { along, across };+}++const texture = leafTexture();+const parts = [{ name: 'ground', geometry: quad([0, 0, 0], [1, 0, 0], [0, 0, -1], 8), material: { color: [0.6, 0.55, 0.45], roughness: 0.9 } }];+for (let leaf = 0; leaf < leafCount; leaf++) {+ const { along, across } = tiltedAxes();+ const center = [(random() - 0.5) * 5, 0.2 + random() * 1.6, (random() - 0.5) * 5];+ parts.push({ name: `leaf-${leaf}`, geometry: quad(center, along, across, 0.35),+ material: { color: [1, 1, 1], roughness: 0.7, map: texture, alphaMode: 'mask', alphaCutoff: 0.5 } });+}+const environment = { keyColor: [3, 2.8, 2.5], lightDirection: [0.4, 0.8, 0.35], pointLights: [], areaLights: [], skyColor: [0.5, 0.6, 0.8], skyIntensity: 0.6 };+const camera = createCamera({ eye: [0, 3.2, 6], target: [0, 0.8, 0], fov: 45 }, options.width, options.height);++setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);+await mkdir(outputDirectory, { recursive: true });+const scene = buildTraceScene(parts, environment);+const nativeStarted = performance.now();+const traced = traceNative(buildNativeInput(scene, camera, options, pack), options);+const nativeSeconds = (performance.now() - nativeStarted) / 1000;+const linear = new Float32Array(options.width * options.height * 3);+for (let pixel = 0; pixel < options.width * options.height; pixel++) linear.set(traced.rgba.subarray(pixel * 4, pixel * 4 + 3), pixel * 3);+const toneMapped = toneMapToRgba8(linear, options.width, options.height, { viewTransform: 'aces', look: null });+await writeFile(`${outputDirectory}/cutout-native.png`, encodePng(toneMapped, options.width, options.height));++const cpuStarted = performance.now();+const reference = await renderPathTracedImage({ parts, environment, camera: { eye: [0, 3.2, 6], target: [0, 0.8, 0], fov: 45 } },+ { ...options, backend: 'cpu', denoise: false, threads: 8, maxSeconds: 1800 });+const cpuSeconds = (performance.now() - cpuStarted) / 1000;+await writeFile(`${outputDirectory}/cutout-cpu.png`, encodePng(reference.rgba, options.width, options.height));++const record = { ...options, leafCards: leafCount, triangles: scene.indices.length / 3, nativeSeconds, nativeTracedSeconds: traced.tracedSeconds, cpuSeconds, adapter: traced.adapter };+await writeFile(`${outputDirectory}/cutout.json`, JSON.stringify(record, null, 1));+console.log(JSON.stringify(record));diff --git a/bench/native-tracer/recipe-bake.mjs b/bench/native-tracer/recipe-bake.mjsnew file mode 100644index 00000000..05bfa511--- /dev/null+++ b/bench/native-tracer/recipe-bake.mjs@@ -0,0 +1,47 @@+// A recipe light bake through the MCP server, timed from scene_create to the answer, with the backend scene_inspect reports.+// Run it through gpu-lock.+// node bench/native-tracer/recipe-bake.mjs <output directory> [--recipe tests/fixtures/demo-room.recipe.json] [--label run1]+// Writes recipe-bake-<label>.json (seconds, the `bake` block of scene_inspect). The native package is used when it is built;+// remove packages/render-native/build to see the fallback.+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';+import { constants, setPriority, tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { Client } from '@modelcontextprotocol/client';+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';++const argumentsGiven = process.argv.slice(2);+const outputDirectory = resolve(argumentsGiven[0]);++function valueAfter(flag, fallback) {+ const index = argumentsGiven.indexOf(flag);+ return index >= 0 ? argumentsGiven[index + 1] : fallback;+}++const label = valueAfter('--label', 'run1');+const recipePath = valueAfter('--recipe', 'tests/fixtures/demo-room.recipe.json');++setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);+await mkdir(outputDirectory, { recursive: true });+const workDirectory = await mkdtemp(join(tmpdir(), '67js-native-bake-'));+const transport = new StdioClientTransport({ command: process.execPath,+ args: [resolve('bin/67js-mcp.mjs'), '--backend', 'gpu', '--memory', '384', '--jobs', join(workDirectory, 'jobs')], cwd: workDirectory, stderr: 'pipe' });+let diagnostics = '';+transport.stderr.on('data', bytes => { diagnostics = (diagnostics + bytes).slice(-4096); });+const client = new Client({ name: '67js-native-bake-bench', version: '1' });++try {+ await client.connect(transport);+ const recipe = JSON.parse(await readFile(recipePath, 'utf8'));+ const started = performance.now();+ const created = (await client.callTool({ name: 'scene_create', arguments: { recipe } }, { timeout: 600000 })).structuredContent;+ const createSeconds = (performance.now() - started) / 1000;+ const inspected = (await client.callTool({ name: 'scene_inspect', arguments: { sessionId: created.sessionId } }, { timeout: 600000 })).structuredContent;+ const summary = { label, createSeconds, bake: inspected.bake, kernels: inspected.kernels };+ await writeFile(join(outputDirectory, `recipe-bake-${label}.json`), JSON.stringify(summary, null, 1));+ console.log(JSON.stringify(summary));+} catch (error) {+ console.error(diagnostics);+ throw error;+} finally {+ await client.close();+}diff --git a/bench/reference/bake-compare.mjs b/bench/reference/bake-compare.mjsindex c147db79..2175badd 100644--- a/bench/reference/bake-compare.mjs+++ b/bench/reference/bake-compare.mjs@@ -2,10 +2,12 @@// node bench/reference/bake-compare.mjs <scene id> '<variants json>'// The variants are named bake options; the first is the reference the others are compared with, for example// '{"cpu":{"backend":"cpu","samples":128},"gpu":{"backend":"gpu","samples":512}}'+// The backend is cpu, gpu, webgpu or native (the hardware ray query tracer of packages/render-native, when it is built).// Run it through GPU_LOCK_WEIGHT=heavy bash ~/.agents/tools/gpu-lock.sh: the GPU bake takes the whole GPU for seconds.import { constants, setPriority } from 'node:os';import { chromium } from 'playwright';import { createServer } from 'vite';+import { createNativeTracerLocator, traceTexelsNative } from '../../scripts/agent-native-trace.mjs';const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';const [sceneId, variantsJson] = process.argv.slice(2);@@ -15,12 +17,24 @@ setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);const server = await createServer({ server: { host: '127.0.0.1', port: 0 }, 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'] });+const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ['--enable-webgl', '--enable-unsafe-webgpu', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding'] });try {const page = await browser.newPage({ viewport: { width: 960, height: 540 } });page.on('pageerror', error => console.log('PAGE ERROR', error.message));page.on('console', message => message.type() === 'error' && console.log('PAGE CONSOLE', message.text()));page.setDefaultTimeout(0);+ // The native backend traces in this process, the way the agent runtime serves a recipe bake.+ const nativeLocator = createNativeTracerLocator();+ await page.exposeFunction('__67jsNativeBake', async request => {+ const found = await nativeLocator.find();+ if (request.action === 'probe') return { available: Boolean(found.tracer) };+ if (!found.tracer) return { error: found.reason };+ try {+ return traceTexelsNative({ tracer: found.tracer, request });+ } catch (error) {+ return { error: error.message };+ }+ });await page.goto(`${serverUrl}/bench/reference/harness.html`, { timeout: 180000 });await page.waitForFunction(() => window.compareBakeBackends, null, { timeout: 180000 });const results = await page.evaluate(([id, named]) => window.compareBakeBackends(id, named), [sceneId, variants]);diff --git a/bench/reference/harness.js b/bench/reference/harness.jsindex 986a0794..c57d71bc 100644--- a/bench/reference/harness.js+++ b/bench/reference/harness.js@@ -183,7 +183,9 @@ async function bakeScene(scene, bakeOptions) {const { pointLights, keyColor, lightDirection } = scene.environment;const started = performance.now();// A scene as large as a hall can need its own texel density to stay under the bake's texel limit.- const baked = await bakeLightmapsAsync(scene.parts, { pointLights, keyColor, lightDirection }, { ...scene.bakeOptions, ...bakeOptions });+ // The native backend traces in the host process; bake-compare.mjs exposes it to the page.+ const texelTracer = bakeOptions.backend === 'native' ? (await import('/scripts/native-bake-page.js')).traceTexelsOnNative : undefined;+ const baked = await bakeLightmapsAsync(scene.parts, { pointLights, keyColor, lightDirection }, { ...scene.bakeOptions, ...bakeOptions, texelTracer });return { parts: baked.parts, report: baked.report, seconds: (performance.now() - started) / 1000 };}diff --git a/changes/626-bake.md b/changes/626-bake.mdnew file mode 100644index 00000000..d060123e--- /dev/null+++ b/changes/626-bake.md@@ -0,0 +1,2 @@+- Recipe light bakes run on the native ray query tracer when `packages/render-native` is built: `bake.backend` is `native`, with the page's GPU kernel as the fallback (`bake.backendNote` says why). `bakeLightmapsAsync` takes `backend: "native"` with a `texelTracer`.+- `renderer.maxSeconds` is honoured by `renderer.backend: "native"`: a trace that passes it fails the job instead of falling back.diff --git a/docs/light-bake.md b/docs/light-bake.mdindex 84469c95..700643f8 100644--- a/docs/light-bake.md+++ b/docs/light-bake.md@@ -58,7 +58,7 @@ Not baked: the environment map (it already lights every surface at run time) and### Recipe bakes choose the backend themselves-A recipe `bake` built in a runtime on the GPU backend (the MCP server's default, `scene_inspect`, render jobs) traces its lightmaps on the GPU when the page has WebGL2 with `EXT_color_buffer_float` and `EXT_float_blend`, and on the CPU worker otherwise: SwiftShader runtimes (`--backend cpu`), a recipe whose lights use `affects`, or a GPU bake that fails. `scene_inspect` reports `bake.backend` (`cpu` or `gpu`) and, for the GPU, `bake.gpu` and `bake.gpuCompileSeconds`. The CPU path is unchanged, so the same recipe gives the same bytes there. The irradiance grid and probes still trace on the CPU.+A recipe `bake` built in a runtime on the GPU backend (the MCP server's default, `scene_inspect`, render jobs) traces its lightmaps first on the native ray query tracer when [`packages/render-native`](../packages/render-native/README.md) is installed and built (`bake.backend` is `native`; its texel entry is `bakeTexels` in the same Vulkan kernel as the render jobs, and a failed native bake falls back to the page's GPU kernel with `bake.backendNote`). On `lit-interior` (28,784 texels, 256 samples, `bench/reference/bake-compare.mjs` with a `native` variant, 2026-11-09) the native bake took 0.26 s against 0.30 s on WebGPU and 0.42 s on WebGL2 once compiled, its kernel compiles in 4 ms against 0.36 s and 8.2 s, and the mean light is 0.12 percent above WebGL2 (gap share 0.0032; the first leg of a bake counts as one bounce, so the kernel runs `bounces - 1`). The native bake has no fog or subsurface, as the native render job. Without it the bake traces on the GPU when the page has WebGL2 with `EXT_color_buffer_float` and `EXT_float_blend`, and on the CPU worker otherwise: SwiftShader runtimes (`--backend cpu`), a recipe whose lights use `affects`, or a GPU bake that fails. `scene_inspect` reports `bake.backend` (`cpu` or `gpu`) and, for the GPU, `bake.gpu` and `bake.gpuCompileSeconds`. The CPU path is unchanged, so the same recipe gives the same bytes there. The irradiance grid and probes still trace on the CPU.## How a part draws itdiff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex 1990ce07..893034f1 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. 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: 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: '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`).diff --git a/packages/render-native/README.md b/packages/render-native/README.mdindex f0deb9bf..f35d023b 100644--- a/packages/render-native/README.md+++ b/packages/render-native/README.md@@ -18,3 +18,16 @@ const { rgba, adapter, tracedSeconds } = traceNative(input, options);````rgba` is linear float RGBA, rows from the top, averaged over the samples. `albedo` and `normal` (three floats per pixel, normalise the normal), `depth` and `variance` (one float) are the first-hit features the wavelet and OIDN denoisers read. `pack-input.mjs` holds `buildNativeInput` without Node imports, so the job page packs the scene itself. `bench/native-tracer` compares it with the browser kernel.++`traceNative` also takes `maxSeconds`: the trace stops with an error ("passed its time limit") once it has run that long. Alpha cutouts are traced by stepping through transparent texels in the kernel (the acceleration structure is opaque).++The light bake uses the texel entry of the same kernel:++```js+import { buildNativeTexelInput, traceNativeTexels } from '@codepawlhq/67js-render-native';++const input = buildNativeTexelInput(traceScene, { texelCount, samples: 256, bounces: 3, seed: 1, fireflyClamp: 1e6 }, pack);+const { radiance, escaped } = traceNativeTexels(input, { count: texelCount, points, normals }, { samples: 256 });+```++`radiance` is the mean light that reaches each texel (three floats per texel) and `escaped` the share of first rays that left the scene. The agent runtime uses it for recipe bakes (`bake.backend: "native"`).diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjsindex b2edb5a5..0472ca30 100644--- a/packages/render-native/index.mjs+++ b/packages/render-native/index.mjs@@ -5,7 +5,7 @@ import { createRequire } from 'node:module';import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';-export { buildNativeInput } from './pack-input.mjs';+export { buildNativeInput, buildNativeTexelInput } from './pack-input.mjs';const PACKAGE_DIRECTORY = dirname(fileURLToPath(import.meta.url));const ADDON_PATH = join(PACKAGE_DIRECTORY, 'build', 'render-native.node');@@ -17,11 +17,24 @@ export function findNativeAddon() {/*** Traces the input on the GPU and resolves linear RGBA float data (`rgba`, width * height * 4, rows from the top, the- * average of `samples` paths) with the adapter name and timings in seconds.+ * average of `samples` paths) with the adapter name and timings in seconds. `maxSeconds` makes the trace fail once it has+ * run that long.*/-export function traceNative(input, { width, height, samples }) {+export function traceNative(input, { width, height, samples, maxSeconds }) {+ return loadAddon().traceScene(input, { width, height, samples, maxSeconds });+}++/**+ * The light bake: traces `samples` cosine weighted paths from every texel of `texels` (`count`, `points`, `normals`) and+ * returns the mean `radiance` (three floats per texel) and the share of first rays that `escaped`. The input comes from+ * `buildNativeTexelInput`.+ */+export function traceNativeTexels(input, texels, { samples, maxSeconds }) {+ return loadAddon().traceTexels(input, texels, { samples, maxSeconds });+}++function loadAddon() {const addonPath = findNativeAddon();if (!addonPath) throw new Error('The native tracer is not built. Run `npm run build` in packages/render-native.');- const addon = createRequire(import.meta.url)(addonPath);- return addon.traceScene(input, { width, height, samples });+ return createRequire(import.meta.url)(addonPath);}diff --git a/packages/render-native/pack-input.mjs b/packages/render-native/pack-input.mjsindex 89dbb115..a0a04edc 100644--- a/packages/render-native/pack-input.mjs+++ b/packages/render-native/pack-input.mjs@@ -48,3 +48,20 @@ export function buildNativeInput(scene, camera, options, pack) {parameters: writeParameters(scene, camera, options, lights.count, atlas.width),};}++// The words of the parameter block the texel entry reads: the texel count where an image holds its width, and the sample+// count in the third word after the seed and the atlas width.+const TEXEL_SAMPLES_WORD = 46;+const NO_CAMERA = { eye: [0, 0, 0], forward: [0, 0, -1], right: [1, 0, 0], above: [0, 1, 0], halfWidth: 1, halfHeight: 1 };++/**+ * The tables of a light bake: the scene without a camera, with the texel count and the sample count in the parameter block.+ * `options` holds `texelCount`, `samples`, `bounces`, `seed` and `fireflyClamp`; `pack` is as for `buildNativeInput`.+ */+export function buildNativeTexelInput(scene, options, pack) {+ // The bake's `bounces` counts the leg that leaves the texel; the kernel counts the bounces after its first hit.+ const input = buildNativeInput(scene, NO_CAMERA, { ...options, bounces: options.bounces - 1, width: options.texelCount, height: 1 }, pack);+ const words = new Uint32Array(input.parameters.buffer, input.parameters.byteOffset, input.parameters.byteLength / 4);+ words[TEXEL_SAMPLES_WORD] = options.samples;+ return input;+}diff --git a/packages/render-native/src/lib.rs b/packages/render-native/src/lib.rsindex 9ebd27ce..26a038a9 100644--- a/packages/render-native/src/lib.rs+++ b/packages/render-native/src/lib.rs@@ -10,7 +10,13 @@ use napi_derive::napi;use wgpu::util::DeviceExt;const KERNEL_SOURCE: &str = include_str!("kernel.wgsl");+/// The texel entry point of the light bake, appended to the kernel for a bake only.+const TEXEL_SOURCE: &str = include_str!("texel.wgsl");const WORKGROUP_SIZE: u32 = 8;+/// Must match `TEXEL_WORKGROUP_SIZE` in texel.wgsl.+const TEXEL_WORKGROUP_SIZE: u32 = 64;+/// A dispatch is at most 65535 workgroups wide; a larger bake wraps onto the second dimension.+const MAXIMUM_TEXEL_GROUPS_X: u32 = 4096;const TRIANGLE_FLOATS: usize = 9 * 4;/// Byte offset of the sample index inside the parameter block (`emittersFlagsSample.w`).const SAMPLE_INDEX_BYTE_OFFSET: u64 = 43 * 4;@@ -38,6 +44,40 @@ pub struct NativeTraceOptions {pub width: u32,pub height: u32,pub samples: u32,+ /// Stop with an error once the trace has run this long (checked every few samples); absent means no limit.+ pub max_seconds: Option<f64>,+}++#[napi(object)]+pub struct NativeTexels {+ /// How many lightmap texels the two lists hold.+ pub count: u32,+ /// World positions, three floats per texel.+ pub points: Float32Array,+ /// Unit surface normals, three floats per texel.+ pub normals: Float32Array,+}++#[napi(object)]+pub struct NativeTexelOptions {+ pub samples: u32,+ /// As for `NativeTraceOptions`.+ pub max_seconds: Option<f64>,+}++#[napi(object)]+pub struct NativeTexelResult {+ /// The mean light that arrives at each texel, three floats per texel.+ pub radiance: Float32Array,+ /// The share of first rays that left the scene, per texel.+ pub escaped: Float32Array,+ pub adapter: String,+ pub backend: String,+ pub setup_seconds: f64,+ pub compile_seconds: f64,+ pub upload_seconds: f64,+ pub acceleration_build_seconds: f64,+ pub traced_seconds: f64,}#[napi(object)]@@ -93,20 +133,35 @@ fn storage_entry(binding: u32, read_only: bool) -> wgpu::BindGroupLayoutEntry {)}-/// Traces the packed scene on the GPU with hardware ray queries.-#[napi]-pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Result<NativeTraceResult> {- let setup_started = Instant::now();- let triangle_count = input.triangle_count as usize;- if triangle_count == 0 || input.triangles.len() < triangle_count * TRIANGLE_FLOATS {- return Err(failure("The triangle table must hold triangle_count triangles of 9 texels."));- }- let triangle_data: &[f32] = &input.triangles[..triangle_count * TRIANGLE_FLOATS];- if input.parameters.len() != 12 * 16 {- return Err(failure("The parameter block must be 192 bytes."));- }- let pixel_count = options.width as u64 * options.height as u64;+/// A device with the scene's acceleration structure built and one compute pipeline bound to it.+struct PreparedScene {+ device: wgpu::Device,+ queue: wgpu::Queue,+ pipeline: wgpu::ComputePipeline,+ bind_group: wgpu::BindGroup,+ accumulation: wgpu::Buffer,+ parameters: wgpu::Buffer,+ adapter_name: String,+ backend_name: String,+ setup_seconds: f64,+ compile_seconds: f64,+ upload_seconds: f64,+ acceleration_build_seconds: f64,+ // The bind group keeps the buffers and the structure alive; holding them here makes that visible.+ _buffers: Vec<wgpu::Buffer>,+ _tlas: wgpu::Tlas,+}++/// What one kind of job adds to the shared scene setup: the kernel text, its entry point, the accumulation size and the+/// extra read only buffers bound after the accumulation (bindings 9 and up).+struct JobShape<'a> {+ source: String,+ entry_point: &'a str,+ accumulation_bytes: u64,+ extra_buffers: Vec<(&'a str, Vec<u8>)>,+}+fn open_device() -> Result<(wgpu::Device, wgpu::Queue, wgpu::AdapterInfo)> {let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {backends: wgpu::Backends::VULKAN,..wgpu::InstanceDescriptor::new_without_display_handle()@@ -119,11 +174,12 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resuif !adapter.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY) {return Err(failure("The Vulkan adapter does not support ray queries."));}- let adapter_info = adapter.get_info();let adapter_limits = adapter.limits();let required_limits = wgpu::Limits {max_storage_buffer_binding_size: adapter_limits.max_storage_buffer_binding_size.min(1 << 30),max_buffer_size: adapter_limits.max_buffer_size.min(1 << 30),+ // The light bake binds nine storage buffers (the scene, the accumulation and the texels); the default allows eight.+ max_storage_buffers_per_shader_stage: adapter_limits.max_storage_buffers_per_shader_stage.min(16),..wgpu::Limits::default()}.using_minimum_supported_acceleration_structure_values();@@ -135,12 +191,26 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resu..Default::default()})).map_err(|error| failure(format!("Could not open the device: {error}")))?;+ Ok((device, queue, adapter.get_info()))+}++fn prepare_scene(input: &NativeTraceInput, shape: JobShape) -> Result<PreparedScene> {+ let setup_started = Instant::now();+ let triangle_count = input.triangle_count as usize;+ if triangle_count == 0 || input.triangles.len() < triangle_count * TRIANGLE_FLOATS {+ return Err(failure("The triangle table must hold triangle_count triangles of 9 texels."));+ }+ let triangle_data: &[f32] = &input.triangles[..triangle_count * TRIANGLE_FLOATS];+ if input.parameters.len() != 12 * 16 {+ return Err(failure("The parameter block must be 192 bytes."));+ }+ let (device, queue, adapter_info) = open_device()?;let setup_seconds = setup_started.elapsed().as_secs_f64();let compile_started = Instant::now();let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {label: Some("path tracer"),- source: wgpu::ShaderSource::Wgsl(KERNEL_SOURCE.into()),+ source: wgpu::ShaderSource::Wgsl(shape.source.into()),});let mut layout_entries = vec![layout_entry(@@ -155,6 +225,7 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resu];layout_entries.extend((2..=7).map(|binding| storage_entry(binding, true)));layout_entries.push(storage_entry(8, false));+ layout_entries.extend((0..shape.extra_buffers.len()).map(|offset| storage_entry(9 + offset as u32, true)));let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {label: Some("path tracer"),entries: &layout_entries,@@ -168,7 +239,7 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resulabel: Some("path tracer"),layout: Some(&pipeline_layout),module: &module,- entry_point: Some("main"),+ entry_point: Some(shape.entry_point),compilation_options: Default::default(),cache: None,});@@ -190,7 +261,7 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resucontents: bytemuck::cast_slice(&vertices),usage: wgpu::BufferUsages::BLAS_INPUT,});- let buffers = [+ let mut buffers = vec![storage_buffer(&device, "triangles", bytemuck::cast_slice(triangle_data)),storage_buffer(&device, "materials", bytemuck::cast_slice(&input.materials)),storage_buffer(&device, "lights", bytemuck::cast_slice(&input.lights)),@@ -200,10 +271,13 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resu];let accumulation = device.create_buffer(&wgpu::BufferDescriptor {label: Some("accumulation"),- size: pixel_count * 4 * 16,+ size: shape.accumulation_bytes,usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,mapped_at_creation: false,});+ for (label, bytes) in &shape.extra_buffers {+ buffers.push(storage_buffer(&device, label, bytes));+ }let parameters = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {label: Some("parameters"),contents: &input.parameters[..],@@ -217,6 +291,8 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resuvertex_count: (triangle_count * 3) as u32,index_format: None,index_count: None,+ // Opaque: the kernel steps through the transparent texels of a cutout itself (see `intersectScene`), so the hardware+ // never runs an any-hit shader and every hit it returns is a candidate surface.flags: wgpu::AccelerationStructureGeometryFlags::OPAQUE,};let blas = device.create_blas(@@ -266,45 +342,93 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resuwgpu::BindGroupEntry { binding: 0, resource: parameters.as_entire_binding() },wgpu::BindGroupEntry { binding: 1, resource: tlas.as_binding() },];- for (offset, buffer) in buffers.iter().enumerate() {+ for (offset, buffer) in buffers[..6].iter().enumerate() {entries.push(wgpu::BindGroupEntry { binding: 2 + offset as u32, resource: buffer.as_entire_binding() });}entries.push(wgpu::BindGroupEntry { binding: 8, resource: accumulation.as_entire_binding() });+ for (offset, buffer) in buffers[6..].iter().enumerate() {+ entries.push(wgpu::BindGroupEntry { binding: 9 + offset as u32, resource: buffer.as_entire_binding() });+ }let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {label: Some("path tracer"),layout: &bind_group_layout,entries: &entries,});+ Ok(PreparedScene {+ device,+ queue,+ pipeline,+ bind_group,+ accumulation,+ parameters,+ adapter_name: adapter_info.name,+ backend_name: format!("{:?}", adapter_info.backend),+ setup_seconds,+ compile_seconds,+ upload_seconds,+ acceleration_build_seconds,+ _buffers: buffers,+ _tlas: tlas,+ })+}+/// Runs every sample over `groups` workgroups and copies the accumulation back. `max_seconds` bounds the run: past it the+/// trace stops with an error instead of finishing, checked each time the CPU waits for the card. Returns the sums and the+/// seconds it took.+fn trace_samples(prepared: &PreparedScene, samples: u32, groups: (u32, u32), accumulation_bytes: u64, max_seconds: Option<f64>) -> Result<(Vec<f32>, f64)> {let trace_started = Instant::now();- for sample_index in 0..options.samples {- queue.write_buffer(¶meters, SAMPLE_INDEX_BYTE_OFFSET, &sample_index.to_le_bytes());+ let device = &prepared.device;+ let queue = &prepared.queue;+ for sample_index in 0..samples {+ queue.write_buffer(&prepared.parameters, SAMPLE_INDEX_BYTE_OFFSET, &sample_index.to_le_bytes());let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("sample") });{let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { label: None, timestamp_writes: None });- pass.set_pipeline(&pipeline);- pass.set_bind_group(0, &bind_group, &[]);- pass.dispatch_workgroups(options.width.div_ceil(WORKGROUP_SIZE), options.height.div_ceil(WORKGROUP_SIZE), 1);+ pass.set_pipeline(&prepared.pipeline);+ pass.set_bind_group(0, &prepared.bind_group, &[]);+ pass.dispatch_workgroups(groups.0, groups.1, 1);}queue.submit(Some(encoder.finish()));if (sample_index + 1) % SAMPLES_PER_WAIT == 0 {let _ = device.poll(wgpu::PollType::wait_indefinitely());+ if let Some(limit) = max_seconds {+ if trace_started.elapsed().as_secs_f64() > limit {+ return Err(failure(format!(+ "The native trace passed its time limit of {limit} s after {} of {samples} samples.",+ sample_index + 1+ )));+ }+ }}}- let readback_size = pixel_count * 16 * 4;let readback = device.create_buffer(&wgpu::BufferDescriptor {label: Some("readback"),- size: readback_size,+ size: accumulation_bytes,usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,mapped_at_creation: false,});let mut copy_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("readback") });- copy_encoder.copy_buffer_to_buffer(&accumulation, 0, &readback, 0, readback_size);+ copy_encoder.copy_buffer_to_buffer(&prepared.accumulation, 0, &readback, 0, accumulation_bytes);queue.submit(Some(copy_encoder.finish()));readback.slice(..).map_async(wgpu::MapMode::Read, |_| {});let _ = device.poll(wgpu::PollType::wait_indefinitely());- let mapped = readback.slice(..).get_mapped_range().map_err(|error| failure(format!("Could not read the image back: {error}")))?;- let sums: &[f32] = bytemuck::cast_slice(&mapped);+ let mapped = readback.slice(..).get_mapped_range().map_err(|error| failure(format!("Could not read the result back: {error}")))?;+ let sums: Vec<f32> = bytemuck::cast_slice::<u8, f32>(&mapped).to_vec();+ drop(mapped);+ Ok((sums, trace_started.elapsed().as_secs_f64()))+}++/// Traces the packed scene on the GPU with hardware ray queries.+#[napi]+pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Result<NativeTraceResult> {+ let pixel_count = options.width as u64 * options.height as u64;+ let accumulation_bytes = pixel_count * 4 * 16;+ let prepared = prepare_scene(+ &input,+ JobShape { source: KERNEL_SOURCE.to_string(), entry_point: "main", accumulation_bytes, extra_buffers: Vec::new() },+ )?;+ let groups = (options.width.div_ceil(WORKGROUP_SIZE), options.height.div_ceil(WORKGROUP_SIZE));+ let (sums, traced_seconds) = trace_samples(&prepared, options.samples, groups, accumulation_bytes, options.max_seconds)?;let plane_length = pixel_count as usize * 4;let sample_scale = 1.0 / options.samples.max(1) as f32;let variance_divisor = options.samples.saturating_sub(1).max(1) as f32;@@ -325,21 +449,74 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resulet mean_luminance = statistics[0] * sample_scale;variance.push((statistics[1] * sample_scale - mean_luminance * mean_luminance).max(0.0) / variance_divisor);}- drop(mapped);- let traced_seconds = trace_started.elapsed().as_secs_f64();-Ok(NativeTraceResult {rgba: Float32Array::new(rgba),albedo: Float32Array::new(albedo),normal: Float32Array::new(normal),depth: Float32Array::new(depth),variance: Float32Array::new(variance),- adapter: adapter_info.name,- backend: format!("{:?}", adapter_info.backend),- setup_seconds,- compile_seconds,- upload_seconds,- acceleration_build_seconds,+ adapter: prepared.adapter_name,+ backend: prepared.backend_name,+ setup_seconds: prepared.setup_seconds,+ compile_seconds: prepared.compile_seconds,+ upload_seconds: prepared.upload_seconds,+ acceleration_build_seconds: prepared.acceleration_build_seconds,+ traced_seconds,+ })+}++/// Three floats per texel, padded to the four the kernel's vec4 arrays read.+fn pad_vectors(vectors: &[f32], count: usize) -> Vec<u8> {+ let mut padded: Vec<f32> = Vec::with_capacity(count * 4);+ for texel in 0..count {+ padded.extend_from_slice(&vectors[texel * 3..texel * 3 + 3]);+ padded.push(0.0);+ }+ bytemuck::cast_slice(&padded).to_vec()+}++/// The light that reaches each lightmap texel: `options.samples` cosine weighted paths from every texel, traced with the+/// scene's ray queries. The parameter block of `input` carries the lights, the bounces and the seed; its texel count and+/// sample count words are the ones `buildNativeTexelInput` writes.+#[napi]+pub fn trace_texels(input: NativeTraceInput, texels: NativeTexels, options: NativeTexelOptions) -> Result<NativeTexelResult> {+ let count = texels.count as usize;+ if count == 0 || texels.points.len() < count * 3 || texels.normals.len() < count * 3 {+ return Err(failure("The texel points and normals must hold three floats for each of `count` texels."));+ }+ let accumulation_bytes = count as u64 * 2 * 16;+ let prepared = prepare_scene(+ &input,+ JobShape {+ source: format!("{KERNEL_SOURCE}\n{TEXEL_SOURCE}"),+ entry_point: "bakeTexels",+ accumulation_bytes,+ extra_buffers: vec![+ ("texel points", pad_vectors(&texels.points, count)),+ ("texel normals", pad_vectors(&texels.normals, count)),+ ],+ },+ )?;+ let workgroups = (count as u32).div_ceil(TEXEL_WORKGROUP_SIZE);+ let groups_x = workgroups.min(MAXIMUM_TEXEL_GROUPS_X);+ let groups = (groups_x, workgroups.div_ceil(groups_x));+ let (sums, traced_seconds) = trace_samples(&prepared, options.samples, groups, accumulation_bytes, options.max_seconds)?;+ let sample_scale = 1.0 / options.samples.max(1) as f32;+ let mut radiance = Vec::with_capacity(count * 3);+ let mut escaped = Vec::with_capacity(count);+ for texel in 0..count {+ radiance.extend(sums[texel * 4..texel * 4 + 3].iter().map(|value| value * sample_scale));+ escaped.push(sums[(count + texel) * 4] * sample_scale);+ }+ Ok(NativeTexelResult {+ radiance: Float32Array::new(radiance),+ escaped: Float32Array::new(escaped),+ adapter: prepared.adapter_name,+ backend: prepared.backend_name,+ setup_seconds: prepared.setup_seconds,+ compile_seconds: prepared.compile_seconds,+ upload_seconds: prepared.upload_seconds,+ acceleration_build_seconds: prepared.acceleration_build_seconds,traced_seconds,})}diff --git a/packages/render-native/src/texel.wgsl b/packages/render-native/src/texel.wgslnew file mode 100644index 00000000..46b428e1--- /dev/null+++ b/packages/render-native/src/texel.wgsl@@ -0,0 +1,30 @@+// The texel entry of the light bake, appended to kernel.wgsl for a bake: one invocation is one lightmap texel+// (params.sizeBouncesLights.x is the texel count, params.seedAndAtlas.z the sample count). The path starts on the texel's+// surface with a cosine weighted direction, so the radiance it returns is the light that arrives at the texel; the bake+// multiplies by the albedo. Plane 0 of the accumulation holds the radiance sums, plane 1 the sums of first rays that left+// the scene. Same random numbers and weights as `bakeTexels` in src/path-tracer-webgpu-kernel.js.+@group(0) @binding(9) var<storage, read> texelPoints: array<vec4<f32>>;+@group(0) @binding(10) var<storage, read> texelNormals: array<vec4<f32>>;++const TEXEL_WORKGROUP_SIZE: u32 = 64u;++@compute @workgroup_size(64)+fn bakeTexels(@builtin(global_invocation_id) id: vec3<u32>, @builtin(num_workgroups) groups: vec3<u32>) {+ let texelCount = u32(params.sizeBouncesLights.x);+ let texelIndex = id.y * groups.x * TEXEL_WORKGROUP_SIZE + id.x;+ if (texelIndex >= texelCount) { return; }+ let sampleIndex = u32(params.emittersFlagsSample.w);+ let seed = params.seedAndAtlas.x;+ if (params.emittersFlagsSample.y != 0) { sunFrame = buildFrame(params.sunDirection.xyz); }+ let normal = texelNormals[texelIndex].xyz;+ let origin = texelPoints[texelIndex].xyz + normal * params.environmentRotationAndRays.z;+ let firstUnit = (f32(sampleIndex) + hashJitter(texelIndex, sampleIndex, seed, 1u)) / f32(params.seedAndAtlas.z);+ let secondUnit = hashJitter(texelIndex, sampleIndex, seed, 2u);+ let coneRadius = sqrt(firstUnit);+ let angle = TWO_PI * secondUnit;+ let rayDirection = buildFrame(normal) * vec3<f32>(coneRadius * cos(angle), coneRadius * sin(angle), sqrt(max(0.0, 1.0 - firstUnit)));+ tracePath(origin, rayDirection, texelIndex, sampleIndex);+ if (!(all(radiance >= vec3<f32>(0.0)) && all(radiance < vec3<f32>(1e30)))) { radiance = vec3<f32>(0.0); }+ accumulation[texelIndex] += vec4<f32>(radiance, 0.0);+ accumulation[texelCount + texelIndex] += vec4<f32>(firstLegEscaped, 0.0, 0.0, 0.0);+}diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjsindex d83ce503..cdf756d1 100644--- a/scripts/agent-native-trace.mjs+++ b/scripts/agent-native-trace.mjs@@ -100,9 +100,9 @@ function withoutAlpha(rgba, pixelCount) {* Traces one frame the page exported and returns the PNG (base64) with the job report. `denoise` is "none", "wavelet" or* "oidn"; `denoiser` is the loaded OIDN package for "oidn". Throws when the tracer cannot run, so the caller can fall back.*/-export async function traceFrameNative({ tracer, exported, width, height, samples, bounces, seed, denoise, denoiser }) {+export async function traceFrameNative({ tracer, exported, width, height, samples, bounces, seed, denoise, denoiser, maxSeconds }) {const started = performance.now();- const traced = tracer.traceNative(decodeTables(exported), { width, height, samples });+ const traced = tracer.traceNative(decodeTables(exported), { width, height, samples, maxSeconds });const tracedSeconds = (performance.now() - started) / 1000;const pixelCount = width * height;const features = { color: withoutAlpha(traced.rgba, pixelCount), albedo: traced.albedo, normal: traced.normal,@@ -134,3 +134,31 @@ export async function traceFrameNative({ tracer, exported, width, height, samplereport.seconds = (performance.now() - started) / 1000;return { data: Buffer.from(png).toString('base64'), report };}++function floatsToBase64(values) {+ return Buffer.from(values.buffer, values.byteOffset, values.byteLength).toString('base64');+}++function floatsFromBase64(data) {+ const bytes = Buffer.from(data, 'base64');+ const copy = new Uint8Array(bytes.length);+ copy.set(bytes);+ return new Float32Array(copy.buffer, 0, copy.length / Float32Array.BYTES_PER_ELEMENT);+}++/**+ * Traces the texels of a recipe bake that the page packed, for the page's `__67jsNativeBake` bridge. `request` holds the+ * scene `tables` and `triangleCount` as `exportNativeScene` makes them, plus `texelCount`, `points`, `normals` (base64+ * floats) and `samples`. Resolves with the base64 `radiance` and `escaped` arrays; throws when the tracer cannot run.+ */+export function traceTexelsNative({ tracer, request, maxSeconds }) {+ const texels = { count: request.texelCount, points: floatsFromBase64(request.points), normals: floatsFromBase64(request.normals) };+ const traced = tracer.traceNativeTexels(decodeTables(request), texels, { samples: request.samples, maxSeconds });+ return { radiance: floatsToBase64(traced.radiance), escaped: floatsToBase64(traced.escaped), adapter: traced.adapter,+ compileSeconds: traced.compileSeconds, tracedSeconds: traced.tracedSeconds };+}++/** True for the error the native tracer raises when a trace passes its `maxSeconds`: a clean failure, not a broken adapter. */+export function isNativeTimeLimitError(error) {+ return /passed its time limit/.test(error?.message ?? '');+}diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex d6ede53c..ae859d47 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -1,3 +1,4 @@+import { encodeNativeTables, nativeTexelTracerIfAvailable } from './native-bake-page.js';import { buildWithKernels, kernelWorkersAvailable, kernelStats, resetKernelStats } from '../src/kernel-offload.js';import { createAgentScene, applyCameraFields, loadAllAgentSceneModules, allAgentSceneModulesLoaded, needsMeshBooleans, loadMeshBooleans, meshBooleansLoaded, setManifoldModuleLoader, needsPhysics, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader } from '../src/agent-scene.js';import { Renderer67 } from '../src/renderer.js';@@ -509,11 +510,12 @@ function useKernelWorkers() {return kernelWorkersAvailable() && globalThis.__67jsKernelWorkers !== 'off';}-// A recipe bake runs on the GPU when the page has float render targets; the CPU bake stays the default everywhere else.+// A recipe bake runs on the native tracer when the host offers it, on the GPU when the page has float render targets, and on+// the CPU everywhere else.async function pageKernelsFor(recipe, backend) {if (!recipe.bake || backend !== 'gpu') return undefined;const { gpuBakeKernels } = await import('../src/agent-bake-gpu.js');- return gpuBakeKernels();+ return gpuBakeKernels({ texelTracer: await nativeTexelTracerIfAvailable() });}async function buildSceneOffMainThread(recipe, options, backend) {@@ -807,10 +809,7 @@ window.__agentPreview = {const traceScene = buildTraceScene(record.scene.parts, environment);const camera = createCamera(record.scene.camera, options.width, options.height);const input = buildNativeInput(traceScene, camera, options, pack);- const tables = {};- for (const [name, values] of Object.entries(input)) {- if (ArrayBuffer.isView(values)) tables[name] = bytesToBase64(new Uint8Array(values.buffer, values.byteOffset, values.byteLength));- }+ const tables = encodeNativeTables(input);// The native kernel has no participating media yet, so say so instead of claiming a fog or a subsurface look it did not trace.const ignored = describeIgnoredFeatures(record.scene.parts, environment);if (environment.volumeFog?.density > 0) ignored.push('volumeFog is not traced by the native backend.');diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex 909366f1..03bd715a 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -14,7 +14,7 @@ import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';import { PATH_TRACER_CAPABILITIES } from '../src/path-tracer-capabilities.js';import { chooseDenoiser, finishWithOidn } from './agent-path-trace-denoise.mjs';-import { chooseTraceBackend, createNativeTracerLocator, traceFrameNative } from './agent-native-trace.mjs';+import { chooseTraceBackend, createNativeTracerLocator, isNativeTimeLimitError, traceFrameNative, traceTexelsNative } from './agent-native-trace.mjs';import { createAgentAssetCatalog } from './agent-asset-catalog.mjs';import { geometryOnlyGlb } from './agent-query-asset.mjs';import { AGENT_ASSET_LIMITS, assertCombinedAssetBytes } from '../src/agent-asset-limits.js';@@ -319,6 +319,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browreturn url.origin === origin ? route.continue() : route.abort();});page.setDefaultTimeout(15000);+ if (backend === 'gpu') await page.exposeFunction('__67jsNativeBake', answerNativeBake);if (!kernelWorkers) {await page.addInitScript(() => { globalThis.__67jsKernelWorkers = 'off'; });}@@ -336,6 +337,22 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow}}+ // The page's bridge to the native tracer for recipe bakes: `probe` says whether it can run, `trace` bakes the texels the page+ // packed. A failure comes back as `{ error }` so the page falls back to its own GPU kernel, and the cause is remembered, so+ // later bakes and render jobs skip the attempt.+ async function answerNativeBake(request) {+ nativeTracerLocator ??= createNativeTracerLocator();+ const found = await nativeTracerLocator.find();+ if (request.action === 'probe') return { available: Boolean(found.tracer) };+ if (!found.tracer) return { error: found.reason };+ try {+ return traceTexelsNative({ tracer: found.tracer, request, maxSeconds: BAKE_WORKER_MAXIMUM_SECONDS });+ } catch (error) {+ if (!isNativeTimeLimitError(error)) nativeTracerLocator.markUnusable(error.message);+ return { error: error.message };+ }+ }+function requireSession(sessionId) {if (!activeSessionId || sessionId !== activeSessionId) {throw new Error(sessionProblem(sessionId, activeSessionId));@@ -470,8 +487,11 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browtry {const exported = await jobPage.evaluate(input => window.__agentPreview.exportNativeScene(input), { ...frameInput, options: { width, height, bounces: tracerOptions.bounces, seed: tracerOptions.seed, fireflyClamp: 20 } });traced = await traceFrameNative({ tracer: trace.tracer, exported, width, height, samples: tracerOptions.samples, bounces: tracerOptions.bounces,- seed: tracerOptions.seed, denoise: choice.denoise === true ? 'wavelet' : choice.denoise === false ? 'none' : choice.denoise, denoiser: choice.denoiser });+ seed: tracerOptions.seed, denoise: choice.denoise === true ? 'wavelet' : choice.denoise === false ? 'none' : choice.denoise, denoiser: choice.denoiser,+ maxSeconds: tracerOptions.maxSeconds });} catch (error) {+ // Past maxSeconds the job fails as it does on every backend; falling back would only run it twice as long.+ if (isNativeTimeLimitError(error)) throw error;nativeTracerLocator.markUnusable(error.message);backendNote = (await nativeTracerLocator.find()).reason;traceOptions.backend = backend === 'cpu' ? 'cpu' : 'gpu';diff --git a/scripts/native-bake-page.js b/scripts/native-bake-page.jsnew file mode 100644index 00000000..16ec44dc--- /dev/null+++ b/scripts/native-bake-page.js@@ -0,0 +1,67 @@+// The page side of the native tracer (packages/render-native), shared by the agent preview page and the bench harness. The+// tracer runs in the host process; the host exposes it on the page as `__67jsNativeBake` (see the agent runtime), and+// everything here packs a scene into the tables it reads and unpacks its answer.++function bytesToBase64(bytes) {+ if (typeof bytes.toBase64 === 'function') return bytes.toBase64();+ const chunkSize = 0x8000;+ let binary = '';+ for (let offset = 0; offset < bytes.length; offset += chunkSize) {+ binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));+ }+ return btoa(binary);+}++function bytesFromBase64(data) {+ if (typeof Uint8Array.fromBase64 === 'function') return Uint8Array.fromBase64(data);+ const binary = atob(data);+ const bytes = new Uint8Array(binary.length);+ for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);+ return bytes;+}++/** Each typed array of a packed native input as base64 bytes, keyed by table name. */+export function encodeNativeTables(input) {+ const tables = {};+ for (const [name, values] of Object.entries(input)) {+ if (ArrayBuffer.isView(values)) tables[name] = bytesToBase64(new Uint8Array(values.buffer, values.byteOffset, values.byteLength));+ }+ return tables;+}++function floatsFromBase64(data) {+ const bytes = bytesFromBase64(data);+ return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Float32Array.BYTES_PER_ELEMENT);+}++function floatsToBase64(values) {+ return bytesToBase64(new Uint8Array(values.buffer, values.byteOffset, values.byteLength));+}++/**+ * The texel tracer of the light bake on the native backend: the packed scene and the texels go to the host, which traces+ * them with ray queries and answers with the light that reaches each texel. Same arguments and answer as `traceTexelsOnGpu`.+ */+export async function traceTexelsOnNative(scene, texels, options) {+ const [pack, { buildNativeTexelInput }] = await Promise.all([import('../src/path-tracer-gpu-pack.js'), import('../packages/render-native/pack-input.mjs')]);+ if (pack.sceneUsesSubsurface(scene.materials)) throw new Error('subsurface is not traced by the native backend');+ const input = buildNativeTexelInput(scene, { texelCount: texels.count, samples: options.samples, bounces: options.bounces, seed: options.seed, fireflyClamp: options.fireflyClamp }, pack);+ const answer = await globalThis.__67jsNativeBake({+ action: 'trace',+ tables: encodeNativeTables(input),+ triangleCount: input.triangleCount,+ samples: options.samples,+ texelCount: texels.count,+ points: floatsToBase64(texels.points.subarray(0, texels.count * 3)),+ normals: floatsToBase64(texels.normals.subarray(0, texels.count * 3)),+ });+ if (answer.error) throw new Error(answer.error);+ return { radiance: floatsFromBase64(answer.radiance), escaped: floatsFromBase64(answer.escaped), gpu: answer.adapter, compileSeconds: answer.compileSeconds };+}++/** `traceTexelsOnNative` when the host offers a tracer that can run here, otherwise undefined. */+export async function nativeTexelTracerIfAvailable() {+ if (typeof globalThis.__67jsNativeBake !== 'function') return undefined;+ const status = await globalThis.__67jsNativeBake({ action: 'probe' });+ return status.available ? traceTexelsOnNative : undefined;+}diff --git a/src/agent-bake-gpu.js b/src/agent-bake-gpu.jsindex 24eb800d..aee30684 100644--- a/src/agent-bake-gpu.js+++ b/src/agent-bake-gpu.js@@ -18,26 +18,47 @@ export function canBakeOnGpu(lighting) {return lightsOf(lighting).every(light => light.affects === undefined || light.affects === null);}-/** The `lightBake` answer traced on the GPU, in the shape `bakeChangedParts` returns. */-export async function bakeChangedPartsOnGpu(snapshots, lighting, settings) {- const plan = planLightmaps(snapshots, lighting, { ...settings, maxSeconds: BAKE_WORKER_MAXIMUM_SECONDS, backend: 'gpu' });+/**+ * The `lightBake` answer traced on the GPU, in the shape `bakeChangedParts` returns. `texelTracer` (the native tracer+ * outside the page) makes the backend "native"; without it the page's WebGL2 kernel runs.+ */+export async function bakeChangedPartsOnGpu(snapshots, lighting, settings, texelTracer) {+ const backend = texelTracer ? 'native' : 'gpu';+ const plan = planLightmaps(snapshots, lighting, { ...settings, maxSeconds: BAKE_WORKER_MAXIMUM_SECONDS, backend });const { used, reduced, reduction } = fitSettingsToBudget(plan, settings);- const { parts, report } = await traceLightmapsAsync(plan, { ...used, backend: 'gpu' });+ const { parts, report } = await traceLightmapsAsync(plan, { ...used, backend, ...(texelTracer ? { texelTracer } : {}) });return { changed: changedPartsOf(parts, snapshots), report, used, reduced, reduction };}/**- * Page kernels for `buildWithKernels`: the GPU bake when this page has WebGL2 float targets, and nothing otherwise, so- * the worker keeps the CPU bake.+ * The native bake with the page's own kernel as its fallback: a native trace that cannot run (no package, no ray query+ * adapter, over its time) is noted in `report.backendNote`, and the WebGL2 kernel bakes instead when this page has one. With+ * no WebGL2 kernel the error stands, and the worker bakes on the CPU.+ */+async function bakeNativeOrOnGpu(snapshots, lighting, settings, texelTracer) {+ try {+ return await bakeChangedPartsOnGpu(snapshots, lighting, settings, texelTracer);+ } catch (error) {+ if (!isGpuTracerAvailable()) throw error;+ const fallback = await bakeChangedPartsOnGpu(snapshots, lighting, settings);+ return { ...fallback, report: { ...fallback.report, backendNote: `The native bake could not run (${error.message}); the gpu backend ran instead.` } };+ }+}++/**+ * Page kernels for `buildWithKernels`: the GPU bake when this page has WebGL2 float targets or the host offers the native+ * tracer (`texelTracer`, see the preview page), and nothing otherwise, so the worker keeps the CPU bake.*/-export function gpuBakeKernels() {- if (!isGpuTracerAvailable()) {+export function gpuBakeKernels({ texelTracer } = {}) {+ if (!texelTracer && !isGpuTracerAvailable()) {return undefined;}return {lightBake: {accepts: ([, lighting]) => canBakeOnGpu(lighting),- compute: ([snapshots, lighting, settings]) => bakeChangedPartsOnGpu(snapshots, lighting, settings),+ compute: ([snapshots, lighting, settings]) => (texelTracer+ ? bakeNativeOrOnGpu(snapshots, lighting, settings, texelTracer)+ : bakeChangedPartsOnGpu(snapshots, lighting, settings)),},};}diff --git a/src/light-bake-gpu.js b/src/light-bake-gpu.jsindex 46e70b1b..fb820fc9 100644--- a/src/light-bake-gpu.js+++ b/src/light-bake-gpu.js@@ -50,6 +50,7 @@ function packCoveredTexels(rasterized) {*//** The texel tracer of the backend; each is loaded only when a bake asks for it. */async function loadTexelTracer(backend) {+ if (backend === 'native') throw new RangeError('A light bake on the native backend needs a `texelTracer` function in its settings: the native tracer runs outside the page.');if (backend === 'webgpu') return (await import('./path-tracer-webgpu.js')).traceTexelsOnWebGpu;return (await import('./path-tracer-gpu.js')).traceTexelsOnGpu;}@@ -58,7 +59,7 @@ async function gatherOnGpu(plan, settings, rasterized, shouldStop) {const environment = traceEnvironment(plan);const texels = packCoveredTexels(rasterized);const scene = buildTraceScene(plan.parts, environment);- const traceTexels = await loadTexelTracer(settings.backend);+ const traceTexels = settings.texelTracer ?? await loadTexelTracer(settings.backend);const traced = await traceTexels(scene, texels, { samples: settings.samples, bounces: settings.bounces, seed: BAKE_SEED, fireflyClamp: NO_FIREFLY_CLAMP }, shouldStop);let next = 0;const entries = rasterized.map(({ resolution }, entryNumber) => {@@ -88,10 +89,12 @@ export async function traceLightmapsAsync(plan, tracedSettings) {/*** `bakeLightmaps` with a choice of tracer: `options.backend` is "cpu" (the default, the reference) or "gpu", which traces the- * texels with the GPU path tracer's kernel and needs a page with WebGL2, or "webgpu", which runs the WGSL kernel and needs `navigator.gpu`. Resolves with the same `{ parts, report }`;- * `report.backend` names the tracer, and a GPU or WebGPU bake adds `gpu` and `gpuCompileSeconds`.+ * texels with the GPU path tracer's kernel and needs a page with WebGL2, or "webgpu", which runs the WGSL kernel and needs `navigator.gpu`,+ * or "native", which hands the texels to `options.texelTracer` (the hardware ray query tracer outside the page, see+ * scripts/native-bake-page.js). Resolves with the same `{ parts, report }`;+ * `report.backend` names the tracer, and a GPU, WebGPU or native bake adds `gpu` and `gpuCompileSeconds`.*/export async function bakeLightmapsAsync(parts, lighting, options = {}) {const plan = planLightmaps(parts, lighting, options);- return traceLightmapsAsync(plan, { ...plan.settings, skyOnly: options.skyOnly === true });+ return traceLightmapsAsync(plan, { ...plan.settings, skyOnly: options.skyOnly === true, ...(options.texelTracer ? { texelTracer: options.texelTracer } : {}) });}diff --git a/src/light-bake.js b/src/light-bake.jsindex 306cfbee..142f4a24 100644--- a/src/light-bake.js+++ b/src/light-bake.js@@ -26,7 +26,7 @@ export const MAX_BAKE_TRIANGLES = 200_000;export const MAX_BAKE_PARTS = 256;// The GPU tracer takes as many parts as the path tracer does (MAX_TRACE_PARTS); the CPU bake keeps 256.export const MAX_GPU_BAKE_PARTS = 1024;-const BAKE_BACKENDS = ['cpu', 'gpu', 'webgpu'];+const BAKE_BACKENDS = ['cpu', 'gpu', 'webgpu', 'native'];export const MAX_BAKE_POINT_LIGHTS = MAX_POINT_LIGHTS;export const MAX_BAKE_SPOT_LIGHTS = MAX_SPOT_LIGHTS;export const MAX_BAKE_AREA_LIGHTS = MAX_AREA_LIGHTS;@@ -66,7 +66,7 @@ export function normalizeBakeOptions(options = {}) {const normalized = {};for (const name of Object.keys(BAKE_LIMITS)) normalized[name] = boundedNumber(options, name);normalized.backend = options.backend ?? 'cpu';- if (!BAKE_BACKENDS.includes(normalized.backend)) throw new TypeError('Light bake backend must be "cpu", "gpu" or "webgpu".');+ if (!BAKE_BACKENDS.includes(normalized.backend)) throw new TypeError('Light bake backend must be "cpu", "gpu", "webgpu" or "native".');return normalized;}diff --git a/tests/native-bake.test.js b/tests/native-bake.test.jsnew file mode 100644index 00000000..b88a00a6--- /dev/null+++ b/tests/native-bake.test.js@@ -0,0 +1,87 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { box } from '../src/geometry.js';+import { bakeLightmapsAsync } from '../src/light-bake-gpu.js';+import { gpuBakeKernels } from '../src/agent-bake-gpu.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';+import * as pack from '../src/path-tracer-gpu-pack.js';+import { buildNativeTexelInput } from '../packages/render-native/pack-input.mjs';+import { isNativeTimeLimitError, traceTexelsNative } from '../scripts/agent-native-trace.mjs';++const cube = box(0, 1);++function placed(name, translation, scale) {+ const 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]);+ return { name, geometry: cube, matrix, material: { tag: 'surface', color: [0.7, 0.7, 0.7], metallic: 0, roughness: 0.8, emission: 0 } };+}++const room = [placed('floor', [0, -0.05, 0], [6, 0.1, 6]), placed('back', [0, 1.5, -3.05], [6, 3.2, 0.1])];+const lamp = { pointLights: [{ position: [-1.5, 2.5, 0], color: [1, 1, 1], intensity: 8, radius: 0.05 }], keyColor: [0, 0, 0] };+const fastOptions = { samples: 8, bounces: 2, texelsPerUnit: 2, maxResolution: 16, backend: 'native' };++test('the light bake accepts the native backend and hands its texels to the texel tracer', async () => {+ const calls = [];+ const texelTracer = async (scene, texels, options) => {+ calls.push({ texels: texels.count, samples: options.samples, bounces: options.bounces });+ return { radiance: new Float32Array(texels.count * 3).fill(1), escaped: new Float32Array(texels.count), gpu: 'fake adapter', compileSeconds: 0 };+ };+ const baked = await bakeLightmapsAsync(room, lamp, { ...fastOptions, texelTracer });+ assert.equal(baked.report.backend, 'native');+ assert.equal(baked.report.gpu, 'fake adapter');+ assert.equal(calls.length, 1);+ assert.equal(calls[0].samples, 8);+ assert.ok(calls[0].texels > 0);+});++test('a native bake without a texel tracer says what it needs instead of running the WebGL kernel', async () => {+ await assert.rejects(bakeLightmapsAsync(room, lamp, fastOptions), /texelTracer/);+});++test('the texel parameter block carries the texel count, the sample count and the bounces after the first leg', () => {+ const scene = buildTraceScene(room, { keyColor: [0, 0, 0], lightDirection: [0, 1, 0], pointLights: lamp.pointLights });+ const input = buildNativeTexelInput(scene, { texelCount: 1234, samples: 77, bounces: 3, seed: 5, fireflyClamp: 1e6 }, pack);+ const integers = new Int32Array(input.parameters.buffer, input.parameters.byteOffset, input.parameters.byteLength / 4);+ const words = new Uint32Array(input.parameters.buffer, input.parameters.byteOffset, input.parameters.byteLength / 4);+ assert.equal(integers[36], 1234);+ assert.equal(integers[38], 2);+ assert.equal(words[44], 5);+ assert.equal(words[46], 77);+});++function decodeFloats(base64) {+ const bytes = Uint8Array.from(Buffer.from(base64, 'base64'));+ return [...new Float32Array(bytes.buffer)];+}++test('the host decodes the page request, runs the native texel trace and encodes the answer', () => {+ const scene = buildTraceScene(room, { keyColor: [0, 0, 0], lightDirection: [0, 1, 0], pointLights: lamp.pointLights });+ const input = buildNativeTexelInput(scene, { texelCount: 2, samples: 4, bounces: 2, seed: 1, fireflyClamp: 1e6 }, pack);+ const tables = {};+ for (const [name, values] of Object.entries(input)) {+ if (ArrayBuffer.isView(values)) tables[name] = Buffer.from(values.buffer, values.byteOffset, values.byteLength).toString('base64');+ }+ const floats = values => Buffer.from(new Float32Array(values).buffer).toString('base64');+ let seen;+ const tracer = {+ traceNativeTexels(decoded, texels, options) {+ seen = { triangleCount: decoded.triangleCount, count: texels.count, points: [...texels.points], options };+ return { radiance: new Float32Array([1, 2, 3, 4, 5, 6]), escaped: new Float32Array([0.25, 0.5]), adapter: 'fake', compileSeconds: 0.5, tracedSeconds: 1 };+ },+ };+ const request = { tables, triangleCount: input.triangleCount, samples: 4, texelCount: 2, points: floats([0, 0, 0, 1, 1, 1]), normals: floats([0, 1, 0, 0, 1, 0]) };+ const answer = traceTexelsNative({ tracer, request, maxSeconds: 90 });+ assert.deepEqual(seen, { triangleCount: input.triangleCount, count: 2, points: [0, 0, 0, 1, 1, 1], options: { samples: 4, maxSeconds: 90 } });+ assert.deepEqual(decodeFloats(answer.radiance), [1, 2, 3, 4, 5, 6]);+ assert.deepEqual(decodeFloats(answer.escaped), [0.25, 0.5]);+ assert.equal(answer.adapter, 'fake');+});++test('only the native time limit error is a clean failure', () => {+ assert.equal(isNativeTimeLimitError(new Error('The native trace passed its time limit of 5 s after 8 of 64 samples.')), true);+ assert.equal(isNativeTimeLimitError(new Error('The Vulkan adapter does not support ray queries.')), false);+});++test('a host that offers the native tracer gives the page bake kernels even without WebGL2', () => {+ assert.equal(gpuBakeKernels(), undefined);+ assert.equal(typeof gpuBakeKernels({ texelTracer: async () => ({}) }).lightBake.compute, 'function');+});