Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.mjs
index 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.sh
index 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 -u
OUT="${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; do
bash ~/.agents/tools/gpu-lock.sh node bench/webgpu-tracer/run.mjs "$OUT" "$VARIANT" --label "run$RUN" 2>&1 | cut -c1-1500
done
done
diff --git a/bench/webgpu-tracer/harness.js b/bench/webgpu-tracer/harness.js
index 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.mjs
index 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.mjs
index 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.mjs
import { 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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 20
diff --git a/bench/webgpu-tracer/kernel.js b/src/path-tracer-webgpu-kernel.js
similarity index 71%
rename from bench/webgpu-tracer/kernel.js
rename to src/path-tracer-webgpu-kernel.js
index 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.js
new file mode 100644
index 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.js
index 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.js
new file mode 100644
index 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`));
+});