3D engine that AI agents drive
Add a WebGPU compute backend to the path tracer: megakernel and wavefront (issue #625)
Nguyen Xuan An6cd65ceaf088
diff --git a/bench/reference/gpu-compare.mjs b/bench/reference/gpu-compare.mjsindex 0426e081..62940047 100644--- a/bench/reference/gpu-compare.mjs+++ b/bench/reference/gpu-compare.mjs@@ -1,5 +1,5 @@// Draws reference scenes with the path tracer on the CPU and on the GPU, same seed, and writes the images and timings.-// node bench/reference/gpu-compare.mjs <output directory> <scene id>,<scene id> [--samples 64] [--backend cpu|gpu|both]+// node bench/reference/gpu-compare.mjs <output directory> <scene id>,<scene id> [--samples 64] [--backend cpu|gpu|webgpu|both]// [--width 960] [--height 540] [--bounces 8] [--no-denoise] [--threads 8]// Files are <scene>-pathtracer-<backend>.png and timings.json. Run it through bash ~/.agents/tools/gpu-lock.sh: the GPU// backend takes the whole GPU for seconds at a time.@@ -35,7 +35,7 @@ const options = {setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);await mkdir(outputDirectory, { recursive: true });-const server = await createServer({ server: { host: '127.0.0.1', port: 0 }, logLevel: 'silent' });+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'] });@@ -51,9 +51,18 @@ try {const isRecipe = id.endsWith('.json');const recipe = isRecipe ? JSON.parse(await readFile(id, 'utf8')) : null;const name = isRecipe ? recipeName(id) : id;- const result = isRecipe- ? await page.evaluate(([sceneRecipe, tracerOptions]) => window.renderRecipePathTraced(sceneRecipe, tracerOptions), [recipe, { ...options, backend }])- : await page.evaluate(([sceneId, tracerOptions]) => window.renderReferencePathTraced(sceneId, tracerOptions), [id, { ...options, backend }]);+ let result;+ try {+ result = isRecipe+ ? await page.evaluate(([sceneRecipe, tracerOptions]) => window.renderRecipePathTraced(sceneRecipe, tracerOptions), [recipe, { ...options, backend }])+ : await page.evaluate(([sceneId, tracerOptions]) => window.renderReferencePathTraced(sceneId, tracerOptions), [id, { ...options, backend }]);+ } catch (error) {+ // The webgpu backend names the scene features it does not trace; record that and go on with the next scene.+ if (backend !== 'webgpu' || !/does not trace/.test(error.message)) throw error;+ timings[`${name}:${backend}`] = { unsupported: error.message.replace(/^.*Error: /, '') };+ console.log(name, backend, 'unsupported:', error.message.split('\n')[0]);+ continue;+ }await writeFile(`${outputDirectory}/${name}-pathtracer-${backend}.png`, Buffer.from(result.image, 'base64'));const { seconds, tracedSeconds, samples, triangles, gpu, gpuCompileSeconds } = result.report;timings[`${name}:${backend}`] = { seconds: Number(seconds.toFixed(2)), tracedSeconds: Number(tracedSeconds.toFixed(2)), samples, triangles, gpu, compileSeconds: gpuCompileSeconds };diff --git a/bench/webgpu-tracer/compare.sh b/bench/webgpu-tracer/compare.shindex 38fbee56..4926e245 100644--- a/bench/webgpu-tracer/compare.sh+++ b/bench/webgpu-tracer/compare.sh@@ -1,12 +1,12 @@#!/usr/bin/env bash-# Alternates the two backends three times at 1920 by 1080 and 64 samples, each trace as its own gpu-lock job (a light job).+# Alternates the WebGL2 kernel and the two WebGPU kernels three times at 1920 by 1080 and 64 samples, each trace as its own gpu-lock job (a light job).# The first pair runs in fresh Chrome profiles (cold shader caches), the later pairs reuse them (warm).# bash bench/webgpu-tracer/compare.sh <output directory>set -uOUT="${1:?output directory}"-rm -rf "$OUT/profile-webgl" "$OUT/profile-webgpu"+rm -rf "$OUT/profile-webgl" "$OUT/profile-wavefront" "$OUT/profile-megakernel"for RUN in 1 2 3; do- for VARIANT in webgpu webgl; do+ for VARIANT in wavefront megakernel webgl; dobash ~/.agents/tools/gpu-lock.sh node bench/webgpu-tracer/run.mjs "$OUT" "$VARIANT" --label "run$RUN" 2>&1 | cut -c1-1500donedonediff --git a/bench/webgpu-tracer/harness.js b/bench/webgpu-tracer/harness.jsindex 52a03ae8..0a658ec4 100644--- a/bench/webgpu-tracer/harness.js+++ b/bench/webgpu-tracer/harness.js@@ -1,7 +1,5 @@-// Page side of the issue #625 spike: builds the demo room trace scene once, then traces it with the WGSL megakernel-// (traceWithWebGpu) or with the shipped WebGL2 kernel (traceWithWebGl), undenoised, and returns timings and a tone mapped PNG.-import { KERNEL_SOURCE, WORKGROUP_SIZE } from './kernel.js';-import { packAtlas, packEnvironment, packLights, packMaterials, packNodes, packTriangles } from '/src/path-tracer-gpu-pack.js';+// Page side of the issue #625 timing: builds the demo room trace scene once, then traces it with the WebGPU tracer (traceWithWebGpu,+// wavefront or megakernel) or with the WebGL2 kernel (traceWithWebGl), undenoised, and returns timings and a tone mapped PNG.import { createCamera, toneMapToRgba8 } from '/src/path-tracer.js';import { buildTraceScene } from '/src/path-tracer-scene.js';@@ -51,122 +49,18 @@ async function traceWithWebGl(options) {return { gpu: traced.gpu, compileSeconds: first.compileSeconds, firstTotalSeconds, tracedSeconds, image: await pngBase64(traced.color, options.width, options.height) };}-function createStorageBuffer(device, data, label) {- const buffer = device.createBuffer({ label, size: Math.max(16, Math.ceil(data.byteLength / 4) * 4), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });- device.queue.writeBuffer(buffer, 0, data.buffer, data.byteOffset, data.byteLength);- return buffer;-}--function packAtlasWords(atlas) {- return new Uint32Array(atlas.data.buffer, atlas.data.byteOffset, Math.floor(atlas.data.byteLength / 4));-}--function writeParams(scene, camera, options, lightCount, atlas, sampleIndex) {- const buffer = new ArrayBuffer(12 * 16);- const floats = new Float32Array(buffer);- const ints = new Int32Array(buffer);- const words = new Uint32Array(buffer);- const { sun } = scene.lights;- const { environment } = scene;- floats.set([...camera.eye, 0], 0);- floats.set([...camera.forward, 0], 4);- floats.set([...camera.right, 0], 8);- floats.set([...camera.above, 0], 12);- floats.set([...(sun?.direction ?? [0, 1, 0]), 0], 16);- floats.set([...(sun?.color ?? [0, 0, 0]), Math.cos(Math.PI / 360)], 20);- floats.set([environment?.width ?? 1, environment?.height ?? 1, environment?.intensity ?? 1, environment?.total ?? 1], 24);- floats.set([environment?.cosine ?? 1, environment?.sine ?? 0, scene.surfaceOffset, scene.farDistance], 28);- floats.set([camera.halfWidth, camera.halfHeight, options.fireflyClamp, 0], 32);- ints.set([options.width, options.height, options.bounces, lightCount], 36);- ints.set([(sun ? 1 : 0) + lightCount + (environment ? 1 : 0), sun ? 1 : 0, environment ? 1 : 0, sampleIndex], 40);- words.set([options.seed >>> 0, atlas.width, 0, 0], 44);- return buffer;-}--async function traceWithWebGpu(options) {+// The first call compiles the kernel (its compileSeconds), so tracedSeconds is taken from a second, warm call. Upload to the+// card and readback are inside tracedSeconds, as they are for the WebGL2 kernel.+async function traceWithWebGpu(options, kernel) {+ const { traceOnWebGpu } = await import('/src/path-tracer-webgpu.js');const { scene, camera } = prepared;- const { width, height, samples } = options;- const pixelCount = width * height;- const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });- const device = await adapter.requestDevice({- requiredLimits: {- maxStorageBufferBindingSize: Math.min(adapter.limits.maxStorageBufferBindingSize, 1 << 30),- maxBufferSize: Math.min(adapter.limits.maxBufferSize, 1 << 30),- },- });- device.addEventListener('uncapturederror', event => console.log('WEBGPU ERROR', event.error.message));- const compileStarted = performance.now();- const module = device.createShaderModule({ label: 'path tracer', code: KERNEL_SOURCE });- const info = await module.getCompilationInfo();- const errors = info.messages.filter(message => message.type === 'error').map(message => `${message.lineNum}: ${message.message}`);- if (errors.length > 0) throw new Error(`WGSL did not compile:\n${errors.slice(0, 12).join('\n')}`);- const pipeline = await device.createComputePipelineAsync({ layout: 'auto', compute: { module, entryPoint: 'main' } });- const compileSeconds = (performance.now() - compileStarted) / 1000;- // Building the same pipeline again measures the in-process cache, not the driver compile.- const secondStarted = performance.now();- await device.createComputePipelineAsync({ layout: 'auto', compute: { module, entryPoint: 'main' } });- const secondCompileSeconds = (performance.now() - secondStarted) / 1000;-- const uploadStarted = performance.now();- const atlas = packAtlas(scene.materials);- const lights = packLights(scene.lights);- const environment = packEnvironment(scene.environment);- const environmentTables = new Float32Array(environment ? environment.height + environment.width * environment.height : 4);- if (environment) {- environmentTables.set(environment.rows.data.subarray(0, environment.height), 0);- environmentTables.set(environment.pixels.data.subarray(0, environment.width * environment.height), environment.height);- }- const buffers = [- createStorageBuffer(device, packNodes(scene.bvh).data, 'nodes'),- createStorageBuffer(device, packTriangles(scene).data, 'triangles'),- createStorageBuffer(device, packMaterials(scene.materials, atlas).data, 'materials'),- createStorageBuffer(device, lights.table.data, 'lights'),- createStorageBuffer(device, packAtlasWords(atlas), 'atlas'),- createStorageBuffer(device, environment?.colors ?? new Float32Array(4), 'environment colors'),- createStorageBuffer(device, environmentTables, 'environment tables'),- ];- const accumulation = device.createBuffer({ label: 'accumulation', size: pixelCount * 4 * 16, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });- const parameters = device.createBuffer({ label: 'parameters', size: 12 * 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });- const bindGroup = device.createBindGroup({- layout: pipeline.getBindGroupLayout(0),- entries: [parameters, ...buffers, accumulation].map((buffer, binding) => ({ binding, resource: { buffer } })),- });- await device.queue.onSubmittedWorkDone();- const uploadSeconds = (performance.now() - uploadStarted) / 1000;-- const traceStarted = performance.now();- const sampleSeconds = [];- for (let sampleIndex = 0; sampleIndex < samples; sampleIndex++) {- const sampleStarted = performance.now();- device.queue.writeBuffer(parameters, 0, writeParams(scene, camera, options, lights.count, atlas, sampleIndex));- const encoder = device.createCommandEncoder();- const pass = encoder.beginComputePass();- pass.setPipeline(pipeline);- pass.setBindGroup(0, bindGroup);- pass.dispatchWorkgroups(Math.ceil(width / WORKGROUP_SIZE), Math.ceil(height / WORKGROUP_SIZE));- pass.end();- device.queue.submit([encoder.finish()]);- await device.queue.onSubmittedWorkDone();- sampleSeconds.push((performance.now() - sampleStarted) / 1000);- }- const dispatchSeconds = (performance.now() - traceStarted) / 1000;-- const readback = device.createBuffer({ size: pixelCount * 16, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });- const encoder = device.createCommandEncoder();- encoder.copyBufferToBuffer(accumulation, 0, readback, 0, pixelCount * 16);- device.queue.submit([encoder.finish()]);- await readback.mapAsync(GPUMapMode.READ);- const sums = new Float32Array(readback.getMappedRange());- const color = new Float32Array(pixelCount * 3);- for (let pixel = 0; pixel < pixelCount; pixel++) {- for (let channel = 0; channel < 3; channel++) color[pixel * 3 + channel] = sums[pixel * 4 + channel] / samples;- }- const tracedSeconds = (performance.now() - traceStarted) / 1000;- const image = await pngBase64(color, width, height);- return {- gpu: `${adapter.info.vendor} ${adapter.info.architecture}`, compileSeconds, secondCompileSeconds, uploadSeconds, dispatchSeconds, tracedSeconds,- firstSampleSeconds: sampleSeconds[0], medianSampleSeconds: median(sampleSeconds), image,- };+ const firstStarted = performance.now();+ const first = await traceOnWebGpu(scene, camera, { ...options, samples: 1, kernel }, () => {});+ const firstTotalSeconds = (performance.now() - firstStarted) / 1000;+ const started = performance.now();+ const traced = await traceOnWebGpu(scene, camera, { ...options, kernel }, () => {});+ const tracedSeconds = (performance.now() - started) / 1000;+ return { gpu: traced.gpu, kernel, compileSeconds: first.compileSeconds, firstTotalSeconds, tracedSeconds, image: await pngBase64(traced.color, options.width, options.height) };}window.prepareScene = prepareScene;diff --git a/bench/webgpu-tracer/run.mjs b/bench/webgpu-tracer/run.mjsindex def8a08a..601ae27a 100644--- a/bench/webgpu-tracer/run.mjs+++ b/bench/webgpu-tracer/run.mjs@@ -1,6 +1,6 @@// One timed trace of the demo room with one backend, in a headless Chrome whose profile persists per backend (so the first// run in a fresh profile is the cold compile and later runs are warm). Run it through bash ~/.agents/tools/gpu-lock.sh.-// node bench/webgpu-tracer/run.mjs <output directory> <webgl|webgpu> [--samples 64] [--width 1920] [--height 1080] [--label run1]+// node bench/webgpu-tracer/run.mjs <output directory> <webgl|wavefront|megakernel> [--samples 64] [--width 1920] [--height 1080] [--label run1] [--sort on|off]// Writes <variant>-<label>.png and <variant>-<label>.json; the profile lives in <output directory>/profile-<variant>.import { mkdir, readFile, writeFile } from 'node:fs/promises';import { constants, setPriority } from 'node:os';@@ -25,6 +25,7 @@ const options = {bounces: 8,seed: 0,fireflyClamp: 20,+ sortByMaterial: valueAfter('--sort', 'off') === 'on',};const label = valueAfter('--label', 'run1');@@ -48,7 +49,7 @@ try {await page.waitForFunction(() => window.harnessReady, null, { timeout: 180000 });const recipe = JSON.parse(await readFile('tests/fixtures/demo-room.recipe.json', 'utf8'));const scene = await page.evaluate(([sceneRecipe, width, height]) => window.prepareScene(sceneRecipe, width, height), [recipe, options.width, options.height]);- const result = await page.evaluate(([name, tracerOptions]) => (name === 'webgl' ? window.traceWithWebGl(tracerOptions) : window.traceWithWebGpu(tracerOptions)), [variant, options]);+ const result = await page.evaluate(([name, tracerOptions]) => (name === 'webgl' ? window.traceWithWebGl(tracerOptions) : window.traceWithWebGpu(tracerOptions, name)), [variant, options]);const { image, ...numbers } = result;await writeFile(`${outputDirectory}/${variant}-${label}.png`, Buffer.from(image, 'base64'));const record = { variant, label, ...options, ...scene, ...numbers };diff --git a/bench/webgpu-tracer/validate.mjs b/bench/webgpu-tracer/validate.mjsindex 14fbe141..8cb0564c 100644--- a/bench/webgpu-tracer/validate.mjs+++ b/bench/webgpu-tracer/validate.mjs@@ -1,4 +1,4 @@-// Compiles the WGSL kernel on SwiftShader's Vulkan adapter (CPU only, no GPU queue) and prints every error with its line.+// Compiles both WGSL kernels on SwiftShader's Vulkan adapter (CPU only, no GPU queue) and prints every error with its line, per kernel.// node bench/webgpu-tracer/validate.mjsimport { chromium } from 'playwright';import { createServer } from 'vite';@@ -11,12 +11,15 @@ try {const page = await browser.newPage();await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/bench/webgpu-tracer/harness.html`);const messages = await page.evaluate(async () => {- const { KERNEL_SOURCE } = await import('/bench/webgpu-tracer/kernel.js');+ const { MEGAKERNEL_SOURCE, WAVEFRONT_SOURCE } = await import('/src/path-tracer-webgpu-kernel.js');const adapter = await navigator.gpu.requestAdapter();const device = await adapter.requestDevice();- const module = device.createShaderModule({ code: KERNEL_SOURCE });- const info = await module.getCompilationInfo();- return info.messages.map(message => `${message.type} ${message.lineNum}:${message.linePos} ${message.message}`);+ const lines = [];+ for (const [name, code] of [['megakernel', MEGAKERNEL_SOURCE], ['wavefront', WAVEFRONT_SOURCE]]) {+ const info = await device.createShaderModule({ code }).getCompilationInfo();+ for (const message of info.messages) lines.push(`${name} ${message.type} ${message.lineNum}:${message.linePos} ${message.message}`);+ }+ return lines;});console.log(messages.length === 0 ? 'WGSL ok' : messages.join('\n'));} finally {diff --git a/changes/625.md b/changes/625.mdnew file mode 100644index 00000000..0b8b7417--- /dev/null+++ b/changes/625.md@@ -0,0 +1 @@+- The path tracer has a third backend, `backend: 'webgpu'`: the WebGL2 kernel written as WGSL compute (`src/path-tracer-webgpu.js`, loaded only for this backend, so the core bundle does not grow). It compiles in about a second instead of 8 to 20, matches the WebGL2 backend within 0.002 FLIP on the 16 reference scenes, and traces the demo room faster. It throws a clear error without `navigator.gpu`, and names volume fog and subsurface scattering (not ported yet) so callers fall back to `gpu`. No default changes (#625)diff --git a/changes/625.size.md b/changes/625.size.mdnew file mode 100644index 00000000..8f47488e--- /dev/null+++ b/changes/625.size.md@@ -0,0 +1 @@+- entry:path-tracer+lazy: the WebGPU path tracer backend adds two WGSL kernels (the megakernel and the wavefront, which share one prelude) and about 300 lines of host code, loaded only by `backend: 'webgpu'`; the core bundle is unchanged and it buys a kernel that compiles in about a second instead of 8 to 20diff --git a/bench/webgpu-tracer/kernel.js b/src/path-tracer-webgpu-kernel.jssimilarity index 71%rename from bench/webgpu-tracer/kernel.jsrename to src/path-tracer-webgpu-kernel.jsindex 79deb948..7ec5883a 100644--- a/bench/webgpu-tracer/kernel.js+++ b/src/path-tracer-webgpu-kernel.js@@ -1,12 +1,17 @@-// Spike for issue #625: the GPU path tracer kernel of src/path-tracer-gpu-shader.js written as one WGSL compute shader (a-// megakernel: one invocation traces one pixel's whole path for one sample). The scene tables are the same packed arrays-// (src/path-tracer-gpu-pack.js) bound as storage buffers instead of float textures, and the random numbers, light sampling-// order and shading follow the GLSL line by line, so one seed gives the same picture. Left out on purpose: fog and-// subsurface (the demo room has neither) and the texel bake entry point.+// The WGSL kernels of the WebGPU path tracer (issue #625). The scene tables are the packed arrays of+// path-tracer-gpu-pack.js bound as storage buffers; the random numbers, light sampling order and shading follow the GLSL+// kernel of path-tracer-gpu-shader.js line by line, so one seed gives the same picture. Two ways to run the same maths:+// MEGAKERNEL_SOURCE: one invocation traces one pixel's whole path (entry point `main`).+// WAVEFRONT_SOURCE: path state lives in a storage buffer and the path is split into kernels (generate, extend, shade,+// shadow, resolve); after extend the hits are binned by material so that neighbouring invocations of shade run the same material.+// Left out: volume fog, subsurface and the texel bake (the host throws a clear error for the first two).export const WORKGROUP_SIZE = 8;+export const WAVEFRONT_WORKGROUP_SIZE = 64;+/** vec4 slots of path state per path; the wavefront section below names each one. */+export const PATH_STATE_VECTORS = 9;-export const KERNEL_SOURCE = /* wgsl */ `+const COMMON_SOURCE = /* wgsl */ `const PI: f32 = 3.14159265358979;const TWO_PI: f32 = 6.28318530717959;const TRIANGLE_TEXELS: i32 = 9;@@ -32,6 +37,8 @@ struct Params {sizeBouncesLights: vec4<i32>,emittersFlagsSample: vec4<i32>,seedAndAtlas: vec4<u32>,+ tileAndDepth: vec4<u32>,+ shadowSlots: vec4<u32>,}@group(0) @binding(0) var<uniform> params: Params;@@ -811,22 +818,6 @@ fn sampleEmitter(depth: i32, normal: vec3<f32>, emitter: i32) {addDirect(depth, normal, distance, weightMode);}-// The first hit lights from every emitter; later hits draw one, and divide by the chance of drawing it.-fn addLights(depth: i32, normal: vec3<f32>) {- let emitterCount = params.emittersFlagsSample.x;- if (depth == 0 || emitterCount <= 1) {- selectionProbability = 1.0;- for (var emitter = 0; emitter < emitterCount; emitter++) {- sampleEmitter(depth, normal, emitter);- flushShadowRay();- }- return;- }- selectionProbability = 1.0 / f32(emitterCount);- sampleEmitter(depth, normal, i32(floor(nextRandom() * f32(emitterCount))));- flushShadowRay();-}-fn addEscape(depth: i32, previousPdf: f32, afterMirror: bool) {if (params.emittersFlagsSample.z == 0) { return; }let sky = environmentRadiance(direction);@@ -845,7 +836,24 @@ fn survivesRoulette(depth: i32) -> bool {throughput /= survival;return true;}+`;+export const MEGAKERNEL_SOURCE = COMMON_SOURCE + /* wgsl */ `+// The first hit lights from every emitter; later hits draw one, and divide by the chance of drawing it.+fn addLights(depth: i32, normal: vec3<f32>) {+ let emitterCount = params.emittersFlagsSample.x;+ if (depth == 0 || emitterCount <= 1) {+ selectionProbability = 1.0;+ for (var emitter = 0; emitter < emitterCount; emitter++) {+ sampleEmitter(depth, normal, emitter);+ flushShadowRay();+ }+ return;+ }+ selectionProbability = 1.0 / f32(emitterCount);+ sampleEmitter(depth, normal, i32(floor(nextRandom() * f32(emitterCount))));+ flushShadowRay();+}fn tracePath(origin: vec3<f32>, startDirection: vec3<f32>, pixel: u32, sampleIndex: u32) {resetRandom(pixel, sampleIndex, params.seedAndAtlas.x);radiance = vec3<f32>(0.0);@@ -942,3 +950,351 @@ fn main(@builtin(global_invocation_id) id: vec3<u32>) {accumulation[3u * pixelCount + pixel] += vec4<f32>(sampleLuminance, sampleLuminance * sampleLuminance, firstLegEscaped, 0.0);}`;++export const WAVEFRONT_SOURCE = COMMON_SOURCE + /* wgsl */ `+// Path state: PATH_STATE_VECTORS vec4<u32> per path (floats are stored as their bits, so nothing is ever rounded or+// canonicalised on the way through memory), then the shadow records, three vec4 per emitter slot of a path.+// 0 origin, previous pdf 1 direction, selection probability 2 throughput 3 radiance, first leg escaped+// 4 albedo 5 normal, depth 6 start of the last ray segment, distance in it 7 u, v, distance before the segment+// 8 random state, flags, hit triangle slot, material+// Shadow record: 0 origin, limit 1 direction, unused 2 amount, 1 when the ray is pending.+@group(0) @binding(9) var<storage, read_write> pathState: array<vec4<u32>>;+// Word 0 counts the hits of this bounce; then per material the count and the write cursor; then the hits sorted by material.+@group(0) @binding(10) var<storage, read_write> binQueue: array<atomic<u32>>;++const PATH_STATE_VECTORS: u32 = ${PATH_STATE_VECTORS}u;+const FLAG_ALIVE: u32 = 1u;+const FLAG_AFTER_MIRROR: u32 = 2u;+const FLAG_HIT: u32 = 4u;+const FLAG_SHADED: u32 = 8u;++fn loadVector(index: u32) -> vec4<f32> {+ return bitcast<vec4<f32>>(pathState[index]);+}++fn storeVector(index: u32, value: vec4<f32>) {+ pathState[index] = bitcast<vec4<u32>>(value);+}++fn tilePathCount() -> u32 {+ return params.tileAndDepth.y;+}++fn currentDepth() -> i32 {+ return i32(params.tileAndDepth.z);+}++fn materialCount() -> u32 {+ return params.tileAndDepth.w;+}++// How many shadow rays a path casts at this depth: every emitter at the first hit, one afterwards.+fn emitterSlotCount(depth: i32) -> u32 {+ let emitterCount = u32(max(params.emittersFlagsSample.x, 0));+ if (depth == 0 || emitterCount <= 1u) { return emitterCount; }+ return 1u;+}++fn shadowRecordBase(path: u32, slot: u32) -> u32 {+ return tilePathCount() * PATH_STATE_VECTORS + (path * params.shadowSlots.x + slot) * 3u;+}++fn storeShadowRecord(path: u32, slot: u32) {+ let base = shadowRecordBase(path, slot);+ if (shadowPending) {+ storeVector(base, vec4<f32>(shadowOrigin, shadowLimit));+ storeVector(base + 1u, vec4<f32>(shadowDirection, 0.0));+ storeVector(base + 2u, vec4<f32>(shadowAmount, 1.0));+ } else {+ storeVector(base + 2u, vec4<f32>(0.0));+ }+}++// Paths are numbered in blocks of 8 by 8 pixels, so the 64 paths of a workgroup look at neighbouring pixels (rays that start+// close together traverse the same part of the BVH). Numbers past the edge of the image have no pixel.+fn blockedPixel(globalPath: u32) -> vec2<u32> {+ let blocksPerRow = (u32(params.sizeBouncesLights.x) + 7u) / 8u;+ let block = globalPath / 64u;+ let within = globalPath % 64u;+ return vec2<u32>((block % blocksPerRow) * 8u + within % 8u, (block / blocksPerRow) * 8u + within / 8u);+}++fn queuedPath(position: u32) -> u32 {+ return atomicLoad(&binQueue[1u + 2u * materialCount() + position]);+}++@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn generatePaths(@builtin(global_invocation_id) id: vec3<u32>) {+ if (id.x >= tilePathCount()) { return; }+ let width = u32(params.sizeBouncesLights.x);+ let height = u32(params.sizeBouncesLights.y);+ let coordinates = blockedPixel(params.tileAndDepth.x + id.x);+ let pixelX = coordinates.x;+ let pixelY = coordinates.y;+ if (pixelX >= width || pixelY >= height) {+ pathState[id.x * PATH_STATE_VECTORS + 8u] = vec4<u32>(0u);+ return;+ }+ let pixel = pixelY * width + pixelX;+ let sampleIndex = u32(params.emittersFlagsSample.w);+ let seed = params.seedAndAtlas.x;+ let jitterX = hashJitter(pixel, sampleIndex, seed, 1u);+ let jitterY = hashJitter(pixel, sampleIndex, seed, 2u);+ let screenX = ((f32(pixelX) + jitterX) / f32(width) * 2.0 - 1.0) * params.cameraAndClamp.x;+ let screenY = (1.0 - (f32(pixelY) + jitterY) / f32(height) * 2.0) * params.cameraAndClamp.y;+ let rayDirection = normalize(params.forward.xyz + params.right.xyz * screenX + params.above.xyz * screenY);+ resetRandom(pixel, sampleIndex, seed);+ let base = id.x * PATH_STATE_VECTORS;+ storeVector(base, vec4<f32>(params.eye.xyz, 0.0));+ storeVector(base + 1u, vec4<f32>(rayDirection, 1.0));+ storeVector(base + 2u, vec4<f32>(1.0, 1.0, 1.0, 0.0));+ storeVector(base + 3u, vec4<f32>(0.0));+ storeVector(base + 4u, vec4<f32>(1.0, 1.0, 1.0, 0.0));+ storeVector(base + 5u, vec4<f32>(0.0, 0.0, 1.0, 0.0));+ pathState[base + 8u] = vec4<u32>(rngState, FLAG_ALIVE | FLAG_AFTER_MIRROR, 0u, 0u);+}++@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn resetBins(@builtin(global_invocation_id) id: vec3<u32>) {+ if (id.x == 0u) { atomicStore(&binQueue[0], 0u); }+ if (id.x < materialCount()) { atomicStore(&binQueue[1u + id.x], 0u); }+}++// Finds the nearest solid hit of every live path (stepping through the transparent texels of cutout materials), adds the+// sky to paths that left the scene, and counts the hits per material.+@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn extendPaths(@builtin(global_invocation_id) id: vec3<u32>) {+ if (id.x >= tilePathCount()) { return; }+ let base = id.x * PATH_STATE_VECTORS;+ var pathMeta = pathState[base + 8u];+ let flags = pathMeta.y;+ if ((flags & FLAG_ALIVE) == 0u) { return; }+ let originPrevious = loadVector(base);+ let directionSelection = loadVector(base + 1u);+ let rayDirection = directionSelection.xyz;+ let farDistance = params.environmentRotationAndRays.w;+ let surfaceOffset = params.environmentRotationAndRays.z;+ var start = originPrevious.xyz;+ var travelled = 0.0;+ var found = false;+ for (var attempt = 0; attempt < ALPHA_STEP_LIMIT; attempt++) {+ traceRay(start, rayDirection, farDistance, false);+ if (nearestSlot < 0) { break; }+ let material = i32(triangles[nearestSlot * TRIANGLE_TEXELS].w) * MATERIAL_TEXELS;+ let cutoff = materials[material + 3].z;+ if (cutoff == 0.0 || alphaAtNearestHit() >= cutoff) {+ found = true;+ break;+ }+ let advance = nearestDistance + surfaceOffset;+ travelled += advance;+ start += rayDirection * advance;+ }+ if (found) {+ let materialIndex = u32(triangles[nearestSlot * TRIANGLE_TEXELS].w);+ storeVector(base + 6u, vec4<f32>(start, nearestDistance));+ storeVector(base + 7u, vec4<f32>(nearestU, nearestV, travelled, 0.0));+ pathMeta = vec4<u32>(pathMeta.x, flags | FLAG_HIT, u32(nearestSlot), materialIndex);+ pathState[base + 8u] = pathMeta;+ if (params.shadowSlots.y == 1u) { atomicAdd(&binQueue[1u + materialIndex], 1u); }+ return;+ }+ var radianceData = loadVector(base + 3u);+ if (currentDepth() == 0) { radianceData.w = 1.0; }+ direction = rayDirection;+ throughput = loadVector(base + 2u).xyz;+ radiance = radianceData.xyz;+ selectionProbability = directionSelection.w;+ addEscape(currentDepth(), originPrevious.w, (flags & FLAG_AFTER_MIRROR) != 0u);+ storeVector(base + 3u, vec4<f32>(radiance, radianceData.w));+ pathMeta.y = flags & ~(FLAG_ALIVE | FLAG_HIT);+ pathState[base + 8u] = pathMeta;+}++@compute @workgroup_size(1)+fn scanBins() {+ let count = materialCount();+ var running = 0u;+ for (var material = 0u; material < count; material++) {+ atomicStore(&binQueue[1u + count + material], running);+ running += atomicLoad(&binQueue[1u + material]);+ }+ atomicStore(&binQueue[0], running);+}++@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn scatterPaths(@builtin(global_invocation_id) id: vec3<u32>) {+ if (id.x >= tilePathCount()) { return; }+ let pathMeta = pathState[id.x * PATH_STATE_VECTORS + 8u];+ if ((pathMeta.y & FLAG_HIT) == 0u) { return; }+ let count = materialCount();+ let position = atomicAdd(&binQueue[1u + count + pathMeta.w], 1u);+ atomicStore(&binQueue[1u + 2u * count + position], id.x);+}++// Shades the hits in material order: emission, features, one shadow record per emitter, then the next direction. Draws+// random numbers in the order of the megakernel, so the picture is the same.+@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn shadePaths(@builtin(global_invocation_id) id: vec3<u32>) {+ var path = id.x;+ if (params.shadowSlots.y == 1u) {+ if (id.x >= atomicLoad(&binQueue[0])) { return; }+ path = queuedPath(id.x);+ } else {+ if (id.x >= tilePathCount()) { return; }+ if ((pathState[id.x * PATH_STATE_VECTORS + 8u].y & FLAG_HIT) == 0u) { return; }+ }+ let base = path * PATH_STATE_VECTORS;+ let depth = currentDepth();+ let originPrevious = loadVector(base);+ let directionSelection = loadVector(base + 1u);+ let radianceData = loadVector(base + 3u);+ let hitStart = loadVector(base + 6u);+ let hitInfo = loadVector(base + 7u);+ var pathMeta = pathState[base + 8u];+ rngState = pathMeta.x;+ direction = directionSelection.xyz;+ selectionProbability = directionSelection.w;+ throughput = loadVector(base + 2u).xyz;+ radiance = radianceData.xyz;+ nearestSlot = i32(pathMeta.z);+ nearestU = hitInfo.x;+ nearestV = hitInfo.y;+ _ = fillHit(hitStart.xyz, direction, hitStart.w);+ hitDistance += hitInfo.z;+ let entering = dot(hitNormal, direction) < 0.0;+ let normal = select(-hitNormal, hitNormal, entering);+ let isGlass = hitTransmission > 0.0 && nextRandom() < hitTransmission;+ if (depth == 0) {+ storeVector(base + 4u, vec4<f32>(select(hitColor, vec3<f32>(1.0), isGlass), 0.0));+ storeVector(base + 5u, vec4<f32>(normal, hitDistance));+ }+ addRadiance(depth, throughput * hitEmission);+ if (params.emittersFlagsSample.y != 0) { sunFrame = buildFrame(params.sunDirection.xyz); }+ if (isGlass) {+ let slotCount = emitterSlotCount(depth);+ for (var slot = 0u; slot < slotCount; slot++) {+ shadowPending = false;+ storeShadowRecord(path, slot);+ }+ } else {+ prepareSurface(normal, -direction);+ let emitterCount = params.emittersFlagsSample.x;+ if (depth == 0 || emitterCount <= 1) {+ selectionProbability = 1.0;+ for (var emitter = 0; emitter < emitterCount; emitter++) {+ shadowPending = false;+ sampleEmitter(depth, normal, emitter);+ storeShadowRecord(path, u32(emitter));+ }+ } else {+ selectionProbability = 1.0 / f32(emitterCount);+ shadowPending = false;+ sampleEmitter(depth, normal, i32(floor(nextRandom() * f32(emitterCount))));+ storeShadowRecord(path, 0u);+ }+ }+ var alive = depth < params.sizeBouncesLights.z;+ var afterMirror = (pathMeta.y & FLAG_AFTER_MIRROR) != 0u;+ var previousPdf = originPrevious.w;+ if (alive && isGlass) {+ let alpha = roughnessToAlpha(hitRoughness);+ let selectionUnit = nextRandom();+ let firstUnit = nextRandom();+ let secondUnit = nextRandom();+ if (sampleGlass(normal, -direction, entering, hitIor, alpha, selectionUnit, firstUnit, secondUnit)) {+ direction = sampledDirection;+ if (dot(direction, normal) < 0.0) { throughput *= hitColor; }+ afterMirror = true;+ } else {+ alive = false;+ }+ } else if (alive) {+ let lobeUnit = nextRandom();+ let firstUnit = nextRandom();+ let secondUnit = nextRandom();+ let isMirror = sampleSurface(lobeUnit, firstUnit, secondUnit);+ direction = sampledDirection;+ let cosine = dot(direction, normal);+ if (cosine <= 0.0) {+ alive = false;+ } else if (isMirror) {+ throughput *= mirrorWeight();+ afterMirror = true;+ } else {+ evaluateSurface(direction);+ if (surfacePdf > 0.0) {+ throughput *= surfaceValue * cosine / surfacePdf;+ previousPdf = surfacePdf;+ afterMirror = false;+ } else {+ alive = false;+ }+ }+ }+ var nextOrigin = originPrevious.xyz;+ if (alive) {+ nextOrigin = hitPoint + direction * params.environmentRotationAndRays.z;+ alive = survivesRoulette(depth);+ }+ storeVector(base, vec4<f32>(nextOrigin, previousPdf));+ storeVector(base + 1u, vec4<f32>(direction, selectionProbability));+ storeVector(base + 2u, vec4<f32>(throughput, 0.0));+ storeVector(base + 3u, vec4<f32>(radiance, radianceData.w));+ pathMeta.x = rngState;+ pathMeta.y = select(0u, FLAG_ALIVE, alive) | select(0u, FLAG_AFTER_MIRROR, afterMirror) | FLAG_SHADED;+ pathState[base + 8u] = pathMeta;+}++// Traces the shadow rays the shade kernel recorded and adds the light that gets through. It walks the paths in pixel order+// (not material order) so that neighbouring invocations cast rays from neighbouring points.+@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn shadowPaths(@builtin(global_invocation_id) id: vec3<u32>) {+ if (id.x >= tilePathCount()) { return; }+ let path = id.x;+ let base = path * PATH_STATE_VECTORS;+ var pathMeta = pathState[base + 8u];+ if ((pathMeta.y & FLAG_SHADED) == 0u) { return; }+ pathMeta.y = pathMeta.y & ~FLAG_SHADED;+ pathState[base + 8u] = pathMeta;+ let depth = currentDepth();+ let radianceData = loadVector(base + 3u);+ radiance = radianceData.xyz;+ let slotCount = emitterSlotCount(depth);+ for (var slot = 0u; slot < slotCount; slot++) {+ let recordBase = shadowRecordBase(path, slot);+ let amount = loadVector(recordBase + 2u);+ if (amount.w == 0.0) { continue; }+ let origin = loadVector(recordBase);+ let rayDirection = loadVector(recordBase + 1u).xyz;+ if (!occluded(origin.xyz, rayDirection, origin.w)) { addRadiance(depth, amount.xyz); }+ }+ storeVector(base + 3u, vec4<f32>(radiance, radianceData.w));+}++// Adds the finished sample of every path of the tile to the accumulation planes, dropping non-finite values as the megakernel does.+@compute @workgroup_size(${WAVEFRONT_WORKGROUP_SIZE})+fn resolvePaths(@builtin(global_invocation_id) id: vec3<u32>) {+ if (id.x >= tilePathCount()) { return; }+ let coordinates = blockedPixel(params.tileAndDepth.x + id.x);+ if (coordinates.x >= u32(params.sizeBouncesLights.x) || coordinates.y >= u32(params.sizeBouncesLights.y)) { return; }+ let base = id.x * PATH_STATE_VECTORS;+ let radianceData = loadVector(base + 3u);+ let normalDepth = loadVector(base + 5u);+ var sampleRadiance = radianceData.xyz;+ var sampleAlbedo = loadVector(base + 4u).xyz;+ var sampleNormal = normalDepth.xyz;+ var sampleDepth = normalDepth.w;+ if (!(all(sampleRadiance >= vec3<f32>(0.0)) && all(sampleRadiance < vec3<f32>(1e30)))) { sampleRadiance = vec3<f32>(0.0); }+ if (!(sampleDepth >= 0.0 && sampleDepth < 1e30)) { sampleDepth = 0.0; }+ if (!(all(sampleNormal >= vec3<f32>(-1.5)) && all(sampleNormal < vec3<f32>(1.5)))) { sampleNormal = vec3<f32>(0.0, 0.0, 1.0); }+ if (!(all(sampleAlbedo >= vec3<f32>(0.0)) && all(sampleAlbedo < vec3<f32>(1e30)))) { sampleAlbedo = vec3<f32>(1.0); }+ let sampleLuminance = luminance(sampleRadiance);+ let pixel = coordinates.y * u32(params.sizeBouncesLights.x) + coordinates.x;+ let pixelCount = u32(params.sizeBouncesLights.x * params.sizeBouncesLights.y);+ accumulation[pixel] += vec4<f32>(sampleRadiance, sampleDepth);+ accumulation[pixelCount + pixel] += vec4<f32>(sampleAlbedo, 0.0);+ accumulation[2u * pixelCount + pixel] += vec4<f32>(sampleNormal, 0.0);+ accumulation[3u * pixelCount + pixel] += vec4<f32>(sampleLuminance, sampleLuminance * sampleLuminance, radianceData.w, 0.0);+}+`;diff --git a/src/path-tracer-webgpu.js b/src/path-tracer-webgpu.jsnew file mode 100644index 00000000..1f3e6fb9--- /dev/null+++ b/src/path-tracer-webgpu.js@@ -0,0 +1,304 @@+import { MEGAKERNEL_SOURCE, PATH_STATE_VECTORS, WAVEFRONT_SOURCE, WAVEFRONT_WORKGROUP_SIZE, WORKGROUP_SIZE } from './path-tracer-webgpu-kernel.js';+import { packAtlas, packEnvironment, packLights, packMaterials, packNodes, packTriangles, sceneUsesSubsurface } from './path-tracer-gpu-pack.js';++// The WebGPU backend of the path tracer (issue #625): the same scene tables, camera, options and random numbers as the+// WebGL2 backend (path-tracer-gpu.js) go in, the same buffers come out. The tracer is WGSL compute, so a page needs+// navigator.gpu; without it traceOnWebGpu throws and the caller falls back to the "gpu" or "cpu" backend. Fog, subsurface and+// the texel bake are not ported: a scene that uses fog or subsurface throws an error that names it.++/** `megakernel`: one invocation per path (the default, faster on the demo room). `wavefront`: generate, extend, shade, shadow kernels with the path state in a buffer. */+export const WEBGPU_KERNELS = ['megakernel', 'wavefront'];+export const DEFAULT_WEBGPU_KERNEL = 'megakernel';+/** Whether the wavefront bins the hits by material before shading them (decided by the measurement in docs/webgpu-decision.md). */+export const DEFAULT_SORT_BY_MATERIAL = false;++const PARAMETER_BYTES = 14 * 16;+// Dynamic uniform offsets must be a multiple of minUniformBufferOffsetAlignment, which is 256 on every adapter.+const PARAMETER_SLOT_BYTES = 256;+const STORAGE_BUFFER_COUNT = 10;+const MAXIMUM_TILE_PATHS = 1 << 19;+// The path state of one tile stays under the default maxStorageBufferBindingSize.+const MAXIMUM_STATE_BYTES = 1 << 27;+const MAXIMUM_BUFFER_BYTES = 1 << 30;+const WAVEFRONT_ENTRY_POINTS = ['generatePaths', 'resetBins', 'extendPaths', 'scanBins', 'scatterPaths', 'shadePaths', 'shadowPaths', 'resolvePaths'];++/** True when this page has WebGPU. Whether an adapter exists is only known after requesting one. */+export function isWebGpuTracerAvailable() {+ return typeof navigator !== 'undefined' && Boolean(navigator.gpu);+}++let session = null;+let kernelCompileCount = 0;++/** How many path tracing kernels this page has compiled so far: a job of many frames compiles each kernel once. */+export function webGpuKernelCompileCount() {+ return kernelCompileCount;+}++async function createSession() {+ if (!isWebGpuTracerAvailable()) {+ throw new Error('The WebGPU path tracer needs navigator.gpu, which this page does not have. Use backend "gpu" (WebGL2) or "cpu".');+ }+ const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });+ if (!adapter) throw new Error('The WebGPU path tracer found no WebGPU adapter. Use backend "gpu" (WebGL2) or "cpu".');+ if (adapter.limits.maxStorageBuffersPerShaderStage < STORAGE_BUFFER_COUNT) {+ throw new Error(`The WebGPU path tracer needs ${STORAGE_BUFFER_COUNT} storage buffers per shader stage and this adapter allows ${adapter.limits.maxStorageBuffersPerShaderStage}. Use backend "gpu".`);+ }+ const device = await adapter.requestDevice({+ requiredLimits: {+ maxStorageBuffersPerShaderStage: STORAGE_BUFFER_COUNT,+ maxStorageBufferBindingSize: Math.min(adapter.limits.maxStorageBufferBindingSize, MAXIMUM_BUFFER_BYTES),+ maxBufferSize: Math.min(adapter.limits.maxBufferSize, MAXIMUM_BUFFER_BYTES),+ },+ });+ const entries = [{ binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PARAMETER_BYTES } }];+ for (let binding = 1; binding < STORAGE_BUFFER_COUNT + 1; binding++) {+ entries.push({ binding, visibility: GPUShaderStage.COMPUTE, buffer: { type: binding <= 7 ? 'read-only-storage' : 'storage' } });+ }+ const bindGroupLayout = device.createBindGroupLayout({ entries });+ const info = adapter.info ?? {};+ return {+ device, bindGroupLayout, pipelineLayout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),+ gpu: `${info.vendor ?? 'webgpu'} ${info.architecture ?? ''}`.trim(), kernels: new Map(),+ };+}++async function getSession() {+ session ??= createSession().catch((error) => {+ session = null;+ throw error;+ });+ return session;+}++async function compileKernel(current, kernel) {+ const { device, pipelineLayout } = current;+ const started = performance.now();+ const module = device.createShaderModule({ label: `path tracer ${kernel}`, code: kernel === 'wavefront' ? WAVEFRONT_SOURCE : MEGAKERNEL_SOURCE });+ const info = await module.getCompilationInfo();+ const errors = info.messages.filter(message => message.type === 'error');+ if (errors.length > 0) throw new Error(`The WebGPU path tracer shader did not compile: ${errors.slice(0, 8).map(message => `${message.lineNum}: ${message.message}`).join('; ')}`);+ const entryPoints = kernel === 'wavefront' ? WAVEFRONT_ENTRY_POINTS : ['main'];+ const pipelines = await Promise.all(entryPoints.map(entryPoint => device.createComputePipelineAsync({ layout: pipelineLayout, compute: { module, entryPoint } })));+ kernelCompileCount++;+ return { pipelines: Object.fromEntries(entryPoints.map((entryPoint, index) => [entryPoint, pipelines[index]])), compileSeconds: (performance.now() - started) / 1000 };+}++async function getKernel(current, kernel) {+ if (!current.kernels.has(kernel)) current.kernels.set(kernel, compileKernel(current, kernel));+ return current.kernels.get(kernel);+}++function createStorageBuffer(device, data, label) {+ const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);+ const buffer = device.createBuffer({ label, size: Math.max(16, Math.ceil(bytes.byteLength / 4) * 4), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });+ device.queue.writeBuffer(buffer, 0, bytes);+ return buffer;+}++function atlasWords(atlas) {+ return new Uint32Array(atlas.data.buffer, atlas.data.byteOffset, Math.floor(atlas.data.byteLength / 4));+}++function uploadScene(device, scene) {+ const atlas = packAtlas(scene.materials);+ const lights = packLights(scene.lights);+ const environment = packEnvironment(scene.environment);+ const environmentTables = new Float32Array(environment ? environment.height + environment.width * environment.height : 4);+ if (environment) {+ environmentTables.set(environment.rows.data.subarray(0, environment.height), 0);+ environmentTables.set(environment.pixels.data.subarray(0, environment.width * environment.height), environment.height);+ }+ const buffers = [+ createStorageBuffer(device, packNodes(scene.bvh).data, 'bvh nodes'),+ createStorageBuffer(device, packTriangles(scene).data, 'triangles'),+ createStorageBuffer(device, packMaterials(scene.materials, atlas).data, 'materials'),+ createStorageBuffer(device, lights.table.data, 'lights'),+ createStorageBuffer(device, atlasWords(atlas), 'texture atlas'),+ createStorageBuffer(device, environment?.colors ?? new Float32Array(4), 'environment colors'),+ createStorageBuffer(device, environmentTables, 'environment tables'),+ ];+ return { buffers, lightCount: lights.count, atlasWidth: atlas.width };+}++/** The scene features this backend does not trace; the caller can fall back to the "gpu" backend. */+export function unsupportedWebGpuFeatures(scene) {+ const unsupported = [];+ if (scene.volume) unsupported.push('volume fog');+ if (sceneUsesSubsurface(scene.materials)) unsupported.push('subsurface scattering');+ return unsupported;+}++/** The words of one uniform block: the 12 vectors of the megakernel parameters, then the tile and shadow slot words. */+function createParameterTemplate(scene, camera, options, uploaded, emitterCount) {+ const words = new ArrayBuffer(PARAMETER_BYTES);+ const floats = new Float32Array(words);+ const integers = new Int32Array(words);+ const unsigned = new Uint32Array(words);+ const { sun } = scene.lights;+ const { environment } = scene;+ floats.set([...camera.eye, 0], 0);+ floats.set([...camera.forward, 0], 4);+ floats.set([...camera.right, 0], 8);+ floats.set([...camera.above, 0], 12);+ floats.set([...(sun?.direction ?? [0, 1, 0]), 0], 16);+ floats.set([...(sun?.color ?? [0, 0, 0]), Math.cos(Math.PI / 360)], 20);+ floats.set([environment?.width ?? 1, environment?.height ?? 1, environment?.intensity ?? 1, environment?.total ?? 1], 24);+ floats.set([environment?.cosine ?? 1, environment?.sine ?? 0, scene.surfaceOffset, scene.farDistance], 28);+ floats.set([camera.halfWidth, camera.halfHeight, options.fireflyClamp, 0], 32);+ integers.set([options.width, options.height, options.bounces, uploaded.lightCount], 36);+ integers.set([emitterCount, sun ? 1 : 0, environment ? 1 : 0, 0], 40);+ unsigned.set([options.seed >>> 0, uploaded.atlasWidth, 0, 0], 44);+ return { unsigned, integers };+}++const SAMPLE_INDEX_WORD = 43;+const TILE_WORD = 48;+const SHADOW_SLOT_WORD = 52;+const SORT_FLAG_WORD = 53;++/** Fills one 256 byte slot per (tile, depth) of a sample; the kernels find their tile and depth in the slot they are bound to. */+function writeParameterSlots(template, sampleIndex, tiles, depthCount, materialCount, shadowSlots, sortByMaterial) {+ const bytes = new Uint8Array(tiles.length * depthCount * PARAMETER_SLOT_BYTES);+ tiles.forEach((tile, tileIndex) => {+ for (let depth = 0; depth < depthCount; depth++) {+ const slot = new Uint32Array(bytes.buffer, (tileIndex * depthCount + depth) * PARAMETER_SLOT_BYTES, PARAMETER_BYTES / 4);+ slot.set(template.unsigned);+ slot[SAMPLE_INDEX_WORD] = sampleIndex;+ slot.set([tile.start, tile.count, depth, materialCount], TILE_WORD);+ slot[SHADOW_SLOT_WORD] = shadowSlots;+ slot[SORT_FLAG_WORD] = sortByMaterial ? 1 : 0;+ }+ });+ return bytes;+}++// Path numbers run over whole 8 by 8 blocks of pixels, so there can be a few more paths than pixels; a tile is a whole number of blocks.+function planTiles(width, height, shadowSlots) {+ const pathCount = Math.ceil(width / 8) * Math.ceil(height / 8) * 64;+ const pathBytes = (PATH_STATE_VECTORS + 3 * shadowSlots) * 16;+ const tilePaths = Math.min(pathCount, Math.floor(Math.min(MAXIMUM_TILE_PATHS, MAXIMUM_STATE_BYTES / pathBytes) / 64) * 64);+ const tiles = [];+ for (let start = 0; start < pathCount; start += tilePaths) tiles.push({ start, count: Math.min(tilePaths, pathCount - start) });+ return { tiles, tilePaths, stateBytes: tilePaths * pathBytes };+}++function averageBuffers(planes, pixelCount, samples) {+ const buffers = {+ color: new Float32Array(pixelCount * 3), albedo: new Float32Array(pixelCount * 3), normal: new Float32Array(pixelCount * 3),+ depth: new Float32Array(pixelCount), variance: new Float32Array(pixelCount), samplesTaken: new Uint16Array(pixelCount).fill(samples),+ };+ const albedoPlane = pixelCount * 4;+ const normalPlane = pixelCount * 8;+ const statisticsPlane = pixelCount * 12;+ for (let pixel = 0; pixel < pixelCount; pixel++) {+ for (let channel = 0; channel < 3; channel++) {+ buffers.color[pixel * 3 + channel] = planes[pixel * 4 + channel] / samples;+ buffers.albedo[pixel * 3 + channel] = planes[albedoPlane + pixel * 4 + channel] / samples;+ buffers.normal[pixel * 3 + channel] = planes[normalPlane + pixel * 4 + channel] / samples;+ }+ buffers.depth[pixel] = planes[pixel * 4 + 3] / samples;+ const mean = planes[statisticsPlane + pixel * 4] / samples;+ buffers.variance[pixel] = Math.max(0, planes[statisticsPlane + pixel * 4 + 1] / samples - mean * mean) / Math.max(samples - 1, 1);+ }+ return buffers;+}++function encodeWavefrontSample(pass, pipelines, bindGroup, tiles, depthCount, materialCount, sortByMaterial) {+ const groupsFor = count => Math.ceil(count / WAVEFRONT_WORKGROUP_SIZE);+ const run = (entryPoint, groups) => {+ pass.setPipeline(pipelines[entryPoint]);+ pass.dispatchWorkgroups(groups);+ };+ tiles.forEach((tile, tileIndex) => {+ const bind = depth => pass.setBindGroup(0, bindGroup, [(tileIndex * depthCount + depth) * PARAMETER_SLOT_BYTES]);+ bind(0);+ run('generatePaths', groupsFor(tile.count));+ for (let depth = 0; depth < depthCount; depth++) {+ bind(depth);+ if (sortByMaterial) run('resetBins', groupsFor(Math.max(materialCount, 1)));+ run('extendPaths', groupsFor(tile.count));+ if (sortByMaterial) {+ run('scanBins', 1);+ run('scatterPaths', groupsFor(tile.count));+ }+ run('shadePaths', groupsFor(tile.count));+ run('shadowPaths', groupsFor(tile.count));+ }+ bind(0);+ run('resolvePaths', groupsFor(tile.count));+ });+}++/**+ * Traces `options.samples` paths for every pixel and resolves with the same buffers as the WebGL2 tracer (color, albedo,+ * normal, depth, variance, samplesTaken) plus a `gpu` note and the `compileSeconds` of the kernel. `options.kernel` picks+ * `wavefront` or `megakernel` (the default is DEFAULT_WEBGPU_KERNEL). `noiseThreshold` is not used: every pixel draws all its+ * samples. `shouldStop` throws when the time limit passes; it runs between samples.+ */+export async function traceOnWebGpu(scene, camera, options, shouldStop) {+ const unsupported = unsupportedWebGpuFeatures(scene);+ if (unsupported.length > 0) throw new Error(`The WebGPU path tracer does not trace ${unsupported.join(' or ')} yet. Use backend "gpu" for this scene.`);+ const kernel = options.kernel ?? DEFAULT_WEBGPU_KERNEL;+ if (!WEBGPU_KERNELS.includes(kernel)) throw new RangeError(`The WebGPU path tracer kernel must be one of ${WEBGPU_KERNELS.join(', ')}.`);+ const current = await getSession();+ const { device } = current;+ const { pipelines, compileSeconds } = await getKernel(current, kernel);+ const { width, height, samples } = options;+ const pixelCount = width * height;+ const planeBytes = pixelCount * 16;+ if (planeBytes * 4 > device.limits.maxStorageBufferBindingSize) {+ throw new RangeError(`A ${width} by ${height} image is too large for this WebGPU adapter. Lower the size or use backend "gpu".`);+ }+ const uploaded = uploadScene(device, scene);+ const emitterCount = (scene.lights.sun ? 1 : 0) + uploaded.lightCount + (scene.environment ? 1 : 0);+ const shadowSlots = Math.max(emitterCount, 1);+ const materialCount = scene.materials.length;+ const depthCount = options.bounces + 1;+ const isWavefront = kernel === 'wavefront';+ const sortByMaterial = options.sortByMaterial ?? DEFAULT_SORT_BY_MATERIAL;+ const { tiles, tilePaths, stateBytes } = planTiles(width, height, shadowSlots);+ const slotCount = isWavefront ? tiles.length * depthCount : 1;+ const accumulation = device.createBuffer({ label: 'accumulation', size: planeBytes * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });+ const parameters = device.createBuffer({ label: 'parameters', size: slotCount * PARAMETER_SLOT_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });+ const stateBuffer = device.createBuffer({ label: 'path state', size: isWavefront ? stateBytes : 16, usage: GPUBufferUsage.STORAGE });+ const queueWords = 1 + 2 * materialCount + tilePaths;+ const binQueue = device.createBuffer({ label: 'material bins', size: isWavefront ? queueWords * 4 : 16, usage: GPUBufferUsage.STORAGE });+ const bindGroup = device.createBindGroup({+ layout: current.bindGroupLayout,+ entries: [+ { binding: 0, resource: { buffer: parameters, size: PARAMETER_BYTES } },+ ...[...uploaded.buffers, accumulation, stateBuffer, binQueue].map((buffer, index) => ({ binding: index + 1, resource: { buffer } })),+ ],+ });+ const template = createParameterTemplate(scene, camera, options, uploaded, emitterCount);+ for (let sample = 0; sample < samples; sample++) {+ const slots = writeParameterSlots(template, sample, isWavefront ? tiles : [{ start: 0, count: pixelCount }], isWavefront ? depthCount : 1, materialCount, shadowSlots, sortByMaterial);+ device.queue.writeBuffer(parameters, 0, slots);+ const encoder = device.createCommandEncoder();+ const pass = encoder.beginComputePass();+ if (isWavefront) {+ encodeWavefrontSample(pass, pipelines, bindGroup, tiles, depthCount, materialCount, sortByMaterial);+ } else {+ pass.setPipeline(pipelines.main);+ pass.setBindGroup(0, bindGroup, [0]);+ pass.dispatchWorkgroups(Math.ceil(width / WORKGROUP_SIZE), Math.ceil(height / WORKGROUP_SIZE));+ }+ pass.end();+ device.queue.submit([encoder.finish()]);+ await device.queue.onSubmittedWorkDone();+ shouldStop();+ }+ const readback = device.createBuffer({ size: planeBytes * 4, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });+ const encoder = device.createCommandEncoder();+ encoder.copyBufferToBuffer(accumulation, 0, readback, 0, planeBytes * 4);+ device.queue.submit([encoder.finish()]);+ await readback.mapAsync(GPUMapMode.READ);+ const buffers = averageBuffers(new Float32Array(readback.getMappedRange()), pixelCount, samples);+ readback.destroy();+ for (const buffer of [...uploaded.buffers, accumulation, parameters, stateBuffer, binQueue]) buffer.destroy();+ return Object.assign(buffers, { gpu: current.gpu, compileSeconds });+}++// The names path-tracer.js looks for in a backend module, the same as path-tracer-gpu.js.+export { traceOnWebGpu as traceOnGpu, webGpuKernelCompileCount as gpuKernelCompileCount };diff --git a/src/path-tracer.js b/src/path-tracer.jsindex ffcd7229..c08a7367 100644--- a/src/path-tracer.js+++ b/src/path-tracer.js@@ -84,6 +84,9 @@ function denoiserNamed(value) {throw new TypeError(`Path tracer denoise must be a boolean or one of ${PATH_TRACER_DENOISERS.join(', ')}.`);}+// "webgpu" is the WGSL compute tracer (src/path-tracer-webgpu.js, loaded only for that backend).+const PATH_TRACER_BACKENDS = ['cpu', 'gpu', 'webgpu'];+export function normalizePathTracerOptions(options = {}) {if (options === null || typeof options !== 'object') throw new TypeError('Path tracer options must be an object.');const result = {@@ -103,7 +106,7 @@ export function normalizePathTracerOptions(options = {}) {};result.denoise = result.denoiser !== 'none';if (!VIEW_TRANSFORM_NAMES.includes(result.viewTransform)) throw new RangeError(`Path tracer viewTransform must be one of ${VIEW_TRANSFORM_NAMES.join(', ')}.`);- if (result.backend !== 'cpu' && result.backend !== 'gpu') throw new TypeError('Path tracer backend must be "cpu" or "gpu".');+ if (!PATH_TRACER_BACKENDS.includes(result.backend)) throw new TypeError('Path tracer backend must be "cpu", "gpu" or "webgpu".');if (result.width * result.height > MAX_TRACE_PIXELS) throw new RangeError(`A path trace takes at most ${MAX_TRACE_PIXELS} pixels.`);if (result.width * result.height * result.samples * (result.bounces + 1) > MAX_TRACE_RAY_WORK) throw new RangeError('This path trace would need too much ray work: lower the size, samples or bounces.');return result;@@ -1044,8 +1047,8 @@ export async function renderPathTracedImage({ parts, environment = {}, camera },let gpuName = null;let gpuCompileSeconds = 0;let gpuKernelCompiles = 0;- if (options.backend === 'gpu') {- const { traceOnGpu, gpuKernelCompileCount } = await import('./path-tracer-gpu.js');+ if (options.backend === 'gpu' || options.backend === 'webgpu') {+ const { traceOnGpu, gpuKernelCompileCount } = await (options.backend === 'webgpu' ? import('./path-tracer-webgpu.js') : import('./path-tracer-gpu.js'));const traced = await traceOnGpu(scene, view, options, shouldStop);gpuName = traced.gpu;gpuCompileSeconds = traced.compileSeconds;diff --git a/tests/path-tracer-webgpu.test.js b/tests/path-tracer-webgpu.test.jsnew file mode 100644index 00000000..678b607c--- /dev/null+++ b/tests/path-tracer-webgpu.test.js@@ -0,0 +1,76 @@+import assert from 'node:assert/strict';+import test from 'node:test';++import { normalizePathTracerOptions, renderPathTracedImage } from '../src/path-tracer.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';+import { MEGAKERNEL_SOURCE, PATH_STATE_VECTORS, WAVEFRONT_SOURCE } from '../src/path-tracer-webgpu-kernel.js';+import { DEFAULT_WEBGPU_KERNEL, isWebGpuTracerAvailable, traceOnWebGpu, unsupportedWebGpuFeatures, WEBGPU_KERNELS } from '../src/path-tracer-webgpu.js';++function quad(offset) {+ return {+ positions: new Float32Array([-1, offset, 1, 1, offset, 1, 1, offset, -1, -1, offset, -1]),+ normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++const camera = { eye: [0, 1, 4], target: [0, 1, 0], fov: 50 };+const parts = [{ name: 'floor', geometry: quad(0), material: { color: [0.5, 0.5, 0.5] } }];++test('the webgpu backend is a valid path tracer option, the default stays cpu', () => {+ assert.equal(normalizePathTracerOptions({ backend: 'webgpu' }).backend, 'webgpu');+ assert.equal(normalizePathTracerOptions({}).backend, 'cpu');+ assert.throws(() => normalizePathTracerOptions({ backend: 'vulkan' }), /"cpu", "gpu" or "webgpu"/);+});++test('without navigator.gpu the webgpu backend throws a clear error naming the fallbacks', async () => {+ assert.equal(isWebGpuTracerAvailable(), false);+ const scene = buildTraceScene(parts, {});+ const options = normalizePathTracerOptions({ width: 16, height: 16, samples: 1, bounces: 1 });+ await assert.rejects(traceOnWebGpu(scene, { eye: [0, 1, 4], forward: [0, 0, -1], right: [1, 0, 0], above: [0, 1, 0], halfWidth: 1, halfHeight: 1 }, options, () => {}), /navigator\.gpu.*"gpu".*"cpu"/);+ await assert.rejects(renderPathTracedImage({ parts, environment: {}, camera }, { width: 16, height: 16, samples: 1, bounces: 1, backend: 'webgpu', denoise: false }), /navigator\.gpu/);+});++test('an unknown kernel name is rejected before any GPU work', async () => {+ const globalNavigator = Object.getOwnPropertyDescriptor(globalThis, 'navigator');+ const calls = [];+ Object.defineProperty(globalThis, 'navigator', { configurable: true, value: { gpu: { requestAdapter: async () => { calls.push('adapter'); return null; } } } });+ try {+ const scene = buildTraceScene(parts, {});+ await assert.rejects(traceOnWebGpu(scene, {}, { kernel: 'nonsense' }, () => {}), /kernel must be one of megakernel, wavefront/);+ await assert.rejects(traceOnWebGpu(scene, {}, { width: 2, height: 2, samples: 1, bounces: 1 }, () => {}), /no WebGPU adapter/);+ } finally {+ if (globalNavigator) Object.defineProperty(globalThis, 'navigator', globalNavigator);+ else delete globalThis.navigator;+ }+ assert.deepEqual(calls, ['adapter']);+});++test('fog and subsurface scenes are named as unsupported so callers can fall back to gpu', async () => {+ assert.deepEqual(unsupportedWebGpuFeatures(buildTraceScene(parts, {})), []);+ const fogScene = buildTraceScene(parts, { volumeFog: { minimum: [-30, 1, -30], maximum: [30, 2, 30], density: 0.5 } });+ const subsurfaceParts = [{ ...parts[0], material: { color: [0.7, 0.4, 0.3], subsurface: { weight: 1, radius: [1, 0.2, 0.1], scale: 0.05 } } }];+ const subsurfaceScene = buildTraceScene(subsurfaceParts, {});+ assert.deepEqual(unsupportedWebGpuFeatures(fogScene), ['volume fog']);+ assert.deepEqual(unsupportedWebGpuFeatures(subsurfaceScene), ['subsurface scattering']);+ await assert.rejects(traceOnWebGpu(fogScene, {}, {}, () => {}), /does not trace volume fog yet.*"gpu"/);+ await assert.rejects(traceOnWebGpu(subsurfaceScene, {}, {}, () => {}), /does not trace subsurface scattering yet/);+});++test('both kernels share the scene bindings and the wavefront adds its path state', () => {+ assert.deepEqual(WEBGPU_KERNELS, ['megakernel', 'wavefront']);+ assert.equal(DEFAULT_WEBGPU_KERNEL, 'megakernel');+ for (let binding = 0; binding <= 8; binding++) {+ assert.match(MEGAKERNEL_SOURCE, new RegExp(`@binding\\(${binding}\\)`));+ assert.match(WAVEFRONT_SOURCE, new RegExp(`@binding\\(${binding}\\)`));+ }+ assert.doesNotMatch(MEGAKERNEL_SOURCE, /@binding\(9\)/);+ assert.match(WAVEFRONT_SOURCE, /@binding\(9\)[^\n]*pathState/);+ assert.match(WAVEFRONT_SOURCE, /@binding\(10\)[^\n]*binQueue/);+ assert.match(MEGAKERNEL_SOURCE, /fn main\(/);+ for (const entryPoint of ['generatePaths', 'resetBins', 'extendPaths', 'scanBins', 'scatterPaths', 'shadePaths', 'shadowPaths', 'resolvePaths']) {+ assert.match(WAVEFRONT_SOURCE, new RegExp(`fn ${entryPoint}\\(`));+ }+ assert.match(WAVEFRONT_SOURCE, new RegExp(`PATH_STATE_VECTORS: u32 = ${PATH_STATE_VECTORS}u`));+});