3D engine that AI agents drive
Run the real-time path tracer on WebGPU (issue #624)
Nguyen Xuan An33c031dade60
diff --git a/bench/realtime-tracer/page.js b/bench/realtime-tracer/page.jsindex 0603d148..f8dc2acb 100644--- a/bench/realtime-tracer/page.js+++ b/bench/realtime-tracer/page.js@@ -34,25 +34,26 @@ window.measureRealtimeFrames = async function measureRealtimeFrames(source, opticonst times = [];for (let frame = 0; frame < frames + warmup; frame++) {const started = performance.now();- tracer.frame(orbitCamera(scene.camera, frame * degreesPerFrame), { wait: true });+ const result = tracer.frame(orbitCamera(scene.camera, frame * degreesPerFrame), { wait: true });+ await result.done;if (frame >= warmup) times.push(performance.now() - started);}- const result = { gpu: tracer.gpu, compileSeconds: tracer.compileSeconds, frames, degreesPerFrame, medianMilliseconds: median(times), minimumMilliseconds: Math.min(...times), maximumMilliseconds: Math.max(...times) };+ const summary = { gpu: tracer.gpu, backend: tracer.backend, fallbackReason: tracer.fallbackReason, compileSeconds: tracer.compileSeconds, frames, degreesPerFrame, medianMilliseconds: median(times), minimumMilliseconds: Math.min(...times), maximumMilliseconds: Math.max(...times) };tracer.dispose();- return result;+ return summary;};// A resting camera for `seconds`; returns the last frame and how many frames fitted.window.renderRestingFrame = async function renderRestingFrame(source, options, seconds = 1) {const { scene, tracer } = await openTracer(source, options);- tracer.frame(scene.camera, { wait: true });+ await tracer.frame(scene.camera, { wait: true }).done;const started = performance.now();let frames = 1;while (performance.now() - started < seconds * 1000) {- tracer.frame(scene.camera, { wait: true });+ await tracer.frame(scene.camera, { wait: true }).done;frames++;}- const image = toBase64Png(tracer.readFrame());+ const image = toBase64Png(await tracer.readFrame());tracer.dispose();return { image, frames, elapsedSeconds: (performance.now() - started) / 1000 };};@@ -60,11 +61,11 @@ window.renderRestingFrame = async function renderRestingFrame(source, options, s// Frames of a camera move: `warmupFrames` at rest, then the orbit, saving every `saveEvery` frames of the move.window.renderCameraMove = async function renderCameraMove(source, options, { warmupFrames = 30, moveFrames = 24, degreesPerFrame = 2, saveEvery = 3 } = {}) {const { scene, tracer } = await openTracer(source, options);- for (let frame = 0; frame < warmupFrames; frame++) tracer.frame(scene.camera, { wait: true });+ for (let frame = 0; frame < warmupFrames; frame++) await tracer.frame(scene.camera, { wait: true }).done;const images = [];for (let frame = 1; frame <= moveFrames; frame++) {- tracer.frame(orbitCamera(scene.camera, frame * degreesPerFrame), { wait: true });- if (frame % saveEvery === 0) images.push(toBase64Png(tracer.readFrame()));+ await tracer.frame(orbitCamera(scene.camera, frame * degreesPerFrame), { wait: true }).done;+ if (frame % saveEvery === 0) images.push(toBase64Png(await tracer.readFrame()));}tracer.dispose();return images;diff --git a/bench/realtime-tracer/run.mjs b/bench/realtime-tracer/run.mjsindex 839faab1..bd9b2b53 100644--- a/bench/realtime-tracer/run.mjs+++ b/bench/realtime-tracer/run.mjs@@ -1,6 +1,7 @@// The real-time path tracer (issue #624): frame time with an orbiting camera, the resting frame after one second, a camera move.// [GPU_LOCK="bash <path to gpu-lock.sh>"] ${GPU_LOCK} node bench/realtime-tracer/run.mjs <output directory> <scene id or recipe.json>,...-// [--mode time|rest|move|all] [--frames 200] [--width 1920] [--height 1080] [--bounces 2] [--repetitions 3]+// [--mode time|rest|move|all] [--frames 200] [--width 1920] [--height 1080] [--bounces 2] [--repetitions 3] [--backend gpu|webgpu]+// (use one output directory per backend: the picture files carry no backend name)// Files: <scene>@realtime-rest.png, <scene>@move-<n>.png and timings.json. bench/realtime-tracer/score.py scores the// resting frames against Cycles, and bench/realtime-tracer/sheet.py puts a camera move on one contact sheet.import { mkdir, readFile, writeFile } from 'node:fs/promises';@@ -17,7 +18,7 @@ const valueAfter = (flag, fallback) => (argumentsGiven.includes(flag) ? argumentconst mode = valueAfter('--mode', 'all');const frames = Number(valueAfter('--frames', 200));const repetitions = Number(valueAfter('--repetitions', 3));-const options = { width: Number(valueAfter('--width', 1920)), height: Number(valueAfter('--height', 1080)), bounces: Number(valueAfter('--bounces', 2)), resolutionDivisor: Number(valueAfter('--divisor', 2)) };+const options = { width: Number(valueAfter('--width', 1920)), height: Number(valueAfter('--height', 1080)), bounces: Number(valueAfter('--bounces', 2)), resolutionDivisor: Number(valueAfter('--divisor', 2)), backend: valueAfter('--backend', 'gpu') };const recipeName = id => id.replace(/^.*[\/]/, '').replace(/\.recipe\.json$|\.json$/, '');setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);@@ -25,7 +26,7 @@ await mkdir(outputDirectory, { recursive: true });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'] });+const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding', '--enable-unsafe-webgpu', '--enable-features=Vulkan,WebGPU', '--use-angle=d3d11'] });const timings = {};try {const page = await browser.newPage({ viewport: { width: 960, height: 540 } });@@ -44,7 +45,7 @@ try {const label = degreesPerFrame ? 'orbit' : 'rest';const runs = [];for (let repetition = 0; repetition < repetitions; repetition++) runs.push(await page.evaluate(([scene, tracerOptions, count, step]) => window.measureRealtimeFrames(scene, tracerOptions, count, step), [source, options, frames, degreesPerFrame]));- timings[`${name}:${label}`] = { medians: runs.map(run => Number(run.medianMilliseconds.toFixed(2))), compileSeconds: runs.map(run => Number(run.compileSeconds.toFixed(2))), gpu: runs[0].gpu };+ timings[`${name}:${label}`] = { medians: runs.map(run => Number(run.medianMilliseconds.toFixed(2))), compileSeconds: runs.map(run => Number(run.compileSeconds.toFixed(2))), gpu: runs[0].gpu, backend: runs[0].backend, fallbackReason: runs[0].fallbackReason };console.log(name, label, JSON.stringify(timings[`${name}:${label}`]));}}diff --git a/changes/624-webgpu.md b/changes/624-webgpu.mdnew file mode 100644index 00000000..1cd9e527--- /dev/null+++ b/changes/624-webgpu.md@@ -0,0 +1 @@+- `createRealtimeTracer(scene, { backend: 'webgpu' })` runs the real-time path tracer (#624) as WebGPU compute: the WebGPU megakernel with the radiance cache lookup and record built in, a cache update with atomic fixed point sums, and the temporal denoiser, a-trous filter and upsample as compute passes in one command buffer, with the picture copied to `canvas`. On the RTX 3060 the demo room at its own camera takes about 20 ms a frame at 1920 by 1080 (traced at 960 by 540) against 36 ms on WebGL2, and the kernel compiles in about 0.5 s against 11 s. WebGL2 stays the default and the fallback: without WebGPU the tracer's `backend` is `"gpu"` and `fallbackReason` says why. On the WebGPU backend `frame(camera, { wait: true }).done` and `readFrame()` are promises. The denoiser also rejects history where the material at the first hit differs (WebGPU backend only)diff --git a/changes/624-webgpu.size.md b/changes/624-webgpu.size.mdnew file mode 100644index 00000000..9ebe4a18--- /dev/null+++ b/changes/624-webgpu.size.md@@ -0,0 +1 @@+- entry:path-tracer-realtime+lazy: the WebGPU backend of the real-time tracer (WGSL kernel pieces, cache update and denoiser passes, about 9 KB gzip) loads only for `backend: 'webgpu'`; the demo room takes 20 ms a frame on it against 36 ms on WebGL2, and the kernel compiles in under a second.diff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex 1990ce07..69dfaa91 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -160,6 +160,10 @@ Light choice at equal samples (16 and 64) on the 16 path tracer scenes: 12 scene- **Radiance cache** (`src/path-tracer-radiance-cache.js`, SHaRC style). A cell is the quantized position (cells double in size each time the distance from the eye doubles past 64 cells) and the quantized normal of a surface point, hashed into 2^20 slots with no collision check (about 0.4% of 7,500 test cells collided). The last hit of a path reads its cell instead of tracing on; the hit before it writes what the rest of the path brought back, and a point pass adds the records into the cells with additive blending (WebGL2 has no atomics), as a running average of up to 128 records. The cache reads as diffuse. It needs the scene to rest: a new scene empties it.- **Temporal denoiser and upsampler** (`src/path-tracer-temporal-denoise.js`, `src/path-tracer-reprojection.js`, SVGF style). The light is divided by the albedo, reprojected history (bilinear, rejected where distance or normal differ) is blended in over up to 48 frames, the variance comes from the history of the luminance (from the 3 by 3 neighbours while the history is short), four a-trous passes filter with plane distance, normal and variance guided luminance weights, and a joint bilateral upsample to the output size multiplies the albedo history back in. A sample far above its neighbours is clamped while the history is short.-What it is not (the issue asked for more): primary hits are traced, not taken from a raster G-buffer (the tracer's first hit already writes albedo, normal and distance; sharing the rasterizer's depth pass would save a ray per pixel and is left open), and motion vectors come from the camera's move, so a moving or animated part would ghost; the scene is static. Material ids are not used for history rejection. The upsample is a joint bilinear filter over half-size data with jittered rays averaged over time, not a full-size accumulation.+What it is not (the issue asked for more): primary hits are traced, not taken from a raster G-buffer (the tracer's first hit already writes albedo, normal and distance; sharing the rasterizer's depth pass would save a ray per pixel and is left open), and motion vectors come from the camera's move, so a moving or animated part would ghost; the scene is static. Material ids are not used for history rejection on the WebGL2 backend (the WebGPU backend uses them, below). The upsample is a joint bilinear filter over half-size data with jittered rays averaged over time, not a full-size accumulation.++**WebGPU backend** (`createRealtimeTracer(scene, { backend: 'webgpu' })`, `src/path-tracer-realtime-webgpu.js`, `-kernel.js` and `-passes.js`). The same frame as WGSL compute in one command buffer. The megakernel of `src/path-tracer-webgpu.js` gets the cache pieces through `buildMegakernelSource({ realtime: true })`: the last hit reads the cache table, the hit before it writes a record, the first hit also picks one light by importance, and the entry point writes radiance with distance, albedo, normal and the material of the first hit to a frame buffer. The cache update is two dispatches: records are summed per cell with atomic adds on fixed point numbers (1/1024, a record clamped at 32), then every cell folds its sum into its running average (up to 128 records) and empties the sum. The denoiser (accumulate, four a-trous steps, upsample with tone mapping) is the same maths as the WebGL2 passes, with one addition: history is rejected where the material at the first hit differs, which stops the light of one surface from bleeding into a neighbour it passes behind. The result is packed into a buffer and copied to `canvas` (the tracer's own, or `options.canvas`). Without `navigator.gpu`, an adapter or 10 storage buffers per stage, `backend: 'webgpu'` falls back to WebGL2 and the tracer reports `backend` and `fallbackReason`. Differences to the WebGL2 object: `frame(camera, { wait: true })` returns `{ frame, done }` (await `done` to time a frame), `readFrame()` and `update()` return promises, and it does not share the WebGL2 context, so it can run beside a WebGL2 render. `bench/realtime-tracer/run.mjs --backend webgpu` measures it (one output directory per backend).Measured on the RTX 3060 with `bench/realtime-tracer/run.mjs` (1920 by 1080 output, 960 by 540 traced, median of 200 frames, three runs of a fresh tracer, the card held by the job): `lit-interior` 20.0 to 20.1 ms orbiting and 20.1 to 20.5 ms resting; the demo room (`tests/fixtures/demo-room.recipe.json`) 20.2 ms orbiting 0.5 degrees per frame (it turns away from the heavy view) and 36.2 to 36.3 ms at the scene's own camera, 27.6 frames per second, 3 ms over the 33 ms target. With `bounces: 1` the demo room at its own camera took 24.5 ms (one run of 100 frames). On a shared card the same runs took up to 62 ms, so time it behind the GPU lock. FLIP of the frame after one second of rest (51 frames) against Cycles, `lit-interior`: 0.0637, against 0.0769 for the 64 sample still (the demo room has no Cycles render). `bench/realtime-tracer/score.py` scores it and `sheet.py` makes the contact sheet of a camera move: no trails behind the sphere, box or sign in either scene, but a fast move leaves visible speckle in dark parts of the demo room, where one sample per pixel and a cold cache are not enough.++WebGPU backend, same setup (2026-11-09, `--backend webgpu`, median of 200 frames, three runs of a fresh tracer, card held through the GPU lock, awaiting `onSubmittedWorkDone` after every frame): `lit-interior` 10.6 to 11.0 ms orbiting and 12.1 to 12.2 ms resting (WebGL2 in the same session: 20.1 to 20.3 ms and 20.1 to 20.3 ms); the demo room 12.0 to 12.5 ms orbiting and 19.6 to 19.9 ms at the scene's own camera (WebGL2: 20.4 to 31.9 ms and 36.3 ms), so the 33 ms target holds with 13 ms to spare, at 1920 by 1080 output and 960 by 540 traced. The kernel compiles in 0.46 s against 10.8 s. FLIP of the frame after one second of rest against Cycles, `lit-interior`: 0.0504 (84 frames) against 0.0637 on WebGL2 (51 frames), the gain mostly from the frames that fit in the second. The contact sheet of a camera move on the demo room (8 frames, 2 degrees each) shows no trails; speckle in the dark floor is as on WebGL2. Left open: primary hits from a raster G-buffer, per-object motion vectors, and full-size accumulation instead of the joint bilinear upsample.diff --git a/src/path-tracer-realtime-options.js b/src/path-tracer-realtime-options.jsnew file mode 100644index 00000000..6fbbc301--- /dev/null+++ b/src/path-tracer-realtime-options.js@@ -0,0 +1,44 @@+import { normalizePathTracerOptions } from './path-tracer.js';++// What both backends of the real-time tracer (path-tracer-realtime.js, path-tracer-realtime-webgpu.js) read from the options.++export const REALTIME_BACKENDS = ['gpu', 'webgpu'];+const DEFAULT_BOUNCES = 2;+const DEFAULT_RESOLUTION_DIVISOR = 2;+const CACHE_CELLS_ACROSS_SCENE = 200;+const CACHE_LEVEL_CELLS = 64;+const SCENE_EXTENT_SCALE = 1e4;++/** The output and tracing sizes and the normalized tracer options of `createRealtimeTracer`'s raw options. */+export function resolveRealtimeOptions(rawOptions) {+ const resolutionDivisor = rawOptions.resolutionDivisor ?? DEFAULT_RESOLUTION_DIVISOR;+ const outputWidth = rawOptions.width ?? 960;+ const outputHeight = rawOptions.height ?? 540;+ const traceWidth = Math.max(1, Math.ceil(outputWidth / resolutionDivisor));+ const traceHeight = Math.max(1, Math.ceil(outputHeight / resolutionDivisor));+ const backend = rawOptions.backend ?? 'gpu';+ if (!REALTIME_BACKENDS.includes(backend)) throw new RangeError(`The real-time path tracer backend must be one of ${REALTIME_BACKENDS.join(', ')}.`);+ const options = normalizePathTracerOptions({+ seed: rawOptions.seed, lightSelection: rawOptions.lightSelection ?? 'importance', bounces: rawOptions.bounces ?? DEFAULT_BOUNCES,+ width: traceWidth, height: traceHeight, samples: 1, backend: 'gpu', denoise: false,+ });+ options.radianceCache = true;+ return {+ backend, outputWidth, outputHeight, traceWidth, traceHeight, options,+ historyLimit: rawOptions.historyLimit, filterIterations: rawOptions.filterIterations, cacheCellSize: rawOptions.cacheCellSize,+ };+}++/** The cache cell size and the distance at which cells start to grow, for a scene of `farDistance`. */+export function cacheCellSizes(traceScene, cacheCellSize) {+ const extent = traceScene.farDistance / SCENE_EXTENT_SCALE;+ const cellSize = cacheCellSize ?? extent / CACHE_CELLS_ACROSS_SCENE;+ return { cellSize, levelDistance: cellSize * CACHE_LEVEL_CELLS };+}++/** True when two cameras (as `createCamera` returns them) look the same way. */+export function viewsMatch(first, second) {+ if (!first || !second) return false;+ const keys = ['eye', 'forward', 'right', 'above'];+ return keys.every(key => first[key].every((value, axis) => value === second[key][axis])) && first.halfWidth === second.halfWidth && first.halfHeight === second.halfHeight;+}diff --git a/src/path-tracer-realtime-webgpu-kernel.js b/src/path-tracer-realtime-webgpu-kernel.jsnew file mode 100644index 00000000..8f1aad15--- /dev/null+++ b/src/path-tracer-realtime-webgpu-kernel.js@@ -0,0 +1,164 @@+import { CACHE_SLOT_COUNT, MAXIMUM_LEVEL, NORMAL_AXIS_THRESHOLD } from './path-tracer-radiance-cache.js';++// The WGSL pieces that turn the WebGPU megakernel into the real-time kernel (issue #624), the counterpart of the cache+// strings in path-tracer-radiance-cache.js for the WebGL2 kernel. buildMegakernelSource({ realtime: true }) places them:+// - the cache table and the record buffer (bindings 9 and 10), the cell hash (the same value as `cacheSlot`) and the lookup;+// - light selection that draws one emitter at every hit (the denoiser averages the draws over frames), by importance;+// - the last hit of a path ending in a cache lookup, and the hit before it remembering its cell for a record;+// - an entry point that writes the first hit's radiance, albedo, normal and material to the frame buffer and the record.+// The cell size and the level distance travel in the tile words of the parameter block, as float bits.++const REALTIME_DECLARATIONS = /* wgsl */ `+@group(0) @binding(9) var<storage, read_write> cacheTable: array<vec4<f32>>;+@group(0) @binding(10) var<storage, read_write> cacheRecords: array<vec4<f32>>;+var<private> recordedSlot: f32 = 0.0;+var<private> recordedRadianceBefore: vec3<f32> = vec3<f32>(0.0);+var<private> recordedThroughput: vec3<f32> = vec3<f32>(1.0);+var<private> firstHitMaterial: f32 = 0.0;++fn normalAxisCode(component: f32) -> u32 {+ if (component > ${NORMAL_AXIS_THRESHOLD}) { return 2u; }+ if (component < -${NORMAL_AXIS_THRESHOLD}) { return 0u; }+ return 1u;+}++fn cacheHash(point: vec3<f32>, normal: vec3<f32>) -> u32 {+ let cellSize = bitcast<f32>(params.tileAndDepth.x);+ let levelDistance = bitcast<f32>(params.tileAndDepth.y);+ let level = clamp(floor(log2(max(length(point - params.eye.xyz) / levelDistance, 1.0))), 0.0, ${MAXIMUM_LEVEL}.0);+ let cell = vec3<i32>(floor(point / (cellSize * exp2(level))));+ let normalCode = normalAxisCode(normal.x) + 3u * normalAxisCode(normal.y) + 9u * normalAxisCode(normal.z);+ var hash = (bitcast<u32>(cell.x) * 73856093u) ^ (bitcast<u32>(cell.y) * 19349663u) ^ (bitcast<u32>(cell.z) * 83492791u);+ hash ^= (normalCode + 1u) * 0x9e3779b1u;+ hash ^= u32(level) * 0x85ebca6bu;+ hash ^= hash >> 16u;+ hash *= 0x7feb352du;+ hash ^= hash >> 15u;+ hash *= 0x846ca68bu;+ hash ^= hash >> 16u;+ return hash & ${CACHE_SLOT_COUNT - 1}u;+}++// The mean radiance that arrives at the cell of a surface point; black while the cell has no record yet.+fn cacheLookup(point: vec3<f32>, normal: vec3<f32>) -> vec3<f32> {+ let cell = cacheTable[cacheHash(point, normal)];+ return select(vec3<f32>(0.0), cell.xyz, cell.w >= 1.0);+}++// A cheap estimate of the light one local light brings to the hit point, as lightImportance in the WebGL2 kernel.+fn lightImportance(index: i32, normal: vec3<f32>) -> f32 {+ let base = index * LIGHT_TEXELS;+ let positionType = lights[base];+ let colorBit = lights[base + 1];+ let directionRadius = lights[base + 2];+ let acrossCone = lights[base + 3];+ let intensityRange = lights[base + 5];+ let delta = positionType.xyz - hitPoint;+ let distanceSquared = max(dot(delta, delta), 1e-8);+ let toLight = delta * inverseSqrt(distanceSquared);+ let cosine = 0.1 + max(dot(normal, toLight), 0.0);+ let power = luminance(colorBit.rgb) * intensityRange.x;+ let lightType = i32(positionType.w);+ if (lightType == 2) { return power * max(-dot(directionRadius.xyz, toLight), 0.0) * cosine / distanceSquared; }+ var coneFactor = 1.0;+ if (lightType == 1 && -dot(directionRadius.xyz, toLight) - acrossCone.w <= 0.0) { coneFactor = 0.0; }+ return power * coneFactor * cosine * pointLightFalloff(distanceSquared, intensityRange.y, directionRadius.w);+}++// Draws one emitter: the sun and the sky keep a uniform share, the local lights split theirs by importance mixed with a uniform part.+fn chooseEmitterByImportance(normal: vec3<f32>) -> i32 {+ let emitterCount = params.emittersFlagsSample.x;+ let lightCount = params.sizeBouncesLights.w;+ let uniformShare = 1.0 / f32(emitterCount);+ let draw = nextRandom();+ let firstLightEmitter = select(0, 1, params.emittersFlagsSample.y != 0);+ var total = 0.0;+ if (lightCount > 1) {+ for (var index = 0; index < lightCount; index++) { total += lightImportance(index, normal); }+ }+ selectionProbability = uniformShare;+ if (!(total > 0.0)) { return min(i32(floor(draw * f32(emitterCount))), emitterCount - 1); }+ let lightsShare = f32(lightCount) * uniformShare;+ var cumulative = 0.0;+ for (var emitter = 0; emitter < emitterCount; emitter++) {+ let index = emitter - firstLightEmitter;+ var share = uniformShare;+ if (index >= 0 && index < lightCount) { share = lightsShare * (0.9 * lightImportance(index, normal) / total + 0.1 / f32(lightCount)); }+ cumulative += share;+ selectionProbability = share;+ if (draw < cumulative) { return emitter; }+ }+ return emitterCount - 1;+}+`;++// The first hit lights from one emitter too, so a frame costs one shadow ray there.+const REALTIME_ADD_LIGHTS = /* wgsl */ `+fn addLights(depth: i32, normal: vec3<f32>) {+ let emitterCount = params.emittersFlagsSample.x;+ if (emitterCount <= 1) {+ selectionProbability = 1.0;+ for (var emitter = 0; emitter < emitterCount; emitter++) {+ sampleEmitter(depth, normal, emitter);+ flushShadowRay();+ }+ return;+ }+ sampleEmitter(depth, normal, chooseEmitterByImportance(normal));+ flushShadowRay();+}+`;++const REALTIME_FIRST_HIT = 'if (!featuresRecorded) { firstHitMaterial = f32(hitMaterialIndex) + 1.0; }';++// The last hit of a path adds the cell's radiance, times what the path carries and the surface colour (a diffuse reading).+const REALTIME_TERMINAL = /* wgsl */ `+ if (depth == bounces && !inFog && !isGlass) {+ addRadiance(depth, throughput * hitColor * cacheLookup(hitPoint, normal));+ break;+ }`;++// The hit before it, if the surface scatters diffusely, remembers its cell, the light so far and the path's weight.+const REALTIME_RECORD = /* wgsl */ `+ if (depth == max(bounces - 1, 0) && !isMirror) {+ recordedSlot = f32(cacheHash(hitPoint, normal)) + 1.0;+ recordedRadianceBefore = radiance;+ recordedThroughput = throughput;+ }`;++// One invocation per pixel. The frame buffer holds three planes of pixelCount vec4: radiance and depth, albedo, normal and material.+const REALTIME_MAIN = /* wgsl */ `+@compute @workgroup_size(8, 8, 1)+fn traceRealtime(@builtin(global_invocation_id) id: vec3<u32>) {+ let width = params.sizeBouncesLights.x;+ let height = params.sizeBouncesLights.y;+ if (i32(id.x) >= width || i32(id.y) >= height) { return; }+ let pixel = id.y * u32(width) + id.x;+ let sampleIndex = u32(params.emittersFlagsSample.w);+ let seed = params.seedAndAtlas.x;+ if (params.emittersFlagsSample.y != 0) { sunFrame = buildFrame(params.sunDirection.xyz); }+ let jitterX = hashJitter(pixel, sampleIndex, seed, 1u);+ let jitterY = hashJitter(pixel, sampleIndex, seed, 2u);+ let screenX = ((f32(id.x) + jitterX) / f32(width) * 2.0 - 1.0) * params.cameraAndClamp.x;+ let screenY = (1.0 - (f32(id.y) + jitterY) / f32(height) * 2.0) * params.cameraAndClamp.y;+ let rayDirection = normalize(params.forward.xyz + params.right.xyz * screenX + params.above.xyz * screenY);+ tracePath(params.eye.xyz, rayDirection, pixel, sampleIndex);+ if (!(all(radiance >= vec3<f32>(0.0)) && all(radiance < vec3<f32>(1e30)))) { radiance = vec3<f32>(0.0); }+ if (!(featureDepth >= 0.0 && featureDepth < 1e30)) { featureDepth = 0.0; }+ if (!(all(featureNormal >= vec3<f32>(-1.5)) && all(featureNormal < vec3<f32>(1.5)))) { featureNormal = vec3<f32>(0.0, 0.0, 1.0); }+ if (!(all(featureAlbedo >= vec3<f32>(0.0)) && all(featureAlbedo < vec3<f32>(1e30)))) { featureAlbedo = vec3<f32>(1.0); }+ let pixelCount = u32(width * height);+ accumulation[pixel] = vec4<f32>(radiance, featureDepth);+ accumulation[pixelCount + pixel] = vec4<f32>(featureAlbedo, 0.0);+ accumulation[2u * pixelCount + pixel] = vec4<f32>(featureNormal, firstHitMaterial);+ // The record: the light the rest of the path brought, per unit of the weight at that hit (the incoming radiance).+ let recordedTail = clamp((radiance - recordedRadianceBefore) / max(recordedThroughput, vec3<f32>(0.05)), vec3<f32>(0.0), vec3<f32>(params.cameraAndClamp.z));+ cacheRecords[pixel] = select(vec4<f32>(0.0), vec4<f32>(recordedTail, recordedSlot), recordedSlot > 0.0);+}+`;++/** The pieces as `buildMegakernelSource({ realtime })` takes them. */+export const REALTIME_KERNEL_PIECES = {+ declarations: REALTIME_DECLARATIONS, addLights: REALTIME_ADD_LIGHTS, firstHit: REALTIME_FIRST_HIT,+ terminal: REALTIME_TERMINAL, record: REALTIME_RECORD, main: REALTIME_MAIN,+};diff --git a/src/path-tracer-realtime-webgpu-passes.js b/src/path-tracer-realtime-webgpu-passes.jsnew file mode 100644index 00000000..d12f672d--- /dev/null+++ b/src/path-tracer-realtime-webgpu-passes.js@@ -0,0 +1,459 @@+import { CACHE_HISTORY_LIMIT, CACHE_SLOT_COUNT } from './path-tracer-radiance-cache.js';+import { DEFAULT_FILTER_ITERATIONS, DEFAULT_HISTORY_LIMIT } from './path-tracer-temporal-denoise.js';+import { DEPTH_TOLERANCE, NORMAL_AGREEMENT } from './path-tracer-reprojection.js';++// The compute passes of the WebGPU real-time tracer (issue #624): the radiance cache update and the temporal denoiser,+// the WGSL form of path-tracer-radiance-cache.js and path-tracer-temporal-denoise.js (read those for the reasoning). Two+// differences from the WebGL2 passes:+// - the cache sums the records with atomic adds on fixed point numbers (WebGL2 has no atomics, so it blends points);+// - history is also rejected where the material at the first hit differs (the fourth value of the normal plane).+// Every image is a storage buffer of vec4 in row order. The traced frame holds three planes: radiance and distance,+// albedo, normal and material. History holds three: colour and length, moments and variance, albedo.++const FIXED_POINT_SCALE = 1024;+const RECORD_LIMIT = 32;+const MINIMUM_ALBEDO = 0.02;+const SPATIAL_VARIANCE_HISTORY = 4;+const FIREFLY_DEVIATIONS = 2.5;+const SHORT_HISTORY_LENGTH = 8;+const CACHE_WORKGROUP_SIZE = 256;+const CACHE_PARAMETER_BYTES = 16;+const DENOISE_PARAMETER_BYTES = 12 * 16;++const CACHE_SOURCE = /* wgsl */ `+@group(0) @binding(0) var<storage, read> records: array<vec4<f32>>;+@group(0) @binding(1) var<storage, read_write> sums: array<atomic<u32>>;+@group(0) @binding(2) var<storage, read_write> cacheTable: array<vec4<f32>>;+@group(0) @binding(3) var<uniform> recordCount: vec4<u32>;++// A record is the light the rest of a path brought (rgb) and the cell it belongs to (a, one more than the slot; 0 for none).+@compute @workgroup_size(${CACHE_WORKGROUP_SIZE})+fn scatterRecords(@builtin(global_invocation_id) id: vec3<u32>, @builtin(num_workgroups) groups: vec3<u32>) {+ let index = id.y * groups.x * ${CACHE_WORKGROUP_SIZE}u + id.x;+ if (index >= recordCount.x) { return; }+ let record = records[index];+ if (record.w < 0.5) { return; }+ let slot = u32(record.w) - 1u;+ let fixedValues = vec3<u32>(min(record.xyz, vec3<f32>(${RECORD_LIMIT}.0)) * ${FIXED_POINT_SCALE}.0);+ atomicAdd(&sums[slot * 4u], fixedValues.x);+ atomicAdd(&sums[slot * 4u + 1u], fixedValues.y);+ atomicAdd(&sums[slot * 4u + 2u], fixedValues.z);+ atomicAdd(&sums[slot * 4u + 3u], 1u);+}++// Folds the records of the frame into the running average of each cell, and empties the sums for the next frame.+@compute @workgroup_size(${CACHE_WORKGROUP_SIZE})+fn resolveCells(@builtin(global_invocation_id) id: vec3<u32>, @builtin(num_workgroups) groups: vec3<u32>) {+ let slot = id.y * groups.x * ${CACHE_WORKGROUP_SIZE}u + id.x;+ if (slot >= ${CACHE_SLOT_COUNT}u) { return; }+ let count = f32(atomicLoad(&sums[slot * 4u + 3u]));+ if (count < 0.5) { return; }+ let sum = vec3<f32>(f32(atomicLoad(&sums[slot * 4u])), f32(atomicLoad(&sums[slot * 4u + 1u])), f32(atomicLoad(&sums[slot * 4u + 2u])));+ for (var word = 0u; word < 4u; word++) { atomicStore(&sums[slot * 4u + word], 0u); }+ let previous = cacheTable[slot];+ let weight = count / (min(previous.w, ${CACHE_HISTORY_LIMIT}.0) + count);+ cacheTable[slot] = vec4<f32>(mix(previous.xyz, sum / ${FIXED_POINT_SCALE}.0 / count, weight), previous.w + count);+}+`;++const DENOISE_COMMON = /* wgsl */ `+struct DenoiseParams {+ eye: vec4<f32>,+ forward: vec4<f32>,+ right: vec4<f32>,+ above: vec4<f32>,+ previousEye: vec4<f32>,+ previousForward: vec4<f32>,+ previousRight: vec4<f32>,+ previousAbove: vec4<f32>,+ halves: vec4<f32>,+ sizes: vec4<i32>,+ settings: vec4<f32>,+ outputLayout: vec4<u32>,+}+// sizes: trace width and height, output width and height. settings: far distance, history limit, reset flag, a-trous step.+// outputLayout: words per output row, 1 when the canvas format is bgra.+@group(0) @binding(0) var<uniform> params: DenoiseParams;++const MINIMUM_ALBEDO: f32 = ${MINIMUM_ALBEDO};+const DEPTH_TOLERANCE: f32 = ${DEPTH_TOLERANCE};+const NORMAL_AGREEMENT: f32 = ${NORMAL_AGREEMENT};++fn luminanceOf(color: vec3<f32>) -> f32 {+ return dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));+}++fn distanceOf(radianceAndDistance: vec4<f32>) -> f32 {+ return select(params.settings.x, radianceAndDistance.w, radianceAndDistance.w > 0.0);+}++fn pixelRayDirection(pixelPosition: vec2<f32>, size: vec2<f32>) -> vec3<f32> {+ let screenX = (pixelPosition.x / size.x * 2.0 - 1.0) * params.halves.x;+ let screenY = (1.0 - pixelPosition.y / size.y * 2.0) * params.halves.y;+ return normalize(params.forward.xyz + params.right.xyz * screenX + params.above.xyz * screenY);+}++// Where a world point was on screen in the previous frame (xy), its distance from the previous eye (z), and w = 1 when it was in front of the camera.+fn projectToPrevious(point: vec3<f32>, size: vec2<f32>) -> vec4<f32> {+ let offset = point - params.previousEye.xyz;+ let alongView = dot(offset, params.previousForward.xyz);+ if (!(alongView > 1e-6)) { return vec4<f32>(0.0); }+ let screenX = dot(offset, params.previousRight.xyz) / alongView / params.halves.z;+ let screenY = dot(offset, params.previousAbove.xyz) / alongView / params.halves.w;+ return vec4<f32>(vec2<f32>(screenX * 0.5 + 0.5, 0.5 - screenY * 0.5) * size, length(offset), 1.0);+}++fn isHistoryConsistent(expectedDistance: f32, historyDistance: f32, normal: vec3<f32>, historyNormal: vec3<f32>, material: f32, historyMaterial: f32) -> bool {+ return abs(historyDistance - expectedDistance) <= DEPTH_TOLERANCE * expectedDistance && dot(normal, historyNormal) >= NORMAL_AGREEMENT && abs(material - historyMaterial) < 0.5;+}++fn pixelIndex(texel: vec2<i32>) -> u32 {+ return u32(texel.y * params.sizes.x + texel.x);+}++fn planeSize() -> u32 {+ return u32(params.sizes.x * params.sizes.y);+}++fn insideTraceImage(texel: vec2<i32>) -> bool {+ return all(texel >= vec2<i32>(0)) && all(texel < params.sizes.xy);+}+`;++const ACCUMULATE_SOURCE = DENOISE_COMMON + /* wgsl */ `+@group(0) @binding(1) var<storage, read> traced: array<vec4<f32>>;+@group(0) @binding(2) var<storage, read> tracedPrevious: array<vec4<f32>>;+@group(0) @binding(3) var<storage, read> historyPrevious: array<vec4<f32>>;+@group(0) @binding(4) var<storage, read_write> historyCurrent: array<vec4<f32>>;+@group(0) @binding(5) var<storage, read_write> filtered: array<vec4<f32>>;++fn illuminationAt(texel: vec2<i32>) -> vec3<f32> {+ let index = pixelIndex(clamp(texel, vec2<i32>(0), params.sizes.xy - vec2<i32>(1)));+ return traced[index].rgb / max(traced[planeSize() + index].rgb, vec3<f32>(MINIMUM_ALBEDO));+}++@compute @workgroup_size(8, 8, 1)+fn accumulate(@builtin(global_invocation_id) id: vec3<u32>) {+ let texel = vec2<i32>(id.xy);+ if (!insideTraceImage(texel)) { return; }+ let plane = planeSize();+ let index = pixelIndex(texel);+ let tracedValue = traced[index];+ let albedo = traced[plane + index].rgb;+ let normalAndMaterial = traced[2u * plane + index];+ let normal = normalAndMaterial.xyz;+ var illumination = tracedValue.rgb / max(albedo, vec3<f32>(MINIMUM_ALBEDO));+ let size = vec2<f32>(params.sizes.xy);+ let point = params.eye.xyz + pixelRayDirection(vec2<f32>(texel) + 0.5, size) * distanceOf(tracedValue);++ var history = vec4<f32>(0.0);+ var historyMoments = vec4<f32>(0.0);+ var historyAlbedo = vec3<f32>(0.0);+ var totalWeight = 0.0;+ let projection = projectToPrevious(point, size);+ if (params.settings.z < 0.5 && projection.w > 0.5) {+ let base = floor(projection.xy - 0.5);+ let fraction = projection.xy - 0.5 - base;+ for (var tap = 0; tap < 4; tap++) {+ let offset = vec2<i32>(tap & 1, tap >> 1u);+ let historyTexel = vec2<i32>(base) + offset;+ if (!insideTraceImage(historyTexel)) { continue; }+ let weight = select(1.0 - fraction.x, fraction.x, offset.x == 1) * select(1.0 - fraction.y, fraction.y, offset.y == 1);+ let historyIndex = pixelIndex(historyTexel);+ let previousNormal = tracedPrevious[2u * plane + historyIndex];+ if (!isHistoryConsistent(projection.z, distanceOf(tracedPrevious[historyIndex]), normal, previousNormal.xyz, normalAndMaterial.w, previousNormal.w)) { continue; }+ history += weight * historyPrevious[historyIndex];+ historyMoments += weight * historyPrevious[plane + historyIndex];+ historyAlbedo += weight * historyPrevious[2u * plane + historyIndex].rgb;+ totalWeight += weight;+ }+ }++ // While the history is short, a sample far above its eight neighbours is a firefly: bring it down to their mean plus a few+ // deviations. A long history averages the spikes in instead, which keeps the energy a clamp would cut.+ var neighbourSum = 0.0;+ var neighbourSumOfSquares = 0.0;+ for (var offsetY = -1; offsetY <= 1; offsetY++) {+ for (var offsetX = -1; offsetX <= 1; offsetX++) {+ if (offsetX == 0 && offsetY == 0) { continue; }+ let neighbour = luminanceOf(illuminationAt(texel + vec2<i32>(offsetX, offsetY)));+ neighbourSum += neighbour;+ neighbourSumOfSquares += neighbour * neighbour;+ }+ }+ let neighbourMean = neighbourSum / 8.0;+ let neighbourDeviation = sqrt(max(0.0, neighbourSumOfSquares / 8.0 - neighbourMean * neighbourMean));+ let luminanceLimit = neighbourMean * 1.05 + ${FIREFLY_DEVIATIONS} * neighbourDeviation + 0.01;+ var luminance = luminanceOf(illumination);+ let shortHistory = totalWeight <= 1e-3 || history.w < ${SHORT_HISTORY_LENGTH}.0;+ if (shortHistory && luminance > luminanceLimit) {+ illumination *= luminanceLimit / luminance;+ luminance = luminanceLimit;+ }+ let currentMoments = vec2<f32>(luminance, luminance * luminance);+ var color = illumination;+ var blendedAlbedo = albedo;+ var moments = currentMoments;+ var historyLength = 1.0;+ if (totalWeight > 1e-3) {+ history /= totalWeight;+ historyMoments /= totalWeight;+ historyAlbedo /= totalWeight;+ historyLength = min(history.w + 1.0, params.settings.y);+ let blend = 1.0 / historyLength;+ color = mix(history.rgb, illumination, blend);+ blendedAlbedo = mix(historyAlbedo, albedo, blend);+ moments = mix(historyMoments.xy, currentMoments, blend);+ }+ var variance = max(0.0, moments.y - moments.x * moments.x);+ if (historyLength < ${SPATIAL_VARIANCE_HISTORY}.0) {+ let sum = neighbourSum + luminance;+ let sumOfSquares = neighbourSumOfSquares + luminance * luminance;+ variance = max(0.0, sumOfSquares / 9.0 - (sum / 9.0) * (sum / 9.0));+ }+ historyCurrent[index] = vec4<f32>(color, historyLength);+ historyCurrent[plane + index] = vec4<f32>(moments, variance, 0.0);+ historyCurrent[2u * plane + index] = vec4<f32>(blendedAlbedo, 1.0);+ filtered[index] = vec4<f32>(color, variance);+}+`;++const ATROUS_SOURCE = DENOISE_COMMON + /* wgsl */ `+@group(0) @binding(1) var<storage, read> traced: array<vec4<f32>>;+@group(0) @binding(2) var<storage, read> filterIn: array<vec4<f32>>;+@group(0) @binding(3) var<storage, read_write> filterOut: array<vec4<f32>>;++const PLANE_SIGMA: f32 = 0.02;+const LUMINANCE_SIGMA: f32 = 4.0;+const NORMAL_POWER: f32 = 64.0;++fn kernelWeight(offset: i32) -> f32 {+ if (offset == 0) { return 0.375; }+ if (offset == 1) { return 0.25; }+ return 0.0625;+}++@compute @workgroup_size(8, 8, 1)+fn atrous(@builtin(global_invocation_id) id: vec3<u32>) {+ let texel = vec2<i32>(id.xy);+ if (!insideTraceImage(texel)) { return; }+ let plane = planeSize();+ let size = vec2<f32>(params.sizes.xy);+ let stride = i32(params.settings.w);+ let index = pixelIndex(texel);+ let center = filterIn[index];+ let centerNormal = traced[2u * plane + index].xyz;+ let centerDistance = distanceOf(traced[index]);+ let centerPoint = pixelRayDirection(vec2<f32>(texel) + 0.5, size) * centerDistance;+ let centerLuminance = luminanceOf(center.rgb);+ var smoothedVariance = 0.0;+ for (var offsetY = -1; offsetY <= 1; offsetY++) {+ for (var offsetX = -1; offsetX <= 1; offsetX++) {+ let neighbour = clamp(texel + vec2<i32>(offsetX, offsetY), vec2<i32>(0), params.sizes.xy - vec2<i32>(1));+ smoothedVariance += filterIn[pixelIndex(neighbour)].w * select(0.25, 0.5, offsetX == 0) * select(0.25, 0.5, offsetY == 0);+ }+ }+ let luminanceScale = LUMINANCE_SIGMA * sqrt(max(smoothedVariance, 0.0)) + 1e-4;++ var sumColor = vec3<f32>(0.0);+ var sumVariance = 0.0;+ var sumWeight = 0.0;+ for (var offsetY = -2; offsetY <= 2; offsetY++) {+ for (var offsetX = -2; offsetX <= 2; offsetX++) {+ let neighbour = texel + vec2<i32>(offsetX, offsetY) * stride;+ if (!insideTraceImage(neighbour)) { continue; }+ let neighbourIndex = pixelIndex(neighbour);+ let value = filterIn[neighbourIndex];+ let neighbourDistance = distanceOf(traced[neighbourIndex]);+ let neighbourPoint = pixelRayDirection(vec2<f32>(neighbour) + 0.5, size) * neighbourDistance;+ let planeDistance = abs(dot(centerNormal, neighbourPoint - centerPoint));+ let planeWeight = exp(-planeDistance / (PLANE_SIGMA * centerDistance));+ let normalWeight = pow(max(dot(centerNormal, traced[2u * plane + neighbourIndex].xyz), 0.0), NORMAL_POWER);+ let luminanceWeight = exp(-abs(luminanceOf(value.rgb) - centerLuminance) / luminanceScale);+ let weight = kernelWeight(abs(offsetX)) * kernelWeight(abs(offsetY)) * planeWeight * normalWeight * luminanceWeight;+ sumColor += weight * value.rgb;+ sumVariance += weight * weight * value.w;+ sumWeight += weight;+ }+ }+ filterOut[index] = select(center, vec4<f32>(sumColor / sumWeight, sumVariance / (sumWeight * sumWeight)), sumWeight > 1e-6);+}+`;++// The filtered light is upsampled to the output size with a joint bilinear filter that does not blend across edges,+// multiplied by the albedo history, tone mapped (ACES, gamma 2.2) and packed as the canvas format wants it.+const PRESENT_SOURCE = DENOISE_COMMON + /* wgsl */ `+@group(0) @binding(1) var<storage, read> traced: array<vec4<f32>>;+@group(0) @binding(2) var<storage, read> filtered: array<vec4<f32>>;+@group(0) @binding(3) var<storage, read> history: array<vec4<f32>>;+@group(0) @binding(4) var<storage, read_write> outputPixels: array<u32>;++fn toneMap(linearColor: vec3<f32>) -> vec3<f32> {+ let color = max(linearColor, vec3<f32>(0.0));+ let mapped = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), vec3<f32>(0.0), vec3<f32>(1.0));+ return pow(mapped, vec3<f32>(1.0 / 2.2));+}++@compute @workgroup_size(8, 8, 1)+fn present(@builtin(global_invocation_id) id: vec3<u32>) {+ let outputSize = vec2<f32>(params.sizes.zw);+ if (id.x >= u32(params.sizes.z) || id.y >= u32(params.sizes.w)) { return; }+ let traceSize = params.sizes.xy;+ let plane = planeSize();+ let position = (vec2<f32>(id.xy) + 0.5) / outputSize * vec2<f32>(traceSize);+ let nearest = clamp(vec2<i32>(floor(position)), vec2<i32>(0), traceSize - vec2<i32>(1));+ let nearestIndex = pixelIndex(nearest);+ let nearestDistance = distanceOf(traced[nearestIndex]);+ let nearestNormal = traced[2u * plane + nearestIndex].xyz;+ let base = floor(position - 0.5);+ let fraction = position - 0.5 - base;+ var illumination = vec3<f32>(0.0);+ var albedo = vec3<f32>(0.0);+ var totalWeight = 0.0;+ for (var tap = 0; tap < 4; tap++) {+ let offset = vec2<i32>(tap & 1, tap >> 1u);+ let texel = clamp(vec2<i32>(base) + offset, vec2<i32>(0), traceSize - vec2<i32>(1));+ let index = pixelIndex(texel);+ var weight = select(1.0 - fraction.x, fraction.x, offset.x == 1) * select(1.0 - fraction.y, fraction.y, offset.y == 1);+ weight *= exp(-abs(distanceOf(traced[index]) - nearestDistance) / (0.02 * nearestDistance));+ weight *= pow(max(dot(nearestNormal, traced[2u * plane + index].xyz), 0.0), 16.0);+ illumination += weight * filtered[index].rgb;+ albedo += weight * history[2u * plane + index].rgb;+ totalWeight += weight;+ }+ if (totalWeight < 1e-5) {+ illumination = filtered[nearestIndex].rgb;+ albedo = history[2u * plane + nearestIndex].rgb;+ totalWeight = 1.0;+ }+ let color = toneMap(illumination / totalWeight * max(albedo / totalWeight, vec3<f32>(MINIMUM_ALBEDO)));+ let bytes = vec3<u32>(color * 255.0 + 0.5);+ let swapped = params.outputLayout.y == 1u;+ let packedColor = select(bytes.x, bytes.z, swapped) | (bytes.y << 8u) | (select(bytes.z, bytes.x, swapped) << 16u) | (255u << 24u);+ outputPixels[id.y * params.outputLayout.x + id.x] = packedColor;+}+`;++function createPipeline(device, module, entryPoint) {+ return device.createComputePipelineAsync({ layout: 'auto', compute: { module, entryPoint } });+}++async function compileModule(device, label, code) {+ const module = device.createShaderModule({ label, code });+ const info = await module.getCompilationInfo();+ const errors = info.messages.filter(message => message.type === 'error');+ if (errors.length > 0) throw new Error(`The WebGPU real-time ${label} shader did not compile: ${errors.slice(0, 8).map(message => `${message.lineNum}: ${message.message}`).join('; ')}`);+ return module;+}++const storage = (device, label, bytes, extraUsage = 0) => device.createBuffer({ label, size: Math.max(16, bytes), usage: GPUBufferUsage.STORAGE | extraUsage });+const uniform = (device, label, bytes) => device.createBuffer({ label, size: bytes, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });+const bind = (device, pipeline, buffers) => device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: buffers.map((buffer, binding) => ({ binding, resource: { buffer } })) });++/**+ * The cache table (CACHE_SLOT_COUNT vec4: mean radiance and the number of records behind it) and the pass that folds the+ * records of a frame in. `table` is bound by the tracer kernel; `encode(pass, records, recordCount)` adds the dispatches.+ */+export async function createWebGpuRadianceCache(device) {+ const module = await compileModule(device, 'radiance cache', CACHE_SOURCE);+ const [scatterPipeline, resolvePipeline] = await Promise.all([createPipeline(device, module, 'scatterRecords'), createPipeline(device, module, 'resolveCells')]);+ const table = storage(device, 'radiance cache', CACHE_SLOT_COUNT * 16, GPUBufferUsage.COPY_DST);+ const sums = storage(device, 'radiance cache sums', CACHE_SLOT_COUNT * 16);+ const recordCountBuffer = uniform(device, 'record count', CACHE_PARAMETER_BYTES);+ let scatterGroup = null;+ let resolveGroup = null;+ return {+ table,+ clear(encoder) {+ encoder.clearBuffer(table);+ },+ encode(pass, records, recordCount) {+ device.queue.writeBuffer(recordCountBuffer, 0, new Uint32Array([recordCount, 0, 0, 0]));+ scatterGroup ??= device.createBindGroup({ layout: scatterPipeline.getBindGroupLayout(0), entries: [[0, records], [1, sums], [3, recordCountBuffer]].map(([binding, buffer]) => ({ binding, resource: { buffer } })) });+ resolveGroup ??= device.createBindGroup({ layout: resolvePipeline.getBindGroupLayout(0), entries: [sums, table].map((buffer, index) => ({ binding: index + 1, resource: { buffer } })) });+ pass.setPipeline(scatterPipeline);+ pass.setBindGroup(0, scatterGroup);+ const recordGroups = Math.ceil(recordCount / CACHE_WORKGROUP_SIZE);+ pass.dispatchWorkgroups(Math.min(recordGroups, 4096), Math.ceil(recordGroups / 4096));+ pass.setPipeline(resolvePipeline);+ pass.setBindGroup(0, resolveGroup);+ pass.dispatchWorkgroups(4096, CACHE_SLOT_COUNT / CACHE_WORKGROUP_SIZE / 4096);+ },+ dispose() {+ for (const buffer of [table, sums, recordCountBuffer]) buffer.destroy();+ },+ };+}++/** Rows of a texture copy start at multiples of 256 bytes. */+export const outputRowWords = width => Math.ceil(width * 4 / 256) * 64;++function writeDenoiseParameters(device, buffer, inputs, sizes, step, rowWords, swapped) {+ const words = new ArrayBuffer(DENOISE_PARAMETER_BYTES);+ const floats = new Float32Array(words);+ const integers = new Int32Array(words);+ const unsigned = new Uint32Array(words);+ const { camera, previousCamera } = inputs;+ floats.set([...camera.eye, 0, ...camera.forward, 0, ...camera.right, 0, ...camera.above, 0], 0);+ floats.set([...previousCamera.eye, 0, ...previousCamera.forward, 0, ...previousCamera.right, 0, ...previousCamera.above, 0], 16);+ floats.set([camera.halfWidth, camera.halfHeight, previousCamera.halfWidth, previousCamera.halfHeight], 32);+ integers.set(sizes, 36);+ floats.set([inputs.farDistance, inputs.historyLimit, inputs.resetHistory ? 1 : 0, step], 40);+ unsigned.set([rowWords, swapped ? 1 : 0, 0, 0], 44);+ device.queue.writeBuffer(buffer, 0, words);+}++/**+ * The temporal denoiser as compute passes. `encode(pass, set, inputs)` adds accumulate, the a-trous steps and the present+ * pass for the traced frame in `tracedBuffers[set]` (the frame before it is in the other set). The result is packed+ * pixels in `outputBuffer`, `outputRowWords(outputWidth)` words per row, red first, or blue first when `swapped`.+ */+export async function createWebGpuDenoiser(device, { traceWidth, traceHeight, outputWidth, outputHeight, tracedBuffers, historyLimit = DEFAULT_HISTORY_LIMIT, filterIterations = DEFAULT_FILTER_ITERATIONS, swapped = false }) {+ const [accumulateModule, atrousModule, presentModule] = await Promise.all([+ compileModule(device, 'accumulate', ACCUMULATE_SOURCE), compileModule(device, 'a-trous', ATROUS_SOURCE), compileModule(device, 'present', PRESENT_SOURCE),+ ]);+ const [accumulatePipeline, atrousPipeline, presentPipeline] = await Promise.all([+ createPipeline(device, accumulateModule, 'accumulate'), createPipeline(device, atrousModule, 'atrous'), createPipeline(device, presentModule, 'present'),+ ]);+ const plane = traceWidth * traceHeight * 16;+ const rowWords = outputRowWords(outputWidth);+ const sizes = [traceWidth, traceHeight, outputWidth, outputHeight];+ const histories = [0, 1].map(index => storage(device, `history ${index}`, plane * 3));+ const filters = [0, 1].map(index => storage(device, `filter ${index}`, plane));+ const outputBuffer = storage(device, 'output pixels', rowWords * 4 * outputHeight, GPUBufferUsage.COPY_SRC);+ const accumulateParameters = uniform(device, 'accumulate parameters', DENOISE_PARAMETER_BYTES);+ const atrousParameters = Array.from({ length: filterIterations }, () => uniform(device, 'a-trous parameters', DENOISE_PARAMETER_BYTES));+ const presentParameters = uniform(device, 'present parameters', DENOISE_PARAMETER_BYTES);+ const finalFilter = filters[filterIterations % 2];+ const groupsFor = (width, height) => [Math.ceil(width / 8), Math.ceil(height / 8)];+ const sets = [0, 1].map(set => ({+ accumulate: bind(device, accumulatePipeline, [accumulateParameters, tracedBuffers[set], tracedBuffers[1 - set], histories[1 - set], histories[set], filters[0]]),+ atrous: atrousParameters.map((parameters, iteration) => bind(device, atrousPipeline, [parameters, tracedBuffers[set], filters[iteration % 2], filters[1 - iteration % 2]])),+ present: bind(device, presentPipeline, [presentParameters, tracedBuffers[set], finalFilter, histories[set], outputBuffer]),+ }));++ return {+ outputBuffer,+ rowWords,+ encode(pass, set, inputs) {+ const settings = { ...inputs, historyLimit };+ writeDenoiseParameters(device, accumulateParameters, settings, sizes, 1, rowWords, swapped);+ atrousParameters.forEach((buffer, iteration) => writeDenoiseParameters(device, buffer, settings, sizes, 1 << iteration, rowWords, swapped));+ writeDenoiseParameters(device, presentParameters, settings, sizes, 1, rowWords, swapped);+ pass.setPipeline(accumulatePipeline);+ pass.setBindGroup(0, sets[set].accumulate);+ pass.dispatchWorkgroups(...groupsFor(traceWidth, traceHeight));+ pass.setPipeline(atrousPipeline);+ for (const group of sets[set].atrous) {+ pass.setBindGroup(0, group);+ pass.dispatchWorkgroups(...groupsFor(traceWidth, traceHeight));+ }+ pass.setPipeline(presentPipeline);+ pass.setBindGroup(0, sets[set].present);+ pass.dispatchWorkgroups(...groupsFor(outputWidth, outputHeight));+ },+ dispose() {+ for (const buffer of [...histories, ...filters, outputBuffer, accumulateParameters, presentParameters, ...atrousParameters]) buffer.destroy();+ },+ };+}diff --git a/src/path-tracer-realtime-webgpu.js b/src/path-tracer-realtime-webgpu.jsnew file mode 100644index 00000000..0237e719--- /dev/null+++ b/src/path-tracer-realtime-webgpu.js@@ -0,0 +1,189 @@+import { buildTraceScene } from './path-tracer-scene.js';+import { createCamera } from './path-tracer.js';+import { prepareRealtimeKernel } from './path-tracer-webgpu.js';+import { REALTIME_KERNEL_PIECES } from './path-tracer-realtime-webgpu-kernel.js';+import { cacheCellSizes } from './path-tracer-realtime-options.js';+import { createWebGpuDenoiser, createWebGpuRadianceCache } from './path-tracer-realtime-webgpu-passes.js';++// The WebGPU backend of the real-time path tracer (issue #624): the same frame as path-tracer-realtime.js, one path per+// pixel at half the output size, two bounces ended by the radiance cache, then the temporal denoiser, but every step is a+// compute pass of one command buffer and the tracing is the WebGPU megakernel (path-tracer-webgpu.js, which compiles in+// under a second). The kernel pieces are in path-tracer-realtime-webgpu-kernel.js, the cache and denoiser passes in+// path-tracer-realtime-webgpu-passes.js. The picture goes to `canvas` through a buffer to texture copy.++const TILE_CELL_SIZE_WORD = 48;+const TILE_LEVEL_DISTANCE_WORD = 49;+const SAMPLE_INDEX_WORD = 43;++const watchedDevices = new WeakSet();++// A rejected command does not throw in the page; the device reports it here, and the frame stays black or stale.+function reportDeviceErrors(device) {+ if (watchedDevices.has(device)) return;+ watchedDevices.add(device);+ device.addEventListener('uncapturederror', event => console.error(`WebGPU real-time tracer: ${event.error.message}`));+}++function createOutputCanvas(width, height) {+ const canvas = typeof document === 'undefined' ? new OffscreenCanvas(width, height) : document.createElement('canvas');+ canvas.width = width;+ canvas.height = height;+ return canvas;+}++/** `resolved` is what `resolveRealtimeOptions` returns for the options of `createRealtimeTracer`; `suppliedCanvas` is optional. */+export async function createWebGpuRealtimeTracer(scene, resolved, suppliedCanvas) {+ const { outputWidth, outputHeight, traceWidth, traceHeight, options, historyLimit, filterIterations, cacheCellSize } = resolved;+ let traceScene = null;+ let kernel = null;+ let device = null;+ let traced = null;+ let cache = null;+ let denoiser = null;+ let canvas = null;+ let context = null;+ let parameterBuffer = null;+ let recordBuffer = null;+ let traceGroups = null;+ let cellSizes = null;+ const pixelCount = traceWidth * traceHeight;+ const swapped = navigator.gpu.getPreferredCanvasFormat() === 'bgra8unorm';+ let currentSet = 0;+ let frameIndex = 0;+ let view = null;+ let resetHistory = true;+ let clearCache = true;+ let disposed = false;++ const loadScene = async (parts, environment) => {+ traceScene = buildTraceScene(parts, environment);+ const next = await prepareRealtimeKernel(traceScene, options, REALTIME_KERNEL_PIECES);+ const previousKernel = kernel;+ kernel = next;+ device = kernel.device;+ reportDeviceErrors(device);+ if (!traced) {+ traced = [0, 1].map(index => device.createBuffer({ label: `traced ${index}`, size: pixelCount * 16 * 3, usage: GPUBufferUsage.STORAGE }));+ recordBuffer = device.createBuffer({ label: 'cache records', size: pixelCount * 16, usage: GPUBufferUsage.STORAGE });+ parameterBuffer = device.createBuffer({ label: 'realtime parameters', size: 512, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });+ cache = await createWebGpuRadianceCache(device);+ denoiser = await createWebGpuDenoiser(device, { traceWidth, traceHeight, outputWidth, outputHeight, tracedBuffers: traced, historyLimit, filterIterations, swapped });+ canvas = suppliedCanvas ?? createOutputCanvas(outputWidth, outputHeight);+ context = canvas.getContext('webgpu');+ context.configure({ device, format: navigator.gpu.getPreferredCanvasFormat(), usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_DST, alphaMode: 'opaque' });+ }+ previousKernel?.uploaded.buffers.forEach(buffer => buffer.destroy());+ traceGroups = [0, 1].map(set => device.createBindGroup({+ layout: kernel.bindGroupLayout,+ entries: [+ { binding: 0, resource: { buffer: parameterBuffer, size: kernel.parameterBytes } },+ ...[...kernel.uploaded.buffers, traced[set], cache.table, recordBuffer].map((buffer, index) => ({ binding: index + 1, resource: { buffer } })),+ ],+ }));+ cellSizes = cacheCellSizes(traceScene, cacheCellSize);+ view = null;+ resetHistory = true;+ clearCache = true;+ };++ await loadScene(scene.parts, scene.environment ?? {});++ const writeParameters = (camera) => {+ const words = kernel.parameterWords(camera);+ const floats = new Float32Array(words.buffer);+ floats[TILE_CELL_SIZE_WORD] = cellSizes.cellSize;+ floats[TILE_LEVEL_DISTANCE_WORD] = cellSizes.levelDistance;+ words[SAMPLE_INDEX_WORD] = frameIndex + 1;+ device.queue.writeBuffer(parameterBuffer, 0, words);+ };++ const encodeFrame = (nextView, previousView) => {+ const encoder = device.createCommandEncoder();+ if (clearCache) {+ cache.clear(encoder);+ clearCache = false;+ }+ const pass = encoder.beginComputePass();+ pass.setPipeline(kernel.pipeline);+ pass.setBindGroup(0, traceGroups[currentSet], [0]);+ pass.dispatchWorkgroups(Math.ceil(traceWidth / 8), Math.ceil(traceHeight / 8));+ cache.encode(pass, recordBuffer, pixelCount);+ denoiser.encode(pass, currentSet, { camera: nextView, previousCamera: previousView, resetHistory, farDistance: traceScene.farDistance });+ pass.end();+ encoder.copyBufferToTexture(+ { buffer: denoiser.outputBuffer, bytesPerRow: denoiser.rowWords * 4, rowsPerImage: outputHeight },+ { texture: context.getCurrentTexture() },+ { width: outputWidth, height: outputHeight },+ );+ device.queue.submit([encoder.finish()]);+ };++ return {+ gpu: kernel.gpu,+ backend: 'webgpu',+ fallbackReason: null,+ get canvas() { return canvas; },+ width: outputWidth,+ height: outputHeight,+ traceWidth,+ traceHeight,+ get compileSeconds() { return kernel.compileSeconds; },+ get frameCount() { return frameIndex; },++ /** A new scene: the radiance cache and the denoiser's history start over. */+ async update({ parts, environment }) {+ if (parts) await loadScene(parts, environment ?? {});+ },++ /** Forgets the denoiser's history (the cache stays: it only depends on the scene). */+ resetHistory() {+ resetHistory = true;+ },++ /** Draws one frame to `canvas` for a camera. With `wait` the result has a `done` promise that settles when the GPU is done, for timing. */+ frame(camera, { wait = false } = {}) {+ if (disposed) throw new Error('This real-time tracer was disposed.');+ const nextView = createCamera(camera, outputWidth, outputHeight);+ const previousView = view ?? nextView;+ writeParameters(nextView);+ view = nextView;+ encodeFrame(nextView, previousView);+ resetHistory = false;+ currentSet = 1 - currentSet;+ frameIndex++;+ return { frame: frameIndex, done: wait ? device.queue.onSubmittedWorkDone() : undefined };+ },++ /** The last frame as tone mapped bytes, top row first. */+ async readFrame() {+ const rowBytes = denoiser.rowWords * 4;+ const readback = device.createBuffer({ size: rowBytes * outputHeight, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });+ const encoder = device.createCommandEncoder();+ encoder.copyBufferToBuffer(denoiser.outputBuffer, 0, readback, 0, rowBytes * outputHeight);+ device.queue.submit([encoder.finish()]);+ await readback.mapAsync(GPUMapMode.READ);+ const packed = new Uint8Array(readback.getMappedRange());+ const rgba = new Uint8ClampedArray(outputWidth * outputHeight * 4);+ for (let row = 0; row < outputHeight; row++) {+ for (let column = 0; column < outputWidth; column++) {+ const source = row * rowBytes + column * 4;+ const target = (row * outputWidth + column) * 4;+ rgba[target] = packed[source + (swapped ? 2 : 0)];+ rgba[target + 1] = packed[source + 1];+ rgba[target + 2] = packed[source + (swapped ? 0 : 2)];+ rgba[target + 3] = 255;+ }+ }+ readback.destroy();+ return { width: outputWidth, height: outputHeight, rgba };+ },++ dispose() {+ disposed = true;+ cache.dispose();+ denoiser.dispose();+ for (const buffer of [...traced, recordBuffer, parameterBuffer, ...kernel.uploaded.buffers]) buffer.destroy();+ context.unconfigure();+ },+ };+}diff --git a/src/path-tracer-realtime.js b/src/path-tracer-realtime.jsindex ab52a486..26878dac 100644--- a/src/path-tracer-realtime.js+++ b/src/path-tracer-realtime.js@@ -1,10 +1,11 @@import { buildTraceScene } from './path-tracer-scene.js';-import { createCamera, normalizePathTracerOptions } from './path-tracer.js';+import { createCamera } from './path-tracer.js';import { getContext, getKernel, releaseResources, setSceneUniforms, uploadScene } from './path-tracer-gpu.js';import { sceneUsesSubsurface } from './path-tracer-gpu-pack.js';import { createRadianceCache } from './path-tracer-radiance-cache.js';import { createTemporalDenoiser } from './path-tracer-temporal-denoise.js';import { createFloatTexture, createFramebuffer, FIRST_PASS_TEXTURE_UNIT } from './path-tracer-realtime-gl.js';+import { cacheCellSizes, resolveRealtimeOptions, viewsMatch } from './path-tracer-realtime-options.js';// A real-time hybrid view of the GPU path tracer (issue #624): one path per pixel and frame at half the output size,// two bounces, ended by a spatial hash radiance cache, then a temporal denoiser that also upsamples to the output size.@@ -13,35 +14,27 @@ import { createFloatTexture, createFramebuffer, FIRST_PASS_TEXTURE_UNIT } from '// static). It shares the WebGL2 context of `traceOnGpu`, so one render at a time owns it. The pieces:// path-tracer-radiance-cache.js, path-tracer-temporal-denoise.js, path-tracer-reprojection.js.-const DEFAULT_BOUNCES = 2;-const DEFAULT_RESOLUTION_DIVISOR = 2;-const CACHE_CELLS_ACROSS_SCENE = 200;-const CACHE_LEVEL_CELLS = 64;-const SCENE_EXTENT_SCALE = 1e4;--function viewsMatch(first, second) {- if (!first || !second) return false;- const keys = ['eye', 'forward', 'right', 'above'];- return keys.every(key => first[key].every((value, axis) => value === second[key][axis])) && first.halfWidth === second.halfWidth && first.halfHeight === second.halfHeight;-}-/*** `scene` is `{ parts, environment, camera }` as `renderPathTracedImage` takes them. `options`: `width` and `height` of the* output, `bounces` (2), `resolutionDivisor` (2: the tracing size is half the output), `seed`, `lightSelection`* ("importance"), `historyLimit` and `filterIterations` of the denoiser, `cacheCellSize` (the scene's size over 200).- * The picture is tone mapped with ACES like the default view transform.+ * The picture is tone mapped with ACES like the default view transform. `backend` is "gpu" (WebGL2, the default) or+ * "webgpu" (compute passes, path-tracer-realtime-webgpu.js): without WebGPU on the page, "webgpu" falls back to WebGL2, and+ * the tracer's `backend` and `fallbackReason` say so. The WebGPU tracer draws to its own `canvas` (or the one in+ * `options.canvas`), and its `readFrame` and `frame({ wait })` return promises.*/export async function createRealtimeTracer(scene, rawOptions = {}) {- const { resolutionDivisor = DEFAULT_RESOLUTION_DIVISOR, historyLimit, filterIterations, cacheCellSize } = rawOptions;- const outputWidth = rawOptions.width ?? 960;- const outputHeight = rawOptions.height ?? 540;- const traceWidth = Math.max(1, Math.ceil(outputWidth / resolutionDivisor));- const traceHeight = Math.max(1, Math.ceil(outputHeight / resolutionDivisor));- const options = normalizePathTracerOptions({- seed: rawOptions.seed, lightSelection: rawOptions.lightSelection ?? 'importance', bounces: rawOptions.bounces ?? DEFAULT_BOUNCES,- width: traceWidth, height: traceHeight, samples: 1, backend: 'gpu', denoise: false,- });- options.radianceCache = true;+ const resolved = resolveRealtimeOptions(rawOptions);+ let fallbackReason = null;+ if (resolved.backend === 'webgpu') {+ try {+ const { createWebGpuRealtimeTracer } = await import('./path-tracer-realtime-webgpu.js');+ return await createWebGpuRealtimeTracer(scene, resolved, rawOptions.canvas);+ } catch (error) {+ fallbackReason = error.message;+ }+ }+ const { outputWidth, outputHeight, traceWidth, traceHeight, options, historyLimit, filterIterations, cacheCellSize } = resolved;const { gl, gpu } = getContext();if (gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS) < FIRST_PASS_TEXTURE_UNIT + 12) throw new Error('The real-time path tracer needs 28 texture units.');gl.canvas.width = outputWidth;@@ -81,10 +74,9 @@ export async function createRealtimeTracer(scene, rawOptions = {}) {lightCount = uploaded.lightCount;cacheTextureUnit = uploaded.nextUnit;gl.uniform1i(gl.getUniformLocation(program, 'uRadianceCache'), cacheTextureUnit);- const extent = traceScene.farDistance / SCENE_EXTENT_SCALE;- const cellSize = cacheCellSize ?? extent / CACHE_CELLS_ACROSS_SCENE;+ const { cellSize, levelDistance } = cacheCellSizes(traceScene, cacheCellSize);gl.uniform1f(gl.getUniformLocation(program, 'uCacheCellSize'), cellSize);- gl.uniform1f(gl.getUniformLocation(program, 'uCacheLevelDistance'), cellSize * CACHE_LEVEL_CELLS);+ gl.uniform1f(gl.getUniformLocation(program, 'uCacheLevelDistance'), levelDistance);cache.clear();view = null;resetHistory = true;@@ -106,6 +98,8 @@ export async function createRealtimeTracer(scene, rawOptions = {}) {return {gpu,+ backend: 'gpu',+ fallbackReason,canvas: gl.canvas,width: outputWidth,height: outputHeight,diff --git a/src/path-tracer-webgpu-kernel.js b/src/path-tracer-webgpu-kernel.jsindex 16aa8428..b11acef3 100644--- a/src/path-tracer-webgpu-kernel.js+++ b/src/path-tracer-webgpu-kernel.js@@ -920,8 +920,9 @@ fn bakeTexels(@builtin(global_invocation_id) id: vec3<u32>, @builtin(num_workgro}`;-export const buildMegakernelSource = ({ hasVolume = false, hasSubsurface = false, texelBake = false } = {}) => buildCommonSource({ hasVolume }) + /* wgsl */ `-// The first hit lights from every emitter; later hits draw one, and divide by the chance of drawing it.+// `realtime` is the set of WGSL pieces of path-tracer-realtime-webgpu-kernel.js (REALTIME_KERNEL_PIECES); the real-time tracer passes them in, so other bundles do not carry them.+export const buildMegakernelSource = ({ hasVolume = false, hasSubsurface = false, texelBake = false, realtime = null } = {}) => buildCommonSource({ hasVolume }) + /* wgsl */ `+${realtime ? realtime.declarations + realtime.addLights : `// 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) {@@ -935,7 +936,7 @@ fn addLights(depth: i32, normal: vec3<f32>) {selectionProbability = 1.0 / f32(emitterCount);sampleEmitter(depth, normal, i32(floor(nextRandom() * f32(emitterCount))));flushShadowRay();-}+}`}${hasSubsurface ? SUBSURFACE_FUNCTIONS : ''}fn tracePath(origin: vec3<f32>, startDirection: vec3<f32>, pixel: u32, sampleIndex: u32) {resetRandom(pixel, sampleIndex, params.seedAndAtlas.x);@@ -970,6 +971,7 @@ fn tracePath(origin: vec3<f32>, startDirection: vec3<f32>, pixel: u32, sampleIndentering = dot(hitNormal, direction) < 0.0;normal = select(-hitNormal, hitNormal, entering);isGlass = hitTransmission > 0.0 && nextRandom() < hitTransmission;+ ${realtime ? realtime.firstHit : ''}if (!featuresRecorded) {featureAlbedo = select(hitColor, vec3<f32>(1.0), isGlass);featureNormal = normal;@@ -985,6 +987,7 @@ fn tracePath(origin: vec3<f32>, startDirection: vec3<f32>, pixel: u32, sampleInd}if (needsLights) { addLights(depth, normal); }inMedium = false;+ ${realtime ? realtime.terminal : ''}${hasVolume ? `if (inFog) {let phaseCosine = sampleHenyeyGreensteinCosine(params.volumeMaximumAnisotropy.w, nextRandom());let phaseSine = sqrt(max(0.0, 1.0 - phaseCosine * phaseCosine));@@ -1033,13 +1036,14 @@ fn tracePath(origin: vec3<f32>, startDirection: vec3<f32>, pixel: u32, sampleIndpreviousPdf = surfacePdf;afterMirror = false;}+ ${realtime ? realtime.record : ''}}position = hitPoint + direction * surfaceOffset;if (!survivesRoulette(depth)) { break; }}}-${texelBake ? TEXEL_MAIN : CAMERA_MAIN}+${texelBake ? TEXEL_MAIN : realtime ? realtime.main : CAMERA_MAIN}`;export const MEGAKERNEL_SOURCE = buildMegakernelSource();diff --git a/src/path-tracer-webgpu.js b/src/path-tracer-webgpu.jsindex fb0f02ba..8fe25e92 100644--- a/src/path-tracer-webgpu.js+++ b/src/path-tracer-webgpu.js@@ -73,8 +73,9 @@ async function getSession() {}/** The WGSL and entry points of a kernel variant; a variant is one of the two kernels, with the optional parts a scene needs. */-function describeVariant({ kernel, hasVolume, hasSubsurface, texelBake }) {+function describeVariant({ kernel, hasVolume, hasSubsurface, texelBake, realtime }) {if (kernel === 'wavefront') return { code: WAVEFRONT_SOURCE, entryPoints: WAVEFRONT_ENTRY_POINTS };+ if (realtime) return { code: buildMegakernelSource({ hasVolume, hasSubsurface, realtime }), entryPoints: ['traceRealtime'] };return { code: buildMegakernelSource({ hasVolume, hasSubsurface, texelBake }), entryPoints: [texelBake ? 'bakeTexels' : 'main'] };}@@ -92,7 +93,7 @@ async function compileKernel(current, variant) {}async function getKernel(current, variant) {- const key = [variant.kernel, variant.hasVolume, variant.hasSubsurface, variant.texelBake].join(':');+ const key = [variant.kernel, variant.hasVolume, variant.hasSubsurface, variant.texelBake, Boolean(variant.realtime)].join(':');if (!current.kernels.has(key)) current.kernels.set(key, compileKernel(current, variant));return current.kernels.get(key);}@@ -320,6 +321,26 @@ export async function traceOnWebGpu(scene, camera, options, shouldStop) {return Object.assign(buffers, { gpu: current.gpu, compileSeconds });}+/**+ * The pieces the real-time tracer (path-tracer-realtime-webgpu.js) builds its frame from, given its kernel's WGSL `realtimePieces`: the device, the real-time kernel's+ * pipeline and bind group layout for `scene`, the uploaded scene tables, and `parameterWords(camera)`, the words of the+ * parameter block for a camera (the caller sets the sample index and the cache words).+ */+export async function prepareRealtimeKernel(scene, options, realtimePieces) {+ const current = await getSession();+ const { device } = current;+ const { pipelines, compileSeconds } = await getKernel(current, { kernel: 'megakernel', ...sceneFeatures(scene), realtime: realtimePieces });+ const uploaded = uploadScene(device, scene);+ const emitterCount = (scene.lights.sun ? 1 : 0) + uploaded.lightCount + (scene.environment ? 1 : 0);+ return {+ device, gpu: current.gpu, compileSeconds, uploaded,+ bindGroupLayout: current.bindGroupLayout,+ pipeline: pipelines.traceRealtime,+ parameterBytes: PARAMETER_BYTES,+ parameterWords: camera => createParameterTemplate(scene, camera, options, uploaded, emitterCount).unsigned,+ };+}+const TEXEL_GROUPS_PER_ROW = 4096;const TEXEL_SAMPLES_PER_WAIT = 16;diff --git a/tests/path-tracer-realtime-webgpu.test.js b/tests/path-tracer-realtime-webgpu.test.jsnew file mode 100644index 00000000..7dc7e968--- /dev/null+++ b/tests/path-tracer-realtime-webgpu.test.js@@ -0,0 +1,73 @@+import assert from 'node:assert/strict';+import test from 'node:test';++import { buildMegakernelSource, MEGAKERNEL_SOURCE } from '../src/path-tracer-webgpu-kernel.js';+import { REALTIME_KERNEL_PIECES } from '../src/path-tracer-realtime-webgpu-kernel.js';+import { CACHE_SLOT_COUNT, MAXIMUM_LEVEL, NORMAL_AXIS_THRESHOLD } from '../src/path-tracer-radiance-cache.js';+import { outputRowWords } from '../src/path-tracer-realtime-webgpu-passes.js';+import { cacheCellSizes, resolveRealtimeOptions, viewsMatch } from '../src/path-tracer-realtime-options.js';++test('the default megakernel does not carry the real-time pieces', () => {+ assert.equal(MEGAKERNEL_SOURCE, buildMegakernelSource());+ for (const name of ['cacheLookup', 'cacheHash', 'traceRealtime', 'cacheRecords', 'chooseEmitterByImportance']) {+ assert.ok(!MEGAKERNEL_SOURCE.includes(name), name);+ }+ assert.ok(MEGAKERNEL_SOURCE.includes('fn main('));+});++test('the real-time megakernel ends paths in the cache, records the hit before, and has its own entry point', () => {+ const source = buildMegakernelSource({ realtime: REALTIME_KERNEL_PIECES });+ assert.ok(source.includes('fn traceRealtime('));+ assert.ok(!source.includes('fn main('));+ assert.ok(source.includes('addRadiance(depth, throughput * hitColor * cacheLookup(hitPoint, normal));'));+ assert.ok(source.includes('recordedSlot = f32(cacheHash(hitPoint, normal)) + 1.0;'));+ assert.ok(source.includes('firstHitMaterial = f32(hitMaterialIndex) + 1.0;'));+ assert.equal(source.split('fn addLights(').length, 2, 'one light selection only');+ assert.ok(source.includes('chooseEmitterByImportance(normal)'));+});++test('the WGSL cache hash uses the constants of the JavaScript reference', () => {+ assert.ok(REALTIME_KERNEL_PIECES.declarations.includes(`hash & ${CACHE_SLOT_COUNT - 1}u`));+ assert.ok(REALTIME_KERNEL_PIECES.declarations.includes(`0.0, ${MAXIMUM_LEVEL}.0)`));+ assert.ok(REALTIME_KERNEL_PIECES.declarations.includes(`component > ${NORMAL_AXIS_THRESHOLD}`));+ for (const constant of ['73856093u', '19349663u', '83492791u', '0x9e3779b1u', '0x85ebca6bu', '0x7feb352du', '0x846ca68bu']) {+ assert.ok(REALTIME_KERNEL_PIECES.declarations.includes(constant), constant);+ }+});++test('the real-time pieces stay out of the other kernel variants', () => {+ assert.ok(REALTIME_KERNEL_PIECES.addLights.includes('chooseEmitterByImportance'));+ assert.ok(!REALTIME_KERNEL_PIECES.main.includes('@group(0)'), 'bindings are declared once, in the declarations');+ assert.ok(buildMegakernelSource({ texelBake: true }).includes('fn bakeTexels('));+ assert.ok(!buildMegakernelSource({ texelBake: true }).includes('traceRealtime'));+});++test('the output rows of the texture copy are whole 256 byte multiples', () => {+ assert.equal(outputRowWords(1920), 1920);+ assert.equal(outputRowWords(960), 960);+ assert.equal(outputRowWords(100), 128);+ assert.equal(outputRowWords(1) * 4 % 256, 0);+});++test('the real-time options default to WebGL2 and name the backends they know', () => {+ assert.equal(resolveRealtimeOptions({}).backend, 'gpu');+ assert.equal(resolveRealtimeOptions({ backend: 'webgpu', width: 1920, height: 1080 }).traceWidth, 960);+ assert.throws(() => resolveRealtimeOptions({ backend: 'vulkan' }), /"gpu", "webgpu"|gpu, webgpu/);+ const resolved = resolveRealtimeOptions({ bounces: 3 });+ assert.equal(resolved.options.bounces, 3);+ assert.equal(resolved.options.radianceCache, true);+});++test('the cache cell size follows the scene unless it is given', () => {+ assert.deepEqual(cacheCellSizes({ farDistance: 2e4 }, 0.5), { cellSize: 0.5, levelDistance: 32 });+ const derived = cacheCellSizes({ farDistance: 2e4 });+ assert.equal(derived.cellSize, 2 / 200);+ assert.equal(derived.levelDistance, derived.cellSize * 64);+});++test('two cameras that look the same way match', () => {+ const view = { eye: [0, 1, 4], forward: [0, 0, -1], right: [1, 0, 0], above: [0, 1, 0], halfWidth: 1, halfHeight: 0.5 };+ assert.equal(viewsMatch(view, { ...view, eye: [0, 1, 4] }), true);+ assert.equal(viewsMatch(view, { ...view, eye: [0, 1, 4.1] }), false);+ assert.equal(viewsMatch(null, view), false);+});