Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Real-time hybrid path traced view: radiance cache, temporal denoiser, half-size tracing (issue #624)

Nguyen Xuan An36b9ef232f22
diff --git a/bench/realtime-tracer/page.js b/bench/realtime-tracer/page.js
new file mode 100644
index 00000000..0603d148
--- /dev/null
+++ b/bench/realtime-tracer/page.js
@@ -0,0 +1,71 @@
+// Page side of bench/realtime-tracer/run.mjs: loaded into bench/reference/harness.html (which supplies the scenes).
+const median = values => [...values].sort((first, second) => first - second)[Math.floor(values.length / 2)];
+
+function orbitCamera(camera, degrees) {
+ const radians = degrees * Math.PI / 180;
+ const offsetX = camera.eye[0] - camera.target[0];
+ const offsetZ = camera.eye[2] - camera.target[2];
+ const eye = [
+ camera.target[0] + offsetX * Math.cos(radians) - offsetZ * Math.sin(radians),
+ camera.eye[1],
+ camera.target[2] + offsetX * Math.sin(radians) + offsetZ * Math.cos(radians),
+ ];
+ return { ...camera, eye };
+}
+
+function toBase64Png(frame) {
+ const canvas = document.createElement('canvas');
+ canvas.width = frame.width;
+ canvas.height = frame.height;
+ canvas.getContext('2d').putImageData(new ImageData(frame.rgba, frame.width, frame.height), 0, 0);
+ return canvas.toDataURL('image/png').split(',')[1];
+}
+
+async function openTracer(source, options) {
+ const scene = await window.loadTraceSceneFor(source);
+ const { createRealtimeTracer } = await import('/src/path-tracer-realtime.js');
+ const tracer = await createRealtimeTracer(scene, options);
+ return { scene, tracer };
+}
+
+// Median of `frames` frames; the camera orbits `degreesPerFrame` each frame (0 for a resting camera).
+window.measureRealtimeFrames = async function measureRealtimeFrames(source, options, frames = 200, degreesPerFrame = 0.5, warmup = 10) {
+ const { scene, tracer } = await openTracer(source, options);
+ const times = [];
+ for (let frame = 0; frame < frames + warmup; frame++) {
+ const started = performance.now();
+ tracer.frame(orbitCamera(scene.camera, frame * degreesPerFrame), { wait: true });
+ 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) };
+ tracer.dispose();
+ return result;
+};
+
+// 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 });
+ const started = performance.now();
+ let frames = 1;
+ while (performance.now() - started < seconds * 1000) {
+ tracer.frame(scene.camera, { wait: true });
+ frames++;
+ }
+ const image = toBase64Png(tracer.readFrame());
+ tracer.dispose();
+ return { image, frames, elapsedSeconds: (performance.now() - started) / 1000 };
+};
+
+// 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 });
+ 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()));
+ }
+ tracer.dispose();
+ return images;
+};
diff --git a/bench/realtime-tracer/run.mjs b/bench/realtime-tracer/run.mjs
new file mode 100644
index 00000000..839faab1
--- /dev/null
+++ b/bench/realtime-tracer/run.mjs
@@ -0,0 +1,73 @@
+// 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]
+// 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';
+import { constants, setPriority } from 'node:os';
+import { resolve } from 'node:path';
+import { chromium } from 'playwright';
+import { createServer } from 'vite';
+
+const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';
+const argumentsGiven = process.argv.slice(2);
+const outputDirectory = resolve(argumentsGiven[0]);
+const sceneIds = argumentsGiven[1].split(',');
+const valueAfter = (flag, fallback) => (argumentsGiven.includes(flag) ? argumentsGiven[argumentsGiven.indexOf(flag) + 1] : fallback);
+const 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 recipeName = id => id.replace(/^.*[\/]/, '').replace(/\.recipe\.json$|\.json$/, '');
+
+setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
+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 timings = {};
+try {
+ const page = await browser.newPage({ viewport: { width: 960, height: 540 } });
+ page.on('pageerror', error => console.log('PAGE ERROR', error.message));
+ page.on('console', message => { if (message.type() === 'error') console.log('PAGE CONSOLE', message.text()); });
+ page.setDefaultTimeout(0);
+ await page.goto(`${serverUrl}/bench/reference/harness.html`, { timeout: 180000 });
+ await page.waitForFunction(() => window.loadTraceSceneFor, null, { timeout: 180000 });
+ await page.addScriptTag({ type: 'module', url: '/bench/realtime-tracer/page.js' });
+ await page.waitForFunction(() => window.measureRealtimeFrames, null, { timeout: 60000 });
+ for (const id of sceneIds) {
+ const name = id.endsWith('.json') ? recipeName(id) : id;
+ const source = id.endsWith('.json') ? JSON.parse(await readFile(id, 'utf8')) : id;
+ if (mode === 'time' || mode === 'all') {
+ for (const degreesPerFrame of [0.5, 0]) {
+ 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 };
+ console.log(name, label, JSON.stringify(timings[`${name}:${label}`]));
+ }
+ }
+ if (mode === 'rest' || mode === 'all') {
+ const rest = await page.evaluate(([scene, tracerOptions]) => window.renderRestingFrame(scene, tracerOptions, 1), [source, options]);
+ await writeFile(`${outputDirectory}/${name}@realtime-rest.png`, Buffer.from(rest.image, 'base64'));
+ timings[`${name}:rest-frame`] = { frames: rest.frames, seconds: Number(rest.elapsedSeconds.toFixed(2)) };
+ console.log(name, 'resting frame', JSON.stringify(timings[`${name}:rest-frame`]));
+ }
+ if (mode === 'move' || mode === 'all') {
+ const images = await page.evaluate(([scene, tracerOptions]) => window.renderCameraMove(scene, tracerOptions), [source, options]);
+ for (const [index, image] of images.entries()) await writeFile(`${outputDirectory}/${name}@move-${index + 1}.png`, Buffer.from(image, 'base64'));
+ console.log(name, 'camera move', images.length, 'frames');
+ }
+ }
+} finally {
+ await browser.close();
+ await server.close();
+}
+let previous = {};
+try {
+ previous = JSON.parse(await readFile(`${outputDirectory}/timings.json`, 'utf8'));
+} catch {
+ // first run in this directory
+}
+await writeFile(`${outputDirectory}/timings.json`, JSON.stringify({ ...previous, ...timings }, null, 1));
diff --git a/bench/realtime-tracer/score.py b/bench/realtime-tracer/score.py
new file mode 100644
index 00000000..e0a8d9fe
--- /dev/null
+++ b/bench/realtime-tracer/score.py
@@ -0,0 +1,53 @@
+# FLIP of the resting real-time frame (bench/realtime-tracer/run.mjs, <scene>@realtime-rest.png) and of the 64 sample still
+# (bench/reference/progressive-compare.mjs --still, <scene>@still-64.png) against the Cycles render.
+# uv run --no-project --python 3.12 --with flip-evaluator --with pillow --with numpy python -I bench/realtime-tracer/score.py <directory> <scene id>,... --cycles <directory with <scene>-cycles.npy>
+# A real-time frame at twice the Cycles size is reduced with a 2 by 2 box filter first.
+import json
+import sys
+from pathlib import Path
+
+import flip_evaluator
+import numpy as np
+from PIL import Image
+
+GAMMA = 2.2
+
+
+def load_png(path):
+ return np.asarray(Image.open(path).convert("RGB"), dtype=np.float32) / 255
+
+
+def tone_map_like_67js(linear):
+ color = np.maximum(linear, 0)
+ mapped = np.clip((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), 0, 1)
+ return mapped ** (1 / GAMMA)
+
+
+def reduce_to(image, height, width):
+ if image.shape[0] == height * 2 and image.shape[1] == width * 2:
+ return image.reshape(height, 2, width, 2, 3).mean(axis=(1, 3))
+ return image
+
+
+def flip_score(reference, test):
+ _, mean_error, _ = flip_evaluator.evaluate(reference.astype(np.float32), test.astype(np.float32), "LDR", inputsRGB=True)
+ return round(float(mean_error), 4)
+
+
+def main():
+ directory = Path(sys.argv[1])
+ scene_ids = sys.argv[2].split(",")
+ cycles_directory = Path(sys.argv[sys.argv.index("--cycles") + 1])
+ rows = {}
+ for scene_id in scene_ids:
+ cycles = tone_map_like_67js(np.load(cycles_directory / f"{scene_id}-cycles.npy"))
+ row = {}
+ for label, name in (("realtime", f"{scene_id}@realtime-rest.png"), ("still-64", f"{scene_id}@still-64.png")):
+ if (directory / name).exists():
+ row[label] = flip_score(cycles, reduce_to(load_png(directory / name), cycles.shape[0], cycles.shape[1]))
+ rows[scene_id] = row
+ print(scene_id.ljust(18), json.dumps(row))
+ (directory / "realtime-score.json").write_text(json.dumps(rows, indent=1) + "\n", encoding="utf-8")
+
+
+main()
diff --git a/bench/realtime-tracer/sheet.py b/bench/realtime-tracer/sheet.py
new file mode 100644
index 00000000..3a52b259
--- /dev/null
+++ b/bench/realtime-tracer/sheet.py
@@ -0,0 +1,29 @@
+# One contact sheet of a camera move (bench/realtime-tracer/run.mjs --mode move, <scene>@move-<n>.png): two columns, frames
+# in order from left to right and top to bottom, each reduced to 480 by 270.
+# uv run --no-project --python 3.12 --with pillow python -I bench/realtime-tracer/sheet.py <directory> <scene id>
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+CELL_WIDTH = 480
+CELL_HEIGHT = 270
+COLUMNS = 2
+
+
+def main():
+ directory = Path(sys.argv[1])
+ scene_id = sys.argv[2]
+ paths = sorted((path for path in directory.glob(f"{scene_id}@move-*.png") if path.stem.rsplit("-", 1)[1].isdigit()), key=lambda path: int(path.stem.rsplit("-", 1)[1]))
+ rows = (len(paths) + COLUMNS - 1) // COLUMNS
+ sheet = Image.new("RGB", (CELL_WIDTH * COLUMNS, CELL_HEIGHT * rows))
+ for index, path in enumerate(paths):
+ cell = Image.open(path).convert("RGB").resize((CELL_WIDTH, CELL_HEIGHT), Image.LANCZOS)
+ ImageDraw.Draw(cell).text((6, 4), f"move frame {index + 1}", fill=(255, 255, 255))
+ sheet.paste(cell, (CELL_WIDTH * (index % COLUMNS), CELL_HEIGHT * (index // COLUMNS)))
+ output = directory / f"{scene_id}@move-sheet.png"
+ sheet.save(output)
+ print(output)
+
+
+main()
diff --git a/bench/reference/harness.js b/bench/reference/harness.js
index 9e716634..79314c2f 100644
--- a/bench/reference/harness.js
+++ b/bench/reference/harness.js
@@ -481,3 +481,5 @@ async function measureProgressiveFrameTime(source, options, frames = 200, warmup
window.renderProgressiveCheckpoints = renderProgressiveCheckpoints;
window.measureProgressiveFrameTime = measureProgressiveFrameTime;
+
+window.loadTraceSceneFor = loadTraceSceneFor;
diff --git a/changes/624.md b/changes/624.md
new file mode 100644
index 00000000..091c396b
--- /dev/null
+++ b/changes/624.md
@@ -0,0 +1 @@
+- `67js/addons/path-tracer-realtime` (`createRealtimeTracer(scene, options)`, then `frame(camera)`) is a real-time view of the WebGL2 path tracer: one path per pixel and frame at half the output size, two bounces whose last hit reads a spatial hash radiance cache, and a temporal denoiser (reprojection, variance, a-trous passes) that upsamples to the output size and draws to a canvas; the scene is static, motion vectors come from the camera, and primary hits are traced rather than rasterized (#624)
diff --git a/changes/624.size.md b/changes/624.size.md
new file mode 100644
index 00000000..8e3a7a5c
--- /dev/null
+++ b/changes/624.size.md
@@ -0,0 +1,5 @@
+- entry:path-tracer+lazy: the GPU kernel builder carries the radiance cache shader text (about 1 KB gzip) that only the new real-time addon compiles in; the GPU tracer's own pixels and speed do not change.
+- entry:path-tracer-progressive: same 1 KB of cache shader text in the kernel builder the progressive addon shares; it is only compiled in for the real-time addon.
+- entry:path-tracer-progressive+lazy: same 1 KB of cache shader text in the kernel builder.
+- entry:light-bake-gpu: same 1 KB of cache shader text in the kernel builder the GPU light bake shares.
+- entry:light-bake-gpu+lazy: same 1 KB of cache shader text in the kernel builder.
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 1e32fc6c..17bc8dae 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -147,3 +147,15 @@ Measured on the RTX 3060, 960 by 540, FLIP against Cycles of the denoised image,
The still of `spot-area` took 60.5 s including 29.9 s of kernel compile. Blue noise alone scored the same as random within 0.0003 at every count on both scenes (it helps the 1 sample image only by 0.001 to 0.002). Median frame time of one sample per pixel, 200 frames, 960 by 540: demo room 69 ms (67 to 71) random and 71 to 73 ms with both options; `lit-interior` 32 ms; `spot-area` 14 ms.
Light choice at equal samples (16 and 64) on the 16 path tracer scenes: 12 scenes have one local light or none and are identical. Better: `lit-interior` 0.0769 to 0.0572 at 64 (0.1318 to 0.0884 at 16), `spot-area` 0.0262 to 0.0224, `light-linking` 0.0291 to 0.0273 at 16. Not better: `brick-room` 0.2587 to 0.2686 at 64 and `light-linking` 0.0213 to 0.0217 at 64. In `brick-room` both choices score worse at 64 than at 16 (0.2491 and 0.2499 at 16), so the converged image is further from Cycles and the score cannot judge the noise; the criterion "no worse on every scene" is therefore not met by this measure, which is why the option stays off. `bench/reference/progressive-compare.mjs` and `progressive-score.py` made the numbers.
+
+## Real-time hybrid view (issue #624)
+
+`67js/addons/path-tracer-realtime` (`createRealtimeTracer(scene, { width, height, bounces, ... })`, then `frame(camera)` for every picture) draws the WebGL2 tracer fast enough to move the camera. It shares the WebGL2 context of the GPU still, so one render at a time owns it, and it draws to `canvas` (an `OffscreenCanvas` or a canvas element, 8 bit, ACES view transform). `readFrame()` returns the same picture as bytes. The pieces, each in its own module so they can move to the WebGPU backend:
+
+- **Half-size tracing.** One path per pixel and frame at half the output size (`resolutionDivisor`, 2), two bounces (`bounces`, 2). The first hit picks one light by importance instead of tracing a shadow ray to every light, which the denoiser averages over frames.
+- **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.
+
+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.
diff --git a/package.json b/package.json
index 0dd4f8d5..a7a6955c 100644
--- a/package.json
+++ b/package.json
@@ -87,6 +87,7 @@
"./addons/floor-sky-visibility": "./build/floor-sky-visibility.js",
"./addons/path-tracer": "./build/path-tracer.js",
"./addons/path-tracer-progressive": "./build/path-tracer-progressive.js",
+ "./addons/path-tracer-realtime": "./build/path-tracer-realtime.js",
"./addons/texture-set": "./build/texture-set.js",
"./addons/agent-scene": "./build/agent-scene.js",
"./addons/agent-asset": "./build/agent-asset.js",
diff --git a/src/path-tracer-gpu-shader.js b/src/path-tracer-gpu-shader.js
index e45611af..dca1c73f 100644
--- a/src/path-tracer-gpu-shader.js
+++ b/src/path-tracer-gpu-shader.js
@@ -1,3 +1,4 @@
+import { CACHE_DECLARATIONS, CACHE_OUTPUT, CACHE_RECORD, CACHE_TERMINAL } from './path-tracer-radiance-cache.js';
import { SUBSURFACE_FUNCTIONS, SUBSURFACE_LOBE, SUBSURFACE_SPLIT, SUBSURFACE_UNIFORM } from './path-tracer-gpu-subsurface.js';
// The GPU path tracer kernel: a WebGL2 fragment shader that follows the same paths as the CPU tracer in
@@ -61,7 +62,7 @@ const TEXEL_MAIN = `void main() {
if (texelIndex >= uTexelCount) rayDirection = normal;
tracePath(origin, rayDirection, pixel, sampleIndex);`;
-const buildSource = (hasSubsurface, texelBake, blueNoise, lightImportance) => `#version 300 es
+const buildSource = (hasSubsurface, texelBake, blueNoise, lightImportance, radianceCache) => `#version 300 es
precision highp float;
precision highp int;
precision highp sampler2D;
@@ -76,6 +77,8 @@ const int LIGHT_TEXELS = ${LIGHT_TEXELS};
const int STACK_SIZE = 128;
const bool BLUE_NOISE_FIRST = ${blueNoise};
const bool IMPORTANT_LIGHTS = ${lightImportance};
+// The real-time kernel picks one emitter at the first hit too (the denoiser averages the choices over frames) instead of tracing a shadow ray to every emitter.
+const bool STOCHASTIC_FIRST_HIT = ${radianceCache};
const int ALPHA_STEP_LIMIT = 8;
const int RUSSIAN_ROULETTE_START = 3;
const float MINIMUM_ALPHA = 1e-3;
@@ -124,6 +127,7 @@ layout(location = 0) out vec4 outRadiance;
layout(location = 1) out vec4 outAlbedo;
layout(location = 2) out vec4 outNormal;
layout(location = 3) out vec4 outStatistics;
+${radianceCache ? CACHE_DECLARATIONS : ''}
vec4 fetchData(sampler2D source, int index) {
return texelFetch(source, ivec2(index & TEXTURE_MASK, index >> TEXTURE_SHIFT), 0);
@@ -1015,7 +1019,7 @@ int chooseEmitterByImportance(vec3 normal, out float probability) {
/** The first hit lights from every emitter; later hits draw one, and divide by the chance of drawing it. */
void addLights(int depth, vec3 normal) {
- if (depth == 0 || uEmitterCount <= 1) {
+ if ((depth == 0 && !STOCHASTIC_FIRST_HIT) || uEmitterCount <= 1) {
selectionProbability = 1.0;
for (int emitter = 0; emitter < uEmitterCount; emitter++) {
sampleEmitter(depth, normal, emitter);
@@ -1109,6 +1113,7 @@ ${hasSubsurface ? SUBSURFACE_SPLIT : ''}
}
if (needsLights) addLights(depth, normal);
inMedium = false;
+${radianceCache ? CACHE_TERMINAL : ''}
if (inFog) {
float cosine = sampleHenyeyGreensteinCosine(uVolumeShape.y, nextRandom());
float sine = sqrt(max(0.0, 1.0 - cosine * cosine));
@@ -1151,6 +1156,7 @@ ${hasSubsurface ? SUBSURFACE_LOBE : ''}
previousPdf = surfacePdf;
afterMirror = false;
}
+${radianceCache ? CACHE_RECORD : ''}
}
position = hitPoint + direction * uSurfaceOffset;
if (!survivesRoulette(depth)) break;
@@ -1168,6 +1174,7 @@ ${texelBake ? TEXEL_MAIN : CAMERA_MAIN}
outAlbedo = vec4(featureAlbedo, 0.0);
outNormal = vec4(featureNormal, 0.0);
outStatistics = vec4(sampleLuminance, sampleLuminance * sampleLuminance, firstLegEscaped, 0.0);
+${radianceCache ? CACHE_OUTPUT : ''}
}
`;
@@ -1175,8 +1182,8 @@ ${texelBake ? TEXEL_MAIN : CAMERA_MAIN}
* The kernel; `hasSubsurface` compiles in the random walk, which only scenes with a subsurface part need. `texelBake`
* starts every path at a lightmap texel instead of the camera (see light-bake-gpu.js).
*/
-export function buildFragmentSource({ hasSubsurface = false, texelBake = false, blueNoise = false, lightImportance = false } = {}) {
- return buildSource(hasSubsurface, texelBake, blueNoise, lightImportance);
+export function buildFragmentSource({ hasSubsurface = false, texelBake = false, blueNoise = false, lightImportance = false, radianceCache = false } = {}) {
+ return buildSource(hasSubsurface, texelBake, blueNoise, lightImportance, radianceCache);
}
export const FRAGMENT_SOURCE = buildFragmentSource();
diff --git a/src/path-tracer-gpu.js b/src/path-tracer-gpu.js
index d76706da..ec90f22b 100644
--- a/src/path-tracer-gpu.js
+++ b/src/path-tracer-gpu.js
@@ -217,10 +217,11 @@ export function getKernel(hasSubsurface, texelBake = false, options = {}) {
const { gl, programs } = getContext();
const blueNoise = options.samplingPattern === 'blue-noise-first';
const lightImportance = options.lightSelection === 'importance';
- const key = `${hasSubsurface}:${texelBake}:${blueNoise}:${lightImportance}`;
+ const radianceCache = options.radianceCache === true;
+ const key = `${hasSubsurface}:${texelBake}:${blueNoise}:${lightImportance}:${radianceCache}`;
if (!programs.has(key)) {
const started = performance.now();
- const program = createProgram(gl, { hasSubsurface, texelBake, blueNoise, lightImportance });
+ const program = createProgram(gl, { hasSubsurface, texelBake, blueNoise, lightImportance, radianceCache });
gl.getProgramParameter(program, gl.LINK_STATUS);
programs.set(key, { program, compileSeconds: (performance.now() - started) / 1000 });
if (!texelBake) kernelCompileCount++;
diff --git a/src/path-tracer-radiance-cache.js b/src/path-tracer-radiance-cache.js
new file mode 100644
index 00000000..7d7ce57d
--- /dev/null
+++ b/src/path-tracer-radiance-cache.js
@@ -0,0 +1,211 @@
+import { createFloatTexture, createFramebuffer, createPass, bindInput, drawFullscreen, FRAGMENT_HEADER } from './path-tracer-realtime-gl.js';
+
+// A spatial hash radiance cache for the real-time path tracer (issue #624), in the manner of NVIDIA SHaRC. A cell is the
+// quantized position (cells grow with the distance from the eye, so far surfaces share cells) and the quantized normal
+// of a surface point. Each cell keeps the mean radiance that arrived at its points, as a running average over frames.
+// - a path ends at its last hit by reading the cell there (`cacheLookup`), so two bounces see the light of many;
+// - the path's second hit writes what the rest of the path brought back (`outCacheUpdate`), and a point pass adds those
+// records into the cells with additive blending, because WebGL2 has no atomics.
+// Cells are not checked against collisions: two surfaces that hash alike share a cell (about 1 of 1000 at 100,000 cells).
+
+export const CACHE_TEXTURE_SIZE = 1024;
+export const CACHE_SLOT_COUNT = CACHE_TEXTURE_SIZE * CACHE_TEXTURE_SIZE;
+export const CACHE_HISTORY_LIMIT = 128;
+export const NORMAL_AXIS_THRESHOLD = 0.3;
+export const MAXIMUM_LEVEL = 8;
+
+const multiplyUnsigned = (first, second) => Math.imul(first, second) >>> 0;
+
+function normalAxisCode(component) {
+ if (component > NORMAL_AXIS_THRESHOLD) return 2;
+ if (component < -NORMAL_AXIS_THRESHOLD) return 0;
+ return 1;
+}
+
+/** The size level of the cells at `distance` from the eye: it doubles the cell size each time the distance doubles past `levelDistance`. */
+export function cacheLevel(distance, levelDistance) {
+ return Math.min(Math.max(Math.floor(Math.log2(Math.max(distance / levelDistance, 1))), 0), MAXIMUM_LEVEL);
+}
+
+/** The slot (0 to CACHE_SLOT_COUNT - 1) of the cell of a surface point. The shader function `cacheHash` computes the same value. */
+export function cacheSlot({ point, normal, eye, cellSize, levelDistance }) {
+ const level = cacheLevel(Math.hypot(point[0] - eye[0], point[1] - eye[1], point[2] - eye[2]), levelDistance);
+ const levelCellSize = cellSize * 2 ** level;
+ const cell = point.map(component => Math.floor(component / levelCellSize));
+ const normalCode = normalAxisCode(normal[0]) + 3 * normalAxisCode(normal[1]) + 9 * normalAxisCode(normal[2]);
+ let hash = (multiplyUnsigned(cell[0], 73856093) ^ multiplyUnsigned(cell[1], 19349663) ^ multiplyUnsigned(cell[2], 83492791)) >>> 0;
+ hash = (hash ^ multiplyUnsigned(normalCode + 1, 0x9e3779b1)) >>> 0;
+ hash = (hash ^ multiplyUnsigned(level, 0x85ebca6b)) >>> 0;
+ hash = (hash ^ (hash >>> 16)) >>> 0;
+ hash = multiplyUnsigned(hash, 0x7feb352d);
+ hash = (hash ^ (hash >>> 15)) >>> 0;
+ hash = multiplyUnsigned(hash, 0x846ca68b);
+ hash = (hash ^ (hash >>> 16)) >>> 0;
+ return hash & (CACHE_SLOT_COUNT - 1);
+}
+
+/**
+ * The running average a cell applies to the records that landed in it this frame: `count` records with mean radiance
+ * `mean` meet a cell of `previousMean` over `previousCount` earlier records. The history counts at most CACHE_HISTORY_LIMIT.
+ */
+export function mergeCell({ previousMean, previousCount, mean, count }) {
+ if (count < 1) return { mean: previousMean, count: previousCount };
+ const weight = count / (Math.min(previousCount, CACHE_HISTORY_LIMIT) + count);
+ return { mean: previousMean.map((value, channel) => value + (mean[channel] - value) * weight), count: previousCount + count };
+}
+
+// GLSL that the tracer kernel includes (path-tracer-gpu-shader.js) when the kernel is built with the cache.
+export const CACHE_DECLARATIONS = `
+uniform sampler2D uRadianceCache;
+uniform float uCacheCellSize;
+uniform float uCacheLevelDistance;
+layout(location = 4) out vec4 outCacheUpdate;
+const int CACHE_SHIFT = ${Math.log2(CACHE_TEXTURE_SIZE)};
+const int CACHE_MASK = ${CACHE_TEXTURE_SIZE - 1};
+const float NORMAL_AXIS_THRESHOLD = ${NORMAL_AXIS_THRESHOLD};
+float recordedSlot = 0.0;
+vec3 recordedRadianceBefore = vec3(0.0);
+vec3 recordedThroughput = vec3(1.0);
+
+uint normalAxisCode(float component) {
+ if (component > NORMAL_AXIS_THRESHOLD) return 2u;
+ if (component < -NORMAL_AXIS_THRESHOLD) return 0u;
+ return 1u;
+}
+
+uint cacheHash(vec3 point, vec3 normal) {
+ float level = clamp(floor(log2(max(length(point - uEye) / uCacheLevelDistance, 1.0))), 0.0, ${MAXIMUM_LEVEL}.0);
+ ivec3 cell = ivec3(floor(point / (uCacheCellSize * exp2(level))));
+ uint normalCode = normalAxisCode(normal.x) + 3u * normalAxisCode(normal.y) + 9u * normalAxisCode(normal.z);
+ uint hash = uint(cell.x) * 73856093u ^ uint(cell.y) * 19349663u ^ uint(cell.z) * 83492791u;
+ hash ^= (normalCode + 1u) * 0x9e3779b1u;
+ hash ^= uint(level) * 0x85ebca6bu;
+ hash ^= hash >> 16;
+ hash *= 0x7feb352du;
+ hash ^= hash >> 15;
+ hash *= 0x846ca68bu;
+ hash ^= hash >> 16;
+ return hash & uint(${CACHE_SLOT_COUNT - 1});
+}
+
+// The mean radiance that arrives at the cell of a surface point; black while the cell has no record yet.
+vec3 cacheLookup(vec3 point, vec3 normal) {
+ int slot = int(cacheHash(point, normal));
+ vec4 cell = texelFetch(uRadianceCache, ivec2(slot & CACHE_MASK, slot >> CACHE_SHIFT), 0);
+ return cell.a >= 1.0 ? cell.rgb : vec3(0.0);
+}
+`;
+
+// The last hit of a path adds the cell's radiance, times what the path carries and the surface colour (a diffuse reading).
+export const CACHE_TERMINAL = `
+ if (depth == uBounces && !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.
+export const CACHE_RECORD = `
+ if (depth == max(uBounces - 1, 0) && !isMirror) {
+ recordedSlot = float(cacheHash(hitPoint, normal)) + 1.0;
+ recordedRadianceBefore = radiance;
+ recordedThroughput = throughput;
+ }`;
+
+// The record: the light the rest of the path brought, per unit of the weight at that hit (the incoming radiance).
+export const CACHE_OUTPUT = `
+ vec3 recordedTail = clamp((radiance - recordedRadianceBefore) / max(recordedThroughput, vec3(0.05)), vec3(0.0), vec3(uFireflyClamp));
+ outCacheUpdate = recordedSlot > 0.0 ? vec4(recordedTail, recordedSlot) : vec4(0.0);`;
+
+const SCATTER_VERTEX = `#version 300 es
+precision highp float;
+precision highp int;
+precision highp sampler2D;
+uniform sampler2D uRecords;
+uniform ivec2 uRecordSize;
+out vec3 vRadiance;
+void main() {
+ vec4 record = texelFetch(uRecords, ivec2(gl_VertexID % uRecordSize.x, gl_VertexID / uRecordSize.x), 0);
+ gl_PointSize = 1.0;
+ vRadiance = record.rgb;
+ if (record.a < 0.5) {
+ gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+ return;
+ }
+ int slot = int(record.a) - 1;
+ vec2 texel = vec2(float(slot & ${CACHE_TEXTURE_SIZE - 1}), float(slot >> ${Math.log2(CACHE_TEXTURE_SIZE)})) + 0.5;
+ gl_Position = vec4(texel / ${CACHE_TEXTURE_SIZE}.0 * 2.0 - 1.0, 0.0, 1.0);
+}`;
+
+const SCATTER_FRAGMENT = `${FRAGMENT_HEADER}
+in vec3 vRadiance;
+out vec4 outSum;
+void main() {
+ outSum = vec4(vRadiance, 1.0);
+}`;
+
+const RESOLVE_FRAGMENT = `${FRAGMENT_HEADER}
+uniform sampler2D uPreviousCache;
+uniform sampler2D uSums;
+out vec4 outCache;
+void main() {
+ ivec2 texel = ivec2(gl_FragCoord.xy);
+ vec4 previous = texelFetch(uPreviousCache, texel, 0);
+ vec4 sums = texelFetch(uSums, texel, 0);
+ if (sums.a < 0.5) {
+ outCache = previous;
+ return;
+ }
+ float weight = sums.a / (min(previous.a, ${CACHE_HISTORY_LIMIT}.0) + sums.a);
+ outCache = vec4(mix(previous.rgb, sums.rgb / sums.a, weight), previous.a + sums.a);
+}`;
+
+/**
+ * The cache textures and the two passes that fold a frame's records in. `texture` is the current cache for the tracer's
+ * `uRadianceCache`; `update(recordTexture, recordWidth, recordHeight)` adds the records the tracer wrote.
+ */
+export function createRadianceCache(gl) {
+ const scatterPass = createPass(gl, SCATTER_FRAGMENT, SCATTER_VERTEX);
+ const resolvePass = createPass(gl, RESOLVE_FRAGMENT);
+ const caches = [createFloatTexture(gl, CACHE_TEXTURE_SIZE, CACHE_TEXTURE_SIZE), createFloatTexture(gl, CACHE_TEXTURE_SIZE, CACHE_TEXTURE_SIZE)];
+ const sums = createFloatTexture(gl, CACHE_TEXTURE_SIZE, CACHE_TEXTURE_SIZE);
+ const cacheFramebuffers = caches.map(texture => createFramebuffer(gl, [{ slot: 0, texture }]));
+ const sumsFramebuffer = createFramebuffer(gl, [{ slot: 0, texture: sums }]);
+ let current = 0;
+
+ const clear = () => {
+ for (const framebuffer of [...cacheFramebuffers, sumsFramebuffer]) {
+ gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+ gl.clearBufferfv(gl.COLOR, 0, [0, 0, 0, 0]);
+ }
+ };
+ clear();
+
+ return {
+ get texture() { return caches[current]; },
+ clear,
+ update(recordTexture, recordWidth, recordHeight) {
+ gl.bindFramebuffer(gl.FRAMEBUFFER, sumsFramebuffer);
+ gl.clearBufferfv(gl.COLOR, 0, [0, 0, 0, 0]);
+ gl.viewport(0, 0, CACHE_TEXTURE_SIZE, CACHE_TEXTURE_SIZE);
+ gl.useProgram(scatterPass.program);
+ bindInput(gl, scatterPass, 'uRecords', 0, recordTexture);
+ gl.uniform2i(scatterPass.locate('uRecordSize'), recordWidth, recordHeight);
+ gl.enable(gl.BLEND);
+ gl.blendFunc(gl.ONE, gl.ONE);
+ gl.drawArrays(gl.POINTS, 0, recordWidth * recordHeight);
+ gl.disable(gl.BLEND);
+ const next = 1 - current;
+ gl.useProgram(resolvePass.program);
+ bindInput(gl, resolvePass, 'uPreviousCache', 0, caches[current]);
+ bindInput(gl, resolvePass, 'uSums', 1, sums);
+ drawFullscreen(gl, cacheFramebuffers[next], CACHE_TEXTURE_SIZE, CACHE_TEXTURE_SIZE);
+ current = next;
+ },
+ dispose() {
+ for (const texture of [...caches, sums]) gl.deleteTexture(texture);
+ for (const framebuffer of [...cacheFramebuffers, sumsFramebuffer]) gl.deleteFramebuffer(framebuffer);
+ gl.deleteProgram(scatterPass.program);
+ gl.deleteProgram(resolvePass.program);
+ },
+ };
+}
diff --git a/src/path-tracer-realtime-gl.js b/src/path-tracer-realtime-gl.js
new file mode 100644
index 00000000..978bd842
--- /dev/null
+++ b/src/path-tracer-realtime-gl.js
@@ -0,0 +1,79 @@
+// Small WebGL2 helpers of the real-time path tracer's passes (radiance cache, temporal denoiser). The tracer program
+// keeps texture units 0 to 15 for the scene tables; these passes bind their inputs from unit 16 up.
+
+export const FIRST_PASS_TEXTURE_UNIT = 16;
+// The same triangle as the tracer kernel's vertex shader (not imported: the kernel imports the radiance cache, which imports this file).
+export const FULLSCREEN_VERTEX_SOURCE = `#version 300 es
+void main() {
+ vec2 corner = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+ gl_Position = vec4(corner * 2.0 - 1.0, 0.0, 1.0);
+}`;
+export const FRAGMENT_HEADER = `#version 300 es
+precision highp float;
+precision highp int;
+precision highp sampler2D;
+`;
+
+function compileShader(gl, type, source) {
+ const shader = gl.createShader(type);
+ gl.shaderSource(shader, source);
+ gl.compileShader(shader);
+ if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) throw new Error(`A real-time path tracer shader did not compile: ${gl.getShaderInfoLog(shader)}`);
+ return shader;
+}
+
+/** A program with a uniform lookup that remembers locations. */
+export function createPass(gl, fragmentSource, vertexSource = FULLSCREEN_VERTEX_SOURCE) {
+ const program = gl.createProgram();
+ gl.attachShader(program, compileShader(gl, gl.VERTEX_SHADER, vertexSource));
+ gl.attachShader(program, compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource));
+ gl.linkProgram(program);
+ if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(`A real-time path tracer program did not link: ${gl.getProgramInfoLog(program)}`);
+ const locations = new Map();
+ const locate = name => {
+ if (!locations.has(name)) locations.set(name, gl.getUniformLocation(program, name));
+ return locations.get(name);
+ };
+ return { program, locate };
+}
+
+export function createFloatTexture(gl, width, height) {
+ const texture = gl.createTexture();
+ gl.activeTexture(gl.TEXTURE0 + FIRST_PASS_TEXTURE_UNIT);
+ gl.bindTexture(gl.TEXTURE_2D, texture);
+ gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA32F, width, height, 0, gl.RGBA, gl.FLOAT, null);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+ return texture;
+}
+
+/** A framebuffer from `{ slot, texture }` entries; slots without an entry are not drawn to. */
+export function createFramebuffer(gl, attachments) {
+ const framebuffer = gl.createFramebuffer();
+ gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+ const slotCount = Math.max(...attachments.map(entry => entry.slot)) + 1;
+ const drawBuffers = new Array(slotCount).fill(gl.NONE);
+ for (const { slot, texture } of attachments) {
+ gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0 + slot, gl.TEXTURE_2D, texture, 0);
+ drawBuffers[slot] = gl.COLOR_ATTACHMENT0 + slot;
+ }
+ gl.drawBuffers(drawBuffers);
+ if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) throw new Error('The real-time path tracer cannot render to float targets here.');
+ return framebuffer;
+}
+
+/** Binds `texture` to the pass's sampler `name` on the pass texture unit `index`. The pass must be in use. */
+export function bindInput(gl, pass, name, index, texture) {
+ gl.activeTexture(gl.TEXTURE0 + FIRST_PASS_TEXTURE_UNIT + index);
+ gl.bindTexture(gl.TEXTURE_2D, texture);
+ gl.uniform1i(pass.locate(name), FIRST_PASS_TEXTURE_UNIT + index);
+}
+
+export function drawFullscreen(gl, framebuffer, width, height) {
+ gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+ gl.viewport(0, 0, width, height);
+ gl.disable(gl.BLEND);
+ gl.drawArrays(gl.TRIANGLES, 0, 3);
+}
diff --git a/src/path-tracer-realtime.js b/src/path-tracer-realtime.js
new file mode 100644
index 00000000..ab52a486
--- /dev/null
+++ b/src/path-tracer-realtime.js
@@ -0,0 +1,172 @@
+import { buildTraceScene } from './path-tracer-scene.js';
+import { createCamera, normalizePathTracerOptions } 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';
+
+// 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.
+// `frame(camera)` draws one picture to `canvas`. Primary hits are traced, not rasterized (the tracer's first hit already
+// gives the albedo, normal and distance a G-buffer would), and motion vectors come from the camera's move (the scene is
+// 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.
+ */
+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 { 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;
+ gl.canvas.height = outputHeight;
+
+ const radianceTextures = [createFloatTexture(gl, traceWidth, traceHeight), createFloatTexture(gl, traceWidth, traceHeight)];
+ const normalTextures = [createFloatTexture(gl, traceWidth, traceHeight), createFloatTexture(gl, traceWidth, traceHeight)];
+ const albedoTexture = createFloatTexture(gl, traceWidth, traceHeight);
+ const recordTexture = createFloatTexture(gl, traceWidth, traceHeight);
+ const traceFramebuffers = [0, 1].map(index => createFramebuffer(gl, [
+ { slot: 0, texture: radianceTextures[index] }, { slot: 1, texture: albedoTexture }, { slot: 2, texture: normalTextures[index] }, { slot: 4, texture: recordTexture },
+ ]));
+ const cache = createRadianceCache(gl);
+ const denoiser = createTemporalDenoiser(gl, { traceWidth, traceHeight, outputWidth, outputHeight, historyLimit, filterIterations });
+ const synchronizationPixel = new Uint8Array(4);
+
+ let traceScene = null;
+ let program = null;
+ let lightCount = 0;
+ let cacheTextureUnit = 0;
+ let compileSeconds = 0;
+ let currentSet = 0;
+ let frameIndex = 0;
+ let view = null;
+ let previousView = null;
+ let resetHistory = true;
+ let disposed = false;
+
+ const loadScene = (parts, environment) => {
+ releaseResources(gl);
+ traceScene = buildTraceScene(parts, environment);
+ const kernel = getKernel(sceneUsesSubsurface(traceScene.materials), false, options);
+ program = kernel.program;
+ compileSeconds = kernel.compileSeconds;
+ gl.useProgram(program);
+ const uploaded = uploadScene(gl, program, traceScene, options);
+ 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;
+ gl.uniform1f(gl.getUniformLocation(program, 'uCacheCellSize'), cellSize);
+ gl.uniform1f(gl.getUniformLocation(program, 'uCacheLevelDistance'), cellSize * CACHE_LEVEL_CELLS);
+ cache.clear();
+ view = null;
+ resetHistory = true;
+ };
+
+ loadScene(scene.parts, scene.environment ?? {});
+
+ const traceOneSample = () => {
+ gl.useProgram(program);
+ gl.uniform1i(gl.getUniformLocation(program, 'uSample'), frameIndex + 1);
+ gl.activeTexture(gl.TEXTURE0 + cacheTextureUnit);
+ gl.bindTexture(gl.TEXTURE_2D, cache.texture);
+ gl.bindFramebuffer(gl.FRAMEBUFFER, traceFramebuffers[currentSet]);
+ gl.viewport(0, 0, traceWidth, traceHeight);
+ gl.disable(gl.BLEND);
+ gl.disable(gl.SCISSOR_TEST);
+ gl.drawArrays(gl.TRIANGLES, 0, 3);
+ };
+
+ return {
+ gpu,
+ canvas: gl.canvas,
+ width: outputWidth,
+ height: outputHeight,
+ traceWidth,
+ traceHeight,
+ get compileSeconds() { return compileSeconds; },
+ get frameCount() { return frameIndex; },
+
+ /** A new scene: the radiance cache and the denoiser's history start over. */
+ update({ parts, environment }) {
+ if (parts) 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 call returns once 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);
+ previousView = view ?? nextView;
+ if (!viewsMatch(view, nextView)) {
+ gl.useProgram(program);
+ setSceneUniforms(gl, program, traceScene, nextView, options, lightCount);
+ }
+ view = nextView;
+ traceOneSample();
+ cache.update(recordTexture, traceWidth, traceHeight);
+ denoiser.run({
+ radiance: radianceTextures[currentSet], albedo: albedoTexture, normal: normalTextures[currentSet],
+ previousRadiance: radianceTextures[1 - currentSet], previousNormal: normalTextures[1 - currentSet],
+ camera: view, previousCamera: previousView, resetHistory, farDistance: traceScene.farDistance,
+ });
+ resetHistory = false;
+ currentSet = 1 - currentSet;
+ frameIndex++;
+ // gl.finish() does not wait in every browser; reading one value back does.
+ if (wait) gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, synchronizationPixel);
+ return { frame: frameIndex };
+ },
+
+ /** The last frame as tone mapped bytes, top row first. Call it right after `frame`, before the page gets a turn. */
+ readFrame() {
+ gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+ const bottomUp = new Uint8Array(outputWidth * outputHeight * 4);
+ gl.readPixels(0, 0, outputWidth, outputHeight, gl.RGBA, gl.UNSIGNED_BYTE, bottomUp);
+ const rgba = new Uint8ClampedArray(bottomUp.length);
+ const rowBytes = outputWidth * 4;
+ for (let row = 0; row < outputHeight; row++) rgba.set(bottomUp.subarray((outputHeight - 1 - row) * rowBytes, (outputHeight - row) * rowBytes), row * rowBytes);
+ return { width: outputWidth, height: outputHeight, rgba };
+ },
+
+ dispose() {
+ disposed = true;
+ cache.dispose();
+ denoiser.dispose();
+ for (const texture of [...radianceTextures, ...normalTextures, albedoTexture, recordTexture]) gl.deleteTexture(texture);
+ for (const framebuffer of traceFramebuffers) gl.deleteFramebuffer(framebuffer);
+ releaseResources(gl);
+ },
+ };
+}
diff --git a/src/path-tracer-reprojection.js b/src/path-tracer-reprojection.js
new file mode 100644
index 00000000..974f5c04
--- /dev/null
+++ b/src/path-tracer-reprojection.js
@@ -0,0 +1,113 @@
+// Temporal reprojection for the real-time path tracer (issue #624): where a surface point seen now was on screen in the
+// previous frame, which of the four neighbouring history pixels may be reused, and the shader text that does the same.
+// The camera is the object `createCamera` of path-tracer.js returns (eye, forward, right, above, halfWidth, halfHeight).
+// The JavaScript functions are the reference the tests check; the GLSL below repeats them line by line.
+
+export const DEPTH_TOLERANCE = 0.06;
+export const NORMAL_AGREEMENT = 0.9;
+
+/** The world direction of the camera ray through a pixel position (pixel centres sit at +0.5). */
+export function pixelRayDirection(camera, pixelX, pixelY, width, height) {
+ const screenX = (pixelX / width * 2 - 1) * camera.halfWidth;
+ const screenY = (1 - pixelY / height * 2) * camera.halfHeight;
+ const direction = [0, 1, 2].map(axis => camera.forward[axis] + camera.right[axis] * screenX + camera.above[axis] * screenY);
+ const length = Math.hypot(...direction);
+ return direction.map(component => component / length);
+}
+
+/** The pixel position and the eye distance of a world point in a camera, or null when the point is behind it. */
+export function projectToPixel(camera, point, width, height) {
+ const offset = [0, 1, 2].map(axis => point[axis] - camera.eye[axis]);
+ const dot = vector => offset[0] * vector[0] + offset[1] * vector[1] + offset[2] * vector[2];
+ const alongView = dot(camera.forward);
+ if (!(alongView > 1e-6)) return null;
+ const screenX = dot(camera.right) / alongView / camera.halfWidth;
+ const screenY = dot(camera.above) / alongView / camera.halfHeight;
+ return { x: (screenX * 0.5 + 0.5) * width, y: (0.5 - screenY * 0.5) * height, distance: Math.hypot(...offset) };
+}
+
+/**
+ * The motion vector of a pixel, in pixels, from the previous frame to this one: the surface point the pixel sees at
+ * `distance` along its ray is projected into the previous camera. Null when it was behind the previous camera.
+ * `previous` holds where that point was and how far from the previous eye.
+ */
+export function motionVector(camera, previousCamera, pixelX, pixelY, distance, width, height) {
+ const direction = pixelRayDirection(camera, pixelX, pixelY, width, height);
+ const point = [0, 1, 2].map(axis => camera.eye[axis] + direction[axis] * distance);
+ const previous = projectToPixel(previousCamera, point, width, height);
+ if (!previous) return null;
+ return { x: pixelX - previous.x, y: pixelY - previous.y, previous };
+}
+
+/** The four history pixels around a position and their bilinear weights (the weights add up to 1). */
+export function bilinearTaps(positionX, positionY) {
+ const left = Math.floor(positionX - 0.5);
+ const top = Math.floor(positionY - 0.5);
+ const fractionX = positionX - 0.5 - left;
+ const fractionY = positionY - 0.5 - top;
+ return [
+ { column: left, row: top, weight: (1 - fractionX) * (1 - fractionY) },
+ { column: left + 1, row: top, weight: fractionX * (1 - fractionY) },
+ { column: left, row: top + 1, weight: (1 - fractionX) * fractionY },
+ { column: left + 1, row: top + 1, weight: fractionX * fractionY },
+ ];
+}
+
+/** Whether a history pixel shows the same surface: its distance within a relative tolerance and its normal close. */
+export function isHistoryConsistent({ expectedDistance, historyDistance, normal, historyNormal }) {
+ const closeInDepth = Math.abs(historyDistance - expectedDistance) <= DEPTH_TOLERANCE * expectedDistance;
+ const normalDot = normal[0] * historyNormal[0] + normal[1] * historyNormal[1] + normal[2] * historyNormal[2];
+ return closeInDepth && normalDot >= NORMAL_AGREEMENT;
+}
+
+export const REPROJECTION_GLSL = `
+uniform vec3 uEye;
+uniform vec3 uForward;
+uniform vec3 uRight;
+uniform vec3 uAbove;
+uniform vec2 uHalfSize;
+uniform vec3 uPreviousEye;
+uniform vec3 uPreviousForward;
+uniform vec3 uPreviousRight;
+uniform vec3 uPreviousAbove;
+uniform vec2 uPreviousHalfSize;
+const float DEPTH_TOLERANCE = ${DEPTH_TOLERANCE};
+const float NORMAL_AGREEMENT = ${NORMAL_AGREEMENT};
+
+vec3 pixelRayDirection(vec2 pixelPosition, vec2 size) {
+ float screenX = (pixelPosition.x / size.x * 2.0 - 1.0) * uHalfSize.x;
+ float screenY = (1.0 - pixelPosition.y / size.y * 2.0) * uHalfSize.y;
+ return normalize(uForward + uRight * screenX + uAbove * screenY);
+}
+
+// The pixel position of a world point in the previous frame; false when it was behind the previous camera.
+bool projectToPrevious(vec3 point, vec2 size, out vec2 pixelPosition, out float distanceToEye) {
+ vec3 offset = point - uPreviousEye;
+ float alongView = dot(offset, uPreviousForward);
+ distanceToEye = length(offset);
+ pixelPosition = vec2(0.0);
+ if (!(alongView > 1e-6)) return false;
+ float screenX = dot(offset, uPreviousRight) / alongView / uPreviousHalfSize.x;
+ float screenY = dot(offset, uPreviousAbove) / alongView / uPreviousHalfSize.y;
+ pixelPosition = vec2(screenX * 0.5 + 0.5, 0.5 - screenY * 0.5) * size;
+ return true;
+}
+
+bool isHistoryConsistent(float expectedDistance, float historyDistance, vec3 normal, vec3 historyNormal) {
+ return abs(historyDistance - expectedDistance) <= DEPTH_TOLERANCE * expectedDistance && dot(normal, historyNormal) >= NORMAL_AGREEMENT;
+}
+`;
+
+/** Uploads the current and previous camera to a pass that includes REPROJECTION_GLSL (the pass is the one in use). */
+export function uploadCameraPair(gl, locate, camera, previousCamera) {
+ gl.uniform3fv(locate('uEye'), camera.eye);
+ gl.uniform3fv(locate('uForward'), camera.forward);
+ gl.uniform3fv(locate('uRight'), camera.right);
+ gl.uniform3fv(locate('uAbove'), camera.above);
+ gl.uniform2f(locate('uHalfSize'), camera.halfWidth, camera.halfHeight);
+ gl.uniform3fv(locate('uPreviousEye'), previousCamera.eye);
+ gl.uniform3fv(locate('uPreviousForward'), previousCamera.forward);
+ gl.uniform3fv(locate('uPreviousRight'), previousCamera.right);
+ gl.uniform3fv(locate('uPreviousAbove'), previousCamera.above);
+ gl.uniform2f(locate('uPreviousHalfSize'), previousCamera.halfWidth, previousCamera.halfHeight);
+}
diff --git a/src/path-tracer-temporal-denoise.js b/src/path-tracer-temporal-denoise.js
new file mode 100644
index 00000000..6357a532
--- /dev/null
+++ b/src/path-tracer-temporal-denoise.js
@@ -0,0 +1,323 @@
+import { REPROJECTION_GLSL, uploadCameraPair } from './path-tracer-reprojection.js';
+import { bindInput, createFloatTexture, createFramebuffer, createPass, drawFullscreen, FRAGMENT_HEADER } from './path-tracer-realtime-gl.js';
+
+// The temporal denoiser of the real-time path tracer (issue #624), after SVGF (Schied et al. 2017). One noisy sample per
+// pixel comes in at the tracing size (half the output) with its albedo, normal and distance; three steps follow:
+// 1. accumulate: the light is divided by the albedo (so texture detail stays out of the filter), reprojected history is
+// blended in where depth and normal agree, and a variance comes from the history of the luminance (or, for a pixel
+// with a short history, from its 3 by 3 neighbours);
+// 2. a few edge-stopping a-trous passes with steps 1, 2, 4, 8 (weights from distance to the plane, normal and the
+// luminance relative to the standard deviation);
+// 3. present: 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 (jittered camera rays average the edges' anti-aliasing there), tone
+// mapped (ACES, gamma 2.2, as `toneMapToRgba8`) and drawn to the canvas.
+// Motion comes from the camera alone: the scene is static, and a moving part would ghost.
+
+export const DEFAULT_HISTORY_LIMIT = 48;
+export const DEFAULT_FILTER_ITERATIONS = 4;
+const MINIMUM_ALBEDO = 0.02;
+const SPATIAL_VARIANCE_HISTORY = 4;
+const FIREFLY_DEVIATIONS = 2.5;
+const SHORT_HISTORY_LENGTH = 8;
+
+const LUMINANCE_GLSL = `
+float luminanceOf(vec3 color) {
+ return dot(color, vec3(0.2126, 0.7152, 0.0722));
+}
+float distanceOf(vec4 radianceAndDistance, float farDistance) {
+ return radianceAndDistance.a > 0.0 ? radianceAndDistance.a : farDistance;
+}
+`;
+
+const ACCUMULATE_FRAGMENT = `${FRAGMENT_HEADER}
+${REPROJECTION_GLSL}
+${LUMINANCE_GLSL}
+uniform sampler2D uRadiance;
+uniform sampler2D uAlbedo;
+uniform sampler2D uNormal;
+uniform sampler2D uPreviousRadiance;
+uniform sampler2D uPreviousNormal;
+uniform sampler2D uHistoryColor;
+uniform sampler2D uHistoryMoments;
+uniform sampler2D uHistoryAlbedo;
+uniform ivec2 uTraceSize;
+uniform bool uResetHistory;
+uniform float uFarDistance;
+uniform float uHistoryLimit;
+const float FIREFLY_DEVIATIONS = ${FIREFLY_DEVIATIONS};
+const float SHORT_HISTORY_LENGTH = ${SHORT_HISTORY_LENGTH}.0;
+layout(location = 0) out vec4 outColor;
+layout(location = 1) out vec4 outMoments;
+layout(location = 2) out vec4 outAlbedo;
+layout(location = 3) out vec4 outFilter;
+
+vec3 illuminationAt(ivec2 texel) {
+ ivec2 clamped = clamp(texel, ivec2(0), uTraceSize - 1);
+ return texelFetch(uRadiance, clamped, 0).rgb / max(texelFetch(uAlbedo, clamped, 0).rgb, vec3(${MINIMUM_ALBEDO}));
+}
+
+void main() {
+ ivec2 texel = ivec2(gl_FragCoord.xy);
+ vec4 traced = texelFetch(uRadiance, texel, 0);
+ vec3 albedo = texelFetch(uAlbedo, texel, 0).rgb;
+ vec3 normal = texelFetch(uNormal, texel, 0).rgb;
+ vec3 illumination = traced.rgb / max(albedo, vec3(${MINIMUM_ALBEDO}));
+ vec2 size = vec2(uTraceSize);
+ float distanceToEye = distanceOf(traced, uFarDistance);
+ vec3 point = uEye + pixelRayDirection(vec2(texel) + 0.5, size) * distanceToEye;
+
+ vec4 history = vec4(0.0);
+ vec4 historyMoments = vec4(0.0);
+ vec3 historyAlbedo = vec3(0.0);
+ float totalWeight = 0.0;
+ vec2 previousPosition;
+ float previousDistance;
+ if (!uResetHistory && projectToPrevious(point, size, previousPosition, previousDistance)) {
+ vec2 base = floor(previousPosition - 0.5);
+ vec2 fraction = previousPosition - 0.5 - base;
+ for (int tap = 0; tap < 4; tap++) {
+ ivec2 offset = ivec2(tap & 1, tap >> 1);
+ ivec2 historyTexel = ivec2(base) + offset;
+ if (any(lessThan(historyTexel, ivec2(0))) || any(greaterThanEqual(historyTexel, uTraceSize))) continue;
+ float weight = (offset.x == 1 ? fraction.x : 1.0 - fraction.x) * (offset.y == 1 ? fraction.y : 1.0 - fraction.y);
+ float historyDistance = distanceOf(texelFetch(uPreviousRadiance, historyTexel, 0), uFarDistance);
+ if (!isHistoryConsistent(previousDistance, historyDistance, normal, texelFetch(uPreviousNormal, historyTexel, 0).rgb)) continue;
+ history += weight * texelFetch(uHistoryColor, historyTexel, 0);
+ historyMoments += weight * texelFetch(uHistoryMoments, historyTexel, 0);
+ historyAlbedo += weight * texelFetch(uHistoryAlbedo, historyTexel, 0).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.
+ float neighbourSum = 0.0;
+ float neighbourSumOfSquares = 0.0;
+ for (int offsetY = -1; offsetY <= 1; offsetY++) {
+ for (int offsetX = -1; offsetX <= 1; offsetX++) {
+ if (offsetX == 0 && offsetY == 0) continue;
+ float neighbour = luminanceOf(illuminationAt(texel + ivec2(offsetX, offsetY)));
+ neighbourSum += neighbour;
+ neighbourSumOfSquares += neighbour * neighbour;
+ }
+ }
+ float neighbourMean = neighbourSum / 8.0;
+ float neighbourDeviation = sqrt(max(0.0, neighbourSumOfSquares / 8.0 - neighbourMean * neighbourMean));
+ float luminanceLimit = neighbourMean * 1.05 + FIREFLY_DEVIATIONS * neighbourDeviation + 0.01;
+ float luminance = luminanceOf(illumination);
+ bool shortHistory = totalWeight <= 1e-3 || history.a < SHORT_HISTORY_LENGTH;
+ if (shortHistory && luminance > luminanceLimit) {
+ illumination *= luminanceLimit / luminance;
+ luminance = luminanceLimit;
+ }
+ vec2 currentMoments = vec2(luminance, luminance * luminance);
+ vec3 color = illumination;
+ vec3 blendedAlbedo = albedo;
+ vec2 moments = currentMoments;
+ float historyLength = 1.0;
+ if (totalWeight > 1e-3) {
+ history /= totalWeight;
+ historyMoments /= totalWeight;
+ historyAlbedo /= totalWeight;
+ historyLength = min(history.a + 1.0, uHistoryLimit);
+ float blend = 1.0 / historyLength;
+ color = mix(history.rgb, illumination, blend);
+ blendedAlbedo = mix(historyAlbedo, albedo, blend);
+ moments = mix(historyMoments.xy, currentMoments, blend);
+ }
+ float variance = max(0.0, moments.y - moments.x * moments.x);
+ if (historyLength < ${SPATIAL_VARIANCE_HISTORY}.0) {
+ float sum = neighbourSum + luminance;
+ float sumOfSquares = neighbourSumOfSquares + luminance * luminance;
+ variance = max(0.0, sumOfSquares / 9.0 - (sum / 9.0) * (sum / 9.0));
+ }
+ outColor = vec4(color, historyLength);
+ outMoments = vec4(moments, variance, 0.0);
+ outAlbedo = vec4(blendedAlbedo, 1.0);
+ outFilter = vec4(color, variance);
+}`;
+
+const ATROUS_FRAGMENT = `${FRAGMENT_HEADER}
+${REPROJECTION_GLSL}
+${LUMINANCE_GLSL}
+uniform sampler2D uFilter;
+uniform sampler2D uRadiance;
+uniform sampler2D uNormal;
+uniform ivec2 uTraceSize;
+uniform int uStep;
+uniform float uFarDistance;
+out vec4 outFilter;
+
+const float KERNEL[3] = float[3](0.375, 0.25, 0.0625);
+const float PLANE_SIGMA = 0.02;
+const float LUMINANCE_SIGMA = 4.0;
+const float NORMAL_POWER = 64.0;
+
+void main() {
+ ivec2 texel = ivec2(gl_FragCoord.xy);
+ vec2 size = vec2(uTraceSize);
+ vec4 center = texelFetch(uFilter, texel, 0);
+ vec3 centerNormal = texelFetch(uNormal, texel, 0).rgb;
+ float centerDistance = distanceOf(texelFetch(uRadiance, texel, 0), uFarDistance);
+ vec3 centerPoint = pixelRayDirection(vec2(texel) + 0.5, size) * centerDistance;
+ float centerLuminance = luminanceOf(center.rgb);
+ float smoothedVariance = 0.0;
+ for (int offsetY = -1; offsetY <= 1; offsetY++) {
+ for (int offsetX = -1; offsetX <= 1; offsetX++) {
+ ivec2 neighbour = clamp(texel + ivec2(offsetX, offsetY), ivec2(0), uTraceSize - 1);
+ smoothedVariance += texelFetch(uFilter, neighbour, 0).a * (offsetX == 0 ? 0.5 : 0.25) * (offsetY == 0 ? 0.5 : 0.25);
+ }
+ }
+ float luminanceScale = LUMINANCE_SIGMA * sqrt(max(smoothedVariance, 0.0)) + 1e-4;
+
+ vec3 sumColor = vec3(0.0);
+ float sumVariance = 0.0;
+ float sumWeight = 0.0;
+ for (int offsetY = -2; offsetY <= 2; offsetY++) {
+ for (int offsetX = -2; offsetX <= 2; offsetX++) {
+ ivec2 neighbour = texel + ivec2(offsetX, offsetY) * uStep;
+ if (any(lessThan(neighbour, ivec2(0))) || any(greaterThanEqual(neighbour, uTraceSize))) continue;
+ vec4 value = texelFetch(uFilter, neighbour, 0);
+ float neighbourDistance = distanceOf(texelFetch(uRadiance, neighbour, 0), uFarDistance);
+ vec3 neighbourPoint = pixelRayDirection(vec2(neighbour) + 0.5, size) * neighbourDistance;
+ float planeDistance = abs(dot(centerNormal, neighbourPoint - centerPoint));
+ float planeWeight = exp(-planeDistance / (PLANE_SIGMA * centerDistance));
+ float normalWeight = pow(max(dot(centerNormal, texelFetch(uNormal, neighbour, 0).rgb), 0.0), NORMAL_POWER);
+ float luminanceWeight = exp(-abs(luminanceOf(value.rgb) - centerLuminance) / luminanceScale);
+ float weight = KERNEL[abs(offsetX)] * KERNEL[abs(offsetY)] * planeWeight * normalWeight * luminanceWeight;
+ sumColor += weight * value.rgb;
+ sumVariance += weight * weight * value.a;
+ sumWeight += weight;
+ }
+ }
+ outFilter = sumWeight > 1e-6 ? vec4(sumColor / sumWeight, sumVariance / (sumWeight * sumWeight)) : center;
+}`;
+
+const PRESENT_FRAGMENT = `${FRAGMENT_HEADER}
+${LUMINANCE_GLSL}
+uniform sampler2D uFilter;
+uniform sampler2D uAlbedoHistory;
+uniform sampler2D uRadiance;
+uniform sampler2D uNormal;
+uniform ivec2 uTraceSize;
+uniform ivec2 uOutputSize;
+uniform float uFarDistance;
+out vec4 outColor;
+
+vec3 toneMap(vec3 linear) {
+ vec3 color = max(linear, vec3(0.0));
+ vec3 mapped = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), 0.0, 1.0);
+ return pow(mapped, vec3(1.0 / 2.2));
+}
+
+void main() {
+ vec2 outputPixel = vec2(gl_FragCoord.x, float(uOutputSize.y) - gl_FragCoord.y);
+ vec2 position = outputPixel / vec2(uOutputSize) * vec2(uTraceSize);
+ ivec2 nearest = clamp(ivec2(floor(position)), ivec2(0), uTraceSize - 1);
+ float nearestDistance = distanceOf(texelFetch(uRadiance, nearest, 0), uFarDistance);
+ vec3 nearestNormal = texelFetch(uNormal, nearest, 0).rgb;
+ vec2 base = floor(position - 0.5);
+ vec2 fraction = position - 0.5 - base;
+ vec3 illumination = vec3(0.0);
+ vec3 albedo = vec3(0.0);
+ float totalWeight = 0.0;
+ for (int tap = 0; tap < 4; tap++) {
+ ivec2 offset = ivec2(tap & 1, tap >> 1);
+ ivec2 texel = clamp(ivec2(base) + offset, ivec2(0), uTraceSize - 1);
+ float weight = (offset.x == 1 ? fraction.x : 1.0 - fraction.x) * (offset.y == 1 ? fraction.y : 1.0 - fraction.y);
+ float distanceDifference = abs(distanceOf(texelFetch(uRadiance, texel, 0), uFarDistance) - nearestDistance);
+ weight *= exp(-distanceDifference / (0.02 * nearestDistance));
+ weight *= pow(max(dot(nearestNormal, texelFetch(uNormal, texel, 0).rgb), 0.0), 16.0);
+ illumination += weight * texelFetch(uFilter, texel, 0).rgb;
+ albedo += weight * texelFetch(uAlbedoHistory, texel, 0).rgb;
+ totalWeight += weight;
+ }
+ if (totalWeight < 1e-5) {
+ illumination = texelFetch(uFilter, nearest, 0).rgb;
+ albedo = texelFetch(uAlbedoHistory, nearest, 0).rgb;
+ totalWeight = 1.0;
+ }
+ vec3 light = illumination / totalWeight;
+ vec3 surface = albedo / totalWeight;
+ outColor = vec4(toneMap(light * max(surface, vec3(${MINIMUM_ALBEDO}))), 1.0);
+}`;
+
+/**
+ * Creates the denoiser for a tracing size and an output size. `run` takes the textures of the frame just traced and the
+ * one before it and draws the result to the default framebuffer (the canvas).
+ */
+export function createTemporalDenoiser(gl, { traceWidth, traceHeight, outputWidth, outputHeight, historyLimit = DEFAULT_HISTORY_LIMIT, filterIterations = DEFAULT_FILTER_ITERATIONS }) {
+ const accumulatePass = createPass(gl, ACCUMULATE_FRAGMENT);
+ const atrousPass = createPass(gl, ATROUS_FRAGMENT);
+ const presentPass = createPass(gl, PRESENT_FRAGMENT);
+ const makePair = () => [createFloatTexture(gl, traceWidth, traceHeight), createFloatTexture(gl, traceWidth, traceHeight)];
+ const colors = makePair();
+ const moments = makePair();
+ const albedos = makePair();
+ const filters = makePair();
+ const accumulateFramebuffers = [0, 1].map(index => createFramebuffer(gl, [
+ { slot: 0, texture: colors[index] }, { slot: 1, texture: moments[index] }, { slot: 2, texture: albedos[index] }, { slot: 3, texture: filters[0] },
+ ]));
+ const filterFramebuffers = filters.map(texture => createFramebuffer(gl, [{ slot: 0, texture }]));
+ let current = 0;
+
+ const bindGuides = (pass, inputs) => {
+ bindInput(gl, pass, 'uRadiance', 0, inputs.radiance);
+ bindInput(gl, pass, 'uNormal', 1, inputs.normal);
+ gl.uniform2i(pass.locate('uTraceSize'), traceWidth, traceHeight);
+ gl.uniform1f(pass.locate('uFarDistance'), inputs.farDistance);
+ };
+
+ const accumulate = (inputs) => {
+ const previous = 1 - current;
+ gl.useProgram(accumulatePass.program);
+ bindGuides(accumulatePass, inputs);
+ bindInput(gl, accumulatePass, 'uAlbedo', 2, inputs.albedo);
+ bindInput(gl, accumulatePass, 'uPreviousRadiance', 3, inputs.previousRadiance);
+ bindInput(gl, accumulatePass, 'uPreviousNormal', 4, inputs.previousNormal);
+ bindInput(gl, accumulatePass, 'uHistoryColor', 5, colors[previous]);
+ bindInput(gl, accumulatePass, 'uHistoryMoments', 6, moments[previous]);
+ bindInput(gl, accumulatePass, 'uHistoryAlbedo', 7, albedos[previous]);
+ uploadCameraPair(gl, accumulatePass.locate, inputs.camera, inputs.previousCamera);
+ gl.uniform1i(accumulatePass.locate('uResetHistory'), inputs.resetHistory ? 1 : 0);
+ gl.uniform1f(accumulatePass.locate('uHistoryLimit'), historyLimit);
+ drawFullscreen(gl, accumulateFramebuffers[current], traceWidth, traceHeight);
+ };
+
+ const filter = (inputs) => {
+ gl.useProgram(atrousPass.program);
+ bindGuides(atrousPass, inputs);
+ uploadCameraPair(gl, atrousPass.locate, inputs.camera, inputs.previousCamera);
+ let source = 0;
+ for (let iteration = 0; iteration < filterIterations; iteration++) {
+ bindInput(gl, atrousPass, 'uFilter', 2, filters[source]);
+ gl.uniform1i(atrousPass.locate('uStep'), 1 << iteration);
+ drawFullscreen(gl, filterFramebuffers[1 - source], traceWidth, traceHeight);
+ source = 1 - source;
+ }
+ return filters[source];
+ };
+
+ const present = (inputs, filtered) => {
+ gl.useProgram(presentPass.program);
+ bindGuides(presentPass, inputs);
+ bindInput(gl, presentPass, 'uFilter', 2, filtered);
+ bindInput(gl, presentPass, 'uAlbedoHistory', 3, albedos[current]);
+ gl.uniform2i(presentPass.locate('uOutputSize'), outputWidth, outputHeight);
+ drawFullscreen(gl, null, outputWidth, outputHeight);
+ };
+
+ return {
+ run(inputs) {
+ accumulate(inputs);
+ const filtered = filter(inputs);
+ present(inputs, filtered);
+ current = 1 - current;
+ },
+ dispose() {
+ for (const texture of [...colors, ...moments, ...albedos, ...filters]) gl.deleteTexture(texture);
+ for (const framebuffer of [...accumulateFramebuffers, ...filterFramebuffers]) gl.deleteFramebuffer(framebuffer);
+ for (const pass of [accumulatePass, atrousPass, presentPass]) gl.deleteProgram(pass.program);
+ },
+ };
+}
diff --git a/tests/path-tracer-radiance-cache.test.js b/tests/path-tracer-radiance-cache.test.js
new file mode 100644
index 00000000..e6f83618
--- /dev/null
+++ b/tests/path-tracer-radiance-cache.test.js
@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { CACHE_HISTORY_LIMIT, CACHE_SLOT_COUNT, cacheLevel, cacheSlot, mergeCell } from '../src/path-tracer-radiance-cache.js';
+import { buildFragmentSource } from '../src/path-tracer-gpu-shader.js';
+
+const EYE = [0, 1.5, 6];
+const CELL_SIZE = 0.1;
+const LEVEL_DISTANCE = 6.4;
+const slotOf = (point, normal = [0, 1, 0], eye = EYE) => cacheSlot({ point, normal, eye, cellSize: CELL_SIZE, levelDistance: LEVEL_DISTANCE });
+
+test('a point and a nearby point of the same cell share a slot, and the slot is stable', () => {
+ const slot = slotOf([1.23, 0, -0.41]);
+ assert.equal(slotOf([1.23, 0, -0.41]), slot);
+ assert.equal(slotOf([1.2301, 0.0001, -0.4099]), slot);
+ assert.ok(slot >= 0 && slot < CACHE_SLOT_COUNT);
+});
+
+test('cells far apart and surfaces facing opposite ways get different slots', () => {
+ const slot = slotOf([1.23, 0, -0.41]);
+ assert.notEqual(slotOf([1.53, 0, -0.41]), slot);
+ assert.notEqual(slotOf([1.23, 0, -0.41], [0, -1, 0]), slot);
+ assert.notEqual(slotOf([1.23, 0, -0.41], [1, 0, 0]), slot);
+});
+
+test('a normal that wobbles around an axis stays in one cell', () => {
+ const slot = slotOf([0.5, 0, 0.5], [0, 1, 0]);
+ assert.equal(slotOf([0.5, 0, 0.5], [0.1, 0.99, -0.05]), slot);
+});
+
+test('cells grow with the distance from the eye, one level each time the distance doubles', () => {
+ assert.equal(cacheLevel(1, LEVEL_DISTANCE), 0);
+ assert.equal(cacheLevel(LEVEL_DISTANCE * 1.9, LEVEL_DISTANCE), 0);
+ assert.equal(cacheLevel(LEVEL_DISTANCE * 2, LEVEL_DISTANCE), 1);
+ assert.equal(cacheLevel(LEVEL_DISTANCE * 4.5, LEVEL_DISTANCE), 2);
+ assert.equal(cacheLevel(1e9, LEVEL_DISTANCE), 8);
+ const farEye = [0, 1.5, 40];
+ assert.equal(slotOf([0, 0, 0], [0, 1, 0], farEye), slotOf([0.15, 0, 0.1], [0, 1, 0], farEye));
+ assert.notEqual(slotOf([0, 0, 0]), slotOf([0.15, 0, 0.1]));
+});
+
+test('the hash spreads cells evenly over the slots', () => {
+ const buckets = new Uint32Array(64);
+ let count = 0;
+ for (let x = 0; x < 60; x++) {
+ for (let z = 0; z < 60; z++) {
+ for (let y = 0; y < 30; y++) {
+ buckets[slotOf([(x + 0.5) * CELL_SIZE, (y + 0.5) * CELL_SIZE, (z + 0.5) * CELL_SIZE]) % 64]++;
+ count++;
+ }
+ }
+ }
+ const expected = count / 64;
+ for (const bucket of buckets) assert.ok(Math.abs(bucket - expected) < expected * 0.1, `bucket ${bucket} against ${expected}`);
+});
+
+test('few cells collide at the size a room needs', () => {
+ const seen = new Set();
+ let cells = 0;
+ for (let x = 0; x < 50; x++) {
+ for (let z = 0; z < 50; z++) {
+ for (const normal of [[0, 1, 0], [0, -1, 0], [1, 0, 0]]) {
+ seen.add(slotOf([(x + 0.5) * CELL_SIZE, 0.05, (z + 0.5) * CELL_SIZE], normal));
+ cells++;
+ }
+ }
+ }
+ assert.ok((cells - seen.size) / cells < 0.01, `${cells - seen.size} of ${cells} cells collided`);
+});
+
+test('a cell averages the records it receives, quickly while it is new and slowly once it has history', () => {
+ const fresh = mergeCell({ previousMean: [0, 0, 0], previousCount: 0, mean: [2, 4, 6], count: 4 });
+ assert.deepEqual(fresh.mean, [2, 4, 6]);
+ assert.equal(fresh.count, 4);
+ const settled = mergeCell({ previousMean: [1, 1, 1], previousCount: 10000, mean: [3, 3, 3], count: 1 });
+ assert.ok(Math.abs(settled.mean[0] - (1 + 2 / (CACHE_HISTORY_LIMIT + 1))) < 1e-12);
+ assert.deepEqual(mergeCell({ previousMean: [1, 2, 3], previousCount: 7, mean: [9, 9, 9], count: 0 }), { mean: [1, 2, 3], count: 7 });
+});
+
+test('the kernel gets the cache only when it is asked for', () => {
+ const plain = buildFragmentSource();
+ const cached = buildFragmentSource({ radianceCache: true });
+ for (const name of ['outCacheUpdate', 'uRadianceCache', 'cacheLookup', 'cacheHash']) {
+ assert.ok(!plain.includes(name), `${name} in the plain kernel`);
+ assert.ok(cached.includes(name), `${name} missing from the cached kernel`);
+ }
+ assert.equal(buildFragmentSource({ radianceCache: false }), plain);
+});
diff --git a/tests/path-tracer-reprojection.test.js b/tests/path-tracer-reprojection.test.js
new file mode 100644
index 00000000..cc64b1e5
--- /dev/null
+++ b/tests/path-tracer-reprojection.test.js
@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createCamera } from '../src/path-tracer.js';
+import { bilinearTaps, isHistoryConsistent, motionVector, pixelRayDirection, projectToPixel } from '../src/path-tracer-reprojection.js';
+
+const WIDTH = 480;
+const HEIGHT = 270;
+const camera = createCamera({ eye: [0, 1.5, 6], target: [0, 1.2, 0], fov: 50 }, WIDTH, HEIGHT);
+const pointAt = (pixelX, pixelY, distance, view = camera) => {
+ const direction = pixelRayDirection(view, pixelX, pixelY, WIDTH, HEIGHT);
+ return direction.map((component, axis) => view.eye[axis] + component * distance);
+};
+
+test('a point seen through a pixel projects back to that pixel with its eye distance', () => {
+ for (const [pixelX, pixelY, distance] of [[240.5, 135.5, 6], [10.25, 20.75, 3], [470.5, 260.5, 12]]) {
+ const projected = projectToPixel(camera, pointAt(pixelX, pixelY, distance), WIDTH, HEIGHT);
+ assert.ok(Math.abs(projected.x - pixelX) < 1e-6 && Math.abs(projected.y - pixelY) < 1e-6);
+ assert.ok(Math.abs(projected.distance - distance) < 1e-9);
+ }
+});
+
+test('the picture centre is where the camera looks, and up is toward row 0', () => {
+ const target = [0, 1.2, 0];
+ const centre = projectToPixel(camera, target, WIDTH, HEIGHT);
+ assert.ok(Math.abs(centre.x - WIDTH / 2) < 1e-6 && Math.abs(centre.y - HEIGHT / 2) < 1e-6);
+ const above = projectToPixel(camera, [0, 2.2, 0], WIDTH, HEIGHT);
+ assert.ok(above.y < centre.y);
+});
+
+test('a resting camera gives a zero motion vector', () => {
+ const vector = motionVector(camera, camera, 100.5, 50.5, 4, WIDTH, HEIGHT);
+ assert.ok(Math.abs(vector.x) < 1e-6 && Math.abs(vector.y) < 1e-6);
+});
+
+test('a camera that moves right sees a near surface move left (vector toward this frame), more than a far one', () => {
+ const moved = createCamera({ eye: [0.2, 1.5, 6], target: [0.2, 1.2, 0], fov: 50 }, WIDTH, HEIGHT);
+ const near = motionVector(moved, camera, 240.5, 135.5, 2, WIDTH, HEIGHT);
+ const far = motionVector(moved, camera, 240.5, 135.5, 20, WIDTH, HEIGHT);
+ assert.ok(near.x < 0 && far.x < 0, 'the surface was further to the right in the previous frame, so the vector toward this frame points left');
+ assert.ok(near.x < far.x);
+ assert.ok(Math.abs(near.y) < 1e-3);
+});
+
+test('a camera that turns moves every surface by the same amount whatever its distance', () => {
+ const turned = createCamera({ eye: [0, 1.5, 6], target: [1, 1.2, 0], fov: 50 }, WIDTH, HEIGHT);
+ const near = motionVector(turned, camera, 240.5, 135.5, 2, WIDTH, HEIGHT);
+ const far = motionVector(turned, camera, 240.5, 135.5, 50, WIDTH, HEIGHT);
+ assert.ok(Math.abs(near.x - far.x) < 1e-6);
+ assert.ok(Math.abs(near.x) > 10);
+});
+
+test('a point behind the previous camera has no history', () => {
+ const behind = createCamera({ eye: [0, 1.5, 6], target: [0, 1.5, 12], fov: 50 }, WIDTH, HEIGHT);
+ assert.equal(projectToPixel(behind, [0, 1.2, 0], WIDTH, HEIGHT), null);
+ assert.equal(motionVector(camera, behind, 240.5, 135.5, 4, WIDTH, HEIGHT), null);
+});
+
+test('bilinear taps add up to one and fall on the pixel centres around the position', () => {
+ const taps = bilinearTaps(10.25, 20.75);
+ assert.ok(Math.abs(taps.reduce((sum, tap) => sum + tap.weight, 0) - 1) < 1e-12);
+ assert.deepEqual(taps.map(tap => [tap.column, tap.row]), [[9, 20], [10, 20], [9, 21], [10, 21]]);
+ const centred = bilinearTaps(10.5, 20.5);
+ assert.deepEqual(centred.map(tap => tap.weight), [1, 0, 0, 0]);
+});
+
+test('history is rejected across a depth jump or a turned surface and accepted along a slope', () => {
+ const flat = [0, 1, 0];
+ const base = { expectedDistance: 5, historyDistance: 5.1, normal: flat, historyNormal: flat };
+ assert.equal(isHistoryConsistent(base), true);
+ assert.equal(isHistoryConsistent({ ...base, historyDistance: 7 }), false, 'a surface two units behind is a disocclusion');
+ assert.equal(isHistoryConsistent({ ...base, historyNormal: [1, 0, 0] }), false);
+ assert.equal(isHistoryConsistent({ ...base, historyNormal: [0.2, 0.98, 0] }), true);
+});
diff --git a/vite.lib.config.js b/vite.lib.config.js
index ea058746..2ec53f60 100644
--- a/vite.lib.config.js
+++ b/vite.lib.config.js
@@ -75,6 +75,7 @@ export default defineConfig({
'floor-sky-visibility': 'src/floor-sky-visibility.js',
'path-tracer': 'src/path-tracer.js',
'path-tracer-progressive': 'src/path-tracer-progressive.js',
+ 'path-tracer-realtime': 'src/path-tracer-realtime.js',
'path-tracer-worker': 'src/path-tracer-worker.js',
'kernel-worker': 'src/kernel-worker.js',
'texture-set': 'src/texture-set.js',