Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Trace local volume noise in the CPU path tracer (#808)

Nguyen Xuan Andb717fca2249
diff --git a/changes/808-volume-noise-pt.md b/changes/808-volume-noise-pt.md
new file mode 100644
index 00000000..03f8fbb1
--- /dev/null
+++ b/changes/808-volume-noise-pt.md
@@ -0,0 +1 @@
+- Local volumes with `noiseAmount` now draw the same noise field in the CPU path tracer as in the rasterizer, whose noise moved to a hash that rounds the same on every GPU; the WebGL, WebGPU and progressive tracers still refuse local volumes, with a test each (#808)
diff --git a/changes/808-volume-noise-pt.size.md b/changes/808-volume-noise-pt.size.md
new file mode 100644
index 00000000..3b05f302
--- /dev/null
+++ b/changes/808-volume-noise-pt.size.md
@@ -0,0 +1,2 @@
+- scene:agent-scene+lazy: 219 bytes gzip for a second value noise in the local volume shader and its CPU port, so the rasterizer and the path tracer draw one noisy volume instead of two different clouds; the fog's sine hash cannot be reused because a GPU's sine error changes the pattern
+- goal:agent-scene: 26 bytes gzip, the CPU path tracer's noise port, which makes a noisy local volume match between renderers (worst region difference 0.003)
diff --git a/docs/volumetric.md b/docs/volumetric.md
index fcde5670..5df9bba1 100644
--- a/docs/volumetric.md
+++ b/docs/volumetric.md
@@ -125,10 +125,10 @@ In a scene with an irradiance grid (`bake.irradianceGrid`) the bounce term is th
| `absorption` | `[1, 1, 1]` | Per colour channel share of the density, `0` to `1`. A larger value dims that channel more, so `[0.1, 0.6, 1]` removes blue first and leaves a warm tint |
| `emission`, `emissionStrength` | `[0, 0, 0]`, `1` | Glow colour and its radiance per unit length at the core, `0` to `1000`. Emission does not depend on `density`, so `density: 0` is a pure glow |
| `falloff` | `0.5` | `0` to `1`. The outer share of the volume over which the density fades to zero (`0` is a hard edge) |
-| `noiseAmount`, `noiseScale` | `0`, `1` | Raster only. `noiseAmount` `0` to `1` breaks the density up with the cloud noise at `noiseScale` cells per unit |
+| `noiseAmount`, `noiseScale` | `0`, `1` | `noiseAmount` `0` to `1` breaks the density up with value noise at `noiseScale` cells per unit: the profile is multiplied by `mix(1, 2 * noise, noiseAmount)`. The rasterizer and the CPU path tracer read the same field. A `fit: "mesh"` volume ignores it |
| `steps` | `16` | `4` to `32` samples through the volume |
-Each volume is marched on its own between its entry and its exit, cut at the first surface, and the volumes are composited nearest entry first. Overlapping volumes are therefore an approximation. Local volumes are drawn before `volumeFog`, so a fog in front of a puff also dims it. They need the same renderer as the fog (`hdr: true`, `depth: true`, an opaque canvas) and are drawn in the post pass, so they are not in the lightmap bake: a scene bake (`bake` in a recipe) leaves them out, an emissive volume lights no baked surface and no volume dims the baked light, and the bake report names them in `skippedLocalVolumes` (index, shape, whether emissive) with a `warnings` line. A scene without local volumes bakes and reports exactly as before. Add a point light or an emissive part where the volume's glow should reach a wall. The path tracer traces them on `backend: "cpu"` with the same fields except the noise, and every other tracer entry point (backends `gpu` and `native`, the progressive and realtime tracers, the GPU light bake) throws instead of leaving them out. Cost grows with the covered pixels times `steps` times the number of volumes that the pixel's ray crosses; a ray that misses every volume pays only the interval test.
+Each volume is marched on its own between its entry and its exit, cut at the first surface, and the volumes are composited nearest entry first. Overlapping volumes are therefore an approximation. Local volumes are drawn before `volumeFog`, so a fog in front of a puff also dims it. They need the same renderer as the fog (`hdr: true`, `depth: true`, an opaque canvas) and are drawn in the post pass, so they are not in the lightmap bake: a scene bake (`bake` in a recipe) leaves them out, an emissive volume lights no baked surface and no volume dims the baked light, and the bake report names them in `skippedLocalVolumes` (index, shape, whether emissive) with a `warnings` line. A scene without local volumes bakes and reports exactly as before. Add a point light or an emissive part where the volume's glow should reach a wall. The path tracer traces them on `backend: "cpu"` with the same fields, noise included, and every other tracer entry point (backends `gpu`, `webgpu` and `native`, the progressive and both realtime tracers, the GPU light bake) throws `environment.localVolumes is traced by the CPU path tracer only` instead of leaving them out. The GPU tracers are refused, not ported: each would need a second march loop in its kernel and a volume table in every pack, for a feature the CPU tracer already draws. Cost grows with the covered pixels times `steps` times the number of volumes that the pixel's ray crosses; a ray that misses every volume pays only the interval test.
### Mesh volumes
@@ -152,4 +152,4 @@ Each volume is marched on its own between its entry and its exit, cut at the fir
### Not covered yet
-The WebGPU and WebGL path tracers and path tracer noise are open work: tracer noise and GPU tracers #808. Lighting baked surfaces from a volume's emission is not planned (#809): the bake reports the limit instead.
+The noise is `localVolumeNoise` in `src/fog-shader.js` and `src/local-volume-noise.js`: trilinear value noise on a hash made of multiplies, adds and `fract` only, which every GPU rounds the same way. The fog's `cloudNoise` hashes with `sin`, whose error grows with its argument: on SwiftShader its lattice values differed from a 32-bit JavaScript port by up to 0.3, so the two renderers drew different clouds. The JavaScript port rounds every step to 32 bits. `tests/local-volume-noise.test.js` draws a noisy box (`density` 1.2, `falloff` 0.3, `noiseAmount` 0.9, `noiseScale` 3) in both renderers and compares the light let through in 8 by 8 regions: on SwiftShader the worst region differed by 0.003 and the mean of the whole frame by 0.0008, and the test allows 0.01 and 0.005. The rasterizer jitters each pixel's steps with a hash and the tracer with its sampler, so single pixels differ by a few percent. Volumes with `noiseAmount` drew with the fog's sine noise before this change, so their pattern moved; the mean density is unchanged. Lighting baked surfaces from a volume's emission is not planned (#809): the bake reports the limit instead.
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index 6d62a42e..868f2470 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -271,7 +271,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
maxSpotLights: MAX_SPOT_LIGHTS, maxAreaLights: MAX_AREA_LIGHTS,
localShadows: Object.freeze({ lights: Object.freeze(['pointLights', 'spotLights']), atlasTiles: 24, pointLightTiles: 6, spotLightTiles: 1, tileSize: 512 }),
lightLinking: Object.freeze({ fields: Object.freeze(['environment.keyAffects', 'pointLights[].affects', 'spotLights[].affects', 'areaLights[].affects']), unlisted: 'a light without affects lights every node', unknownNode: 'rejected', bake: 'honoured', pathTracer: 'ignored, named in report.ignored' }),
- localVolumes: Object.freeze({ field: 'environment.localVolumes', maximum: 8, shapes: Object.freeze(['box', 'sphere', 'mesh']), fields: 'shape, center, size (box) or radius (sphere) or part + fit bounds|mesh (mesh: the named part, bounds by default; fit mesh fills a closed part, ignoring falloff, noise and steps), density 0-100 (1), falloff 0-1 (0.5), absorption rgb 0-1 (1,1,1), emission rgb 0-1, emissionStrength 0-1000 (1), noiseAmount 0-1 (0), noiseScale (1), steps 4-32 (16)', note: 'Absorb and emit, no scattering; needs hdr and depth like volumeFog; noise is raster only; path tracer: backend cpu only (gpu and native throw); a bake leaves them out, so an emissive volume lights no baked surface (bake report: skippedLocalVolumes, warnings).' }),
+ localVolumes: Object.freeze({ field: 'environment.localVolumes', maximum: 8, shapes: Object.freeze(['box', 'sphere', 'mesh']), fields: 'shape, center, size (box) or radius (sphere) or part + fit bounds|mesh (mesh: the named part, bounds by default; fit mesh fills a closed part, ignoring falloff, noise and steps), density 0-100 (1), falloff 0-1 (0.5), absorption rgb 0-1 (1,1,1), emission rgb 0-1, emissionStrength 0-1000 (1), noiseAmount 0-1 (0), noiseScale (1), steps 4-32 (16)', note: 'Absorb and emit, no scattering; needs hdr and depth like volumeFog; noise is the same field in the rasterizer and the CPU path tracer; path tracer: backend cpu only (gpu, webgpu and native throw); a bake leaves them out, so an emissive volume lights no baked surface (bake report: skippedLocalVolumes, warnings).' }),
shadowCascades: Object.freeze({ field: 'environment.shadowCascades', counts: Object.freeze([0, 1, 2, 3, 4]), zero: 'one shadow map', automatic: 'three cascades when shadow.extent is above 40 and the field is unset', maximumDistance: 150, note: 'volume fog and water read the single map' }),
lineArt: Object.freeze({ field: 'environment.lines', fields: 'width px 0.25-16 (1.5), color, boundaries, creaseAngle deg (35), depthJump (0.08), toon steps 0-8, polylines [{points [x,y,z] 2-256, color, width, depthTest, closed}] max 64; {} turns on, null clears; material toon 0-8', note: 'docs/line-art.md' }),
viewTransform: Object.freeze({
diff --git a/src/fog-shader.js b/src/fog-shader.js
index 44db34c8..e39d5b67 100644
--- a/src/fog-shader.js
+++ b/src/fog-shader.js
@@ -122,6 +122,21 @@ uniform highp sampler2D localMeshVolumes;
// Each volume is marched on its own between its entry and exit (cut at the first surface) and composited nearest first: the colour
// behind it is dimmed by exp(-absorption * profile * step) and its emission is added, both per colour channel.
const LOCAL_VOLUME_FUNCTIONS = `
+// Value noise on a hash of plain multiplies, adds and fract, which every GPU rounds the same way (a sine hash does not: its error
+// grows with the argument). local-volume-noise.js repeats it for the CPU path tracer, so keep the two in step.
+float localVolumeCellHash(vec3 cell) {
+ vec3 scrambled = fract(cell * 0.1031);
+ scrambled += dot(scrambled, scrambled.zyx + 31.32);
+ return fract((scrambled.x + scrambled.y) * scrambled.z);
+}
+float localVolumeNoise(vec3 position) {
+ vec3 cell = floor(position);
+ vec3 fraction = fract(position);
+ fraction = fraction * fraction * (3.0 - 2.0 * fraction);
+ float lower = mix(mix(localVolumeCellHash(cell), localVolumeCellHash(cell + vec3(1,0,0)), fraction.x), mix(localVolumeCellHash(cell + vec3(0,1,0)), localVolumeCellHash(cell + vec3(1,1,0)), fraction.x), fraction.y);
+ float upper = mix(mix(localVolumeCellHash(cell + vec3(0,0,1)), localVolumeCellHash(cell + vec3(1,0,1)), fraction.x), mix(localVolumeCellHash(cell + vec3(0,1,1)), localVolumeCellHash(cell + vec3(1,1,1)), fraction.x), fraction.y);
+ return mix(lower, upper, fraction.z);
+}
vec3 localVolumeLocal(int index, vec3 vector) {
return vec3(dot(localVolumeAxes[index * 3].xyz, vector), dot(localVolumeAxes[index * 3 + 1].xyz, vector), dot(localVolumeAxes[index * 3 + 2].xyz, vector));
}
@@ -161,7 +176,7 @@ float localVolumeProfile(int index, vec3 position) {
float falloff = localVolumeExtents[index].w;
float profile = falloff > 0.0 ? 1.0 - smoothstep(1.0 - falloff, 1.0, distanceRatio) : 1.0 - step(1.0, distanceRatio);
float noiseAmount = localVolumeAbsorption[index].w;
- if (noiseAmount > 0.0) profile *= mix(1.0, cloudNoise(position * localVolumeEmission[index].w) * 2.0, noiseAmount);
+ if (noiseAmount > 0.0) profile *= mix(1.0, localVolumeNoise(position * localVolumeEmission[index].w) * 2.0, noiseAmount);
return profile;
}
vec3 localVolumes(vec3 background) {
diff --git a/src/local-volume-noise.js b/src/local-volume-noise.js
new file mode 100644
index 00000000..a323dd66
--- /dev/null
+++ b/src/local-volume-noise.js
@@ -0,0 +1,57 @@
+// The value noise the rasterizer's post shader draws local volumes with (localVolumeNoise in fog-shader.js), written for the CPU path
+// tracer so both renderers read one field. The hash uses only multiplies, adds and fract, and every step is rounded to a 32-bit float
+// as the shader's is, so the two agree to a few float32 steps (a sine hash would not: a GPU's sine is not specified bit for bit).
+
+const round = Math.fround;
+
+const fract = value => round(value - Math.floor(value));
+
+function latticeHash(x, y, z) {
+ let scrambledX = fract(round(x * round(0.1031)));
+ let scrambledY = fract(round(y * round(0.1031)));
+ let scrambledZ = fract(round(z * round(0.1031)));
+ const offset = round(31.32);
+ const spread = round(round(round(scrambledX * round(scrambledZ + offset)) + round(scrambledY * round(scrambledY + offset))) + round(scrambledZ * round(scrambledX + offset)));
+ scrambledX = round(scrambledX + spread);
+ scrambledY = round(scrambledY + spread);
+ scrambledZ = round(scrambledZ + spread);
+ return fract(round(round(scrambledX + scrambledY) * scrambledZ));
+}
+
+function smooth(fraction) {
+ return round(round(fraction * fraction) * round(3 - round(2 * fraction)));
+}
+
+function mix(first, second, amount) {
+ return round(round(first * round(1 - amount)) + round(second * amount));
+}
+
+/** The shader's cloudNoise at a point, 0 to 1 with a mean near 0.5. */
+export function localVolumeNoise(x, y, z) {
+ const positionX = round(x);
+ const positionY = round(y);
+ const positionZ = round(z);
+ const cellX = Math.floor(positionX);
+ const cellY = Math.floor(positionY);
+ const cellZ = Math.floor(positionZ);
+ const fractionX = smooth(round(positionX - cellX));
+ const fractionY = smooth(round(positionY - cellY));
+ const fractionZ = smooth(round(positionZ - cellZ));
+ const lower = mix(
+ mix(latticeHash(cellX, cellY, cellZ), latticeHash(cellX + 1, cellY, cellZ), fractionX),
+ mix(latticeHash(cellX, cellY + 1, cellZ), latticeHash(cellX + 1, cellY + 1, cellZ), fractionX),
+ fractionY,
+ );
+ const upper = mix(
+ mix(latticeHash(cellX, cellY, cellZ + 1), latticeHash(cellX + 1, cellY, cellZ + 1), fractionX),
+ mix(latticeHash(cellX, cellY + 1, cellZ + 1), latticeHash(cellX + 1, cellY + 1, cellZ + 1), fractionX),
+ fractionY,
+ );
+ return mix(lower, upper, fractionZ);
+}
+
+/** The factor the shader multiplies the profile by: mix(1, 2 * noise(position * scale), amount). */
+export function localVolumeNoiseFactor(volume, x, y, z) {
+ const noise = localVolumeNoise(x * volume.noiseScale, y * volume.noiseScale, z * volume.noiseScale);
+ return 1 + (2 * noise - 1) * volume.noiseAmount;
+}
diff --git a/src/local-volumes.js b/src/local-volumes.js
index c9f770e6..d4daae01 100644
--- a/src/local-volumes.js
+++ b/src/local-volumes.js
@@ -1,4 +1,5 @@
import { finiteRange } from './volumetric.js';
+import { localVolumeNoiseFactor } from './local-volume-noise.js';
// Local volumes: up to MAX_LOCAL_VOLUMES boxes, spheres or parts (shape "mesh") that absorb and emit light, for candle haze, smoke puffs and glowing
// fog in one place. They sit beside environment.volumeFog (the one scattering volume) and need no fog. The post pass marches
@@ -94,7 +95,7 @@ export function packLocalVolumes(volumes, buffers) {
return buffers;
}
-/** The density factor of a volume at a point, 0 to 1, without noise: 1 at the core, fading over the outer `falloff` share. */
+/** The density factor of a volume at a point: 1 at the core, fading over the outer `falloff` share, times the noise factor (up to 2) when `noiseAmount` is above 0, as the post shader does. */
export function localVolumeProfile(volume, x, y, z) {
if (volume.shape === 'mesh') return 1;
let offsetX = x - volume.center[0];
@@ -112,9 +113,13 @@ export function localVolumeProfile(volume, x, y, z) {
? Math.hypot(offsetX, offsetY, offsetZ) / volume.radius
: Math.max(Math.abs(offsetX) / (volume.size[0] / 2), Math.abs(offsetY) / (volume.size[1] / 2), Math.abs(offsetZ) / (volume.size[2] / 2));
if (distance >= 1) return 0;
- if (volume.falloff === 0) return 1;
- const ratio = Math.min(1, Math.max(0, (distance - (1 - volume.falloff)) / volume.falloff));
- return 1 - ratio * ratio * (3 - 2 * ratio);
+ let profile = 1;
+ if (volume.falloff > 0) {
+ const ratio = Math.min(1, Math.max(0, (distance - (1 - volume.falloff)) / volume.falloff));
+ profile = 1 - ratio * ratio * (3 - 2 * ratio);
+ }
+ if (volume.noiseAmount > 0) profile *= localVolumeNoiseFactor(volume, x, y, z);
+ return profile;
}
/** Where a ray is inside a volume, as distances along it: writes `[entry, exit]` into `out`, clipped to `[0, limit]`, and returns true; false when it misses. */
diff --git a/src/path-tracer-volume.js b/src/path-tracer-volume.js
index 3e5faee8..865408d2 100644
--- a/src/path-tracer-volume.js
+++ b/src/path-tracer-volume.js
@@ -7,7 +7,7 @@ import { createTracer } from './ray-query.js';
// Homogeneous fog for the path tracer: a box of uniform scattering medium with the colour, density and anisotropy of the
// rasterizer's `environment.volumeFog`. Distances to the next scattering event are drawn from the exact free-flight
// distribution, so the cost is one random number per ray segment and there is no step count to trade against quality.
-// The rasterizer's noise, drift and ambient term are not traced: the medium is uniform and lit only by the scene's lights.
+// The rasterizer's drift and ambient term are not traced: the medium is lit only by the scene's lights.
/** The medium the tracer reads, or null when the environment has no fog. Throws what the rasterizer throws for bad input. */
export function resolveTraceVolume(volumeFog) {
@@ -154,7 +154,7 @@ function marchMeshVolume(volume, spans, originX, originY, originZ, directionX, d
* Builds the function that carries a ray through the scene's local volumes (environment.localVolumes). Each volume is marched with
* its own step count between its entry and exit, nearest entry first: the emitted light is added in proportion to the throughput
* so far, then the throughput is dimmed by exp(-absorption * profile * step). Emission and absorption do not scatter, so no light
- * sample is taken. The rasterizer's noise is not traced. `jitter` (0 to 1) offsets the samples within a step.
+ * sample is taken. A volume's `noiseAmount` modulates the profile with the rasterizer's own noise field. `jitter` (0 to 1) offsets the samples within a step.
* The returned function writes the emitted light into `emitted` and scales `throughput` in place.
*/
export function createLocalVolumeCrossing(volumes) {
diff --git a/tests/local-volume-noise.test.js b/tests/local-volume-noise.test.js
new file mode 100644
index 00000000..9470c0c2
--- /dev/null
+++ b/tests/local-volume-noise.test.js
@@ -0,0 +1,247 @@
+// Noise in local volumes (issue 808): the CPU path tracer reads the same noise field as the rasterizer's post shader. The pure tests
+// check the port; the browser test draws one noisy box in both renderers and compares the light that gets through per region, in
+// headless Chrome (SwiftShader) from the Vite dev server, and skips when Chrome cannot start. Set LOCAL_VOLUME_NOISE_ARTIFACTS to a
+// folder to also write the compare still and the per-region numbers there.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { freePort } from './helpers/free-port.js';
+import { renderPathTracedImage } from '../src/path-tracer.js';
+import { applyViewTransform } from '../src/view-transform.js';
+import { encodePng } from '../src/export-png.js';
+import { resolveLocalVolumes, localVolumeProfile } from '../src/local-volumes.js';
+import { localVolumeNoise, localVolumeNoiseFactor } from '../src/local-volume-noise.js';
+
+const NOISY_BOX = { shape: 'box', center: [0, 1.5, 0], size: [3, 1, 3], density: 1.2, falloff: 0.3, noiseAmount: 0.9, noiseScale: 3, steps: 32 };
+const REGION_TOLERANCE = 0.01;
+const MEAN_TOLERANCE = 0.005;
+
+test('the noise is deterministic, stays between 0 and 1 and averages about one half', () => {
+ let total = 0;
+ let lowest = 1;
+ let highest = 0;
+ const count = 4000;
+ for (let index = 0; index < count; index++) {
+ const value = localVolumeNoise(index * 0.37 - 20, Math.sin(index) * 9, index * 0.11);
+ assert.equal(value, localVolumeNoise(index * 0.37 - 20, Math.sin(index) * 9, index * 0.11));
+ total += value;
+ lowest = Math.min(lowest, value);
+ highest = Math.max(highest, value);
+ }
+ assert.ok(lowest >= 0 && highest <= 1);
+ assert.ok(Math.abs(total / count - 0.5) < 0.03, `mean ${total / count}`);
+ assert.equal(localVolumeNoise(1, 2, 3), localVolumeNoise(1 + 0, 2, 3));
+ assert.notEqual(localVolumeNoise(0.5, 0.5, 0.5), localVolumeNoise(7.5, 0.5, 0.5));
+});
+
+test('the noise is continuous: a tiny step moves the value a tiny amount', () => {
+ for (let index = 0; index < 200; index++) {
+ const x = index * 0.173;
+ assert.ok(Math.abs(localVolumeNoise(x, 0.4, 0.9) - localVolumeNoise(x + 1e-4, 0.4, 0.9)) < 2e-3);
+ }
+});
+
+test('noiseAmount 0 leaves the profile alone and a positive amount scales it by mix(1, 2 * noise, amount)', () => {
+ const [plain] = resolveLocalVolumes([{ shape: 'box', center: [0, 0, 0], size: [4, 4, 4], falloff: 0.5 }]);
+ const [noisy] = resolveLocalVolumes([{ shape: 'box', center: [0, 0, 0], size: [4, 4, 4], falloff: 0.5, noiseAmount: 0.6, noiseScale: 2 }]);
+ const point = [0.3, -0.2, 0.7];
+ assert.equal(plain.noiseAmount, 0);
+ assert.equal(localVolumeProfile(plain, ...point), 1);
+ const noise = localVolumeNoise(point[0] * 2, point[1] * 2, point[2] * 2);
+ const expected = 1 + (2 * noise - 1) * 0.6;
+ assert.ok(Math.abs(localVolumeNoiseFactor(noisy, ...point) - expected) < 1e-12);
+ assert.ok(Math.abs(localVolumeProfile(noisy, ...point) - expected) < 1e-12);
+ assert.equal(localVolumeProfile(noisy, 3, 0, 0), 0, 'outside the volume stays clear');
+});
+
+async function startServer(port) {
+ const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+ await new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => reject(new Error('The dev server did not start.')), 30000);
+ server.stdout.on('data', (data) => {
+ if (/ready in/.test(data.toString())) {
+ clearTimeout(timeout);
+ resolve();
+ }
+ });
+ server.on('exit', (code) => {
+ clearTimeout(timeout);
+ reject(new Error(`The dev server exited ${code}.`));
+ });
+ });
+ return server;
+}
+
+const SIZE = 64;
+const CPU_SIZE = 32;
+const LOOKING_DOWN = { eye: [0, 3, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 40 };
+
+// Draws the scene with and without the volume in the rasterizer and returns both frames as floats (RGBA, rows bottom to top).
+async function rasterFrames(page, volume) {
+ const task = async ({ size, localVolume, camera }) => {
+ const { box } = await import('/src/geometry.js');
+ const { Renderer67 } = await import('/src/renderer.js');
+ const { createFloatOutput, readFloatPixels } = await import('/src/float-output.js');
+ await import('/src/fog-shader.js');
+ const canvas = document.createElement('canvas');
+ canvas.width = size;
+ canvas.height = size;
+ canvas.style.width = size + 'px';
+ canvas.style.height = size + 'px';
+ document.body.append(canvas);
+ const material = { tag: 'unlit', color: [1, 1, 1], metallic: 0, roughness: 1, emission: 0 };
+ const ground = { name: 'ground', geometry: box(0, 1), matrix: new Float32Array([40, 0, 0, 0, 0, 0.2, 0, 0, 0, 0, 40, 0, 0, -0.1, 0, 1]), material };
+ const renderer = new Renderer67(canvas, [ground], { hdr: true, depth: true, samples: 1, pixelRatio: 1, ground: false });
+ const output = createFloatOutput(renderer.context, size, size);
+ const draw = (localVolumes) => {
+ const environment = { keyIntensity: 0, fillIntensity: 0, ambientIntensity: 0, localVolumes };
+ renderer.render({ ...camera, time: 0, environment, outputFramebuffer: output.framebuffer });
+ return Array.from(readFloatPixels(renderer.context, output.framebuffer, size, size));
+ };
+ const frames = { plain: draw([]), filled: draw([localVolume]) };
+ frames.glError = renderer.context.getError();
+ output.dispose();
+ renderer.dispose?.();
+ return frames;
+ };
+ return page.evaluate(task, { size: SIZE, localVolume: volume, camera: LOOKING_DOWN });
+}
+
+// The display shows aces(light) ^ (1 / 2.2); this undoes both for a channel, so the ratio of two frames is the light that got through.
+function lightOf(displayed) {
+ let low = 0;
+ let high = 64;
+ for (let round = 0; round < 40; round++) {
+ const middle = (low + high) / 2;
+ if (applyViewTransform('aces', [middle, middle, middle])[0] ** (1 / 2.2) < displayed) low = middle;
+ else high = middle;
+ }
+ return low;
+}
+
+// One transmittance per pixel, top row first.
+function rasterTransmittance({ plain, filled }) {
+ const result = new Float64Array(SIZE * SIZE);
+ for (let row = 0; row < SIZE; row++) {
+ for (let column = 0; column < SIZE; column++) {
+ const at = ((SIZE - 1 - row) * SIZE + column) * 4;
+ result[row * SIZE + column] = plain[at] > 0 ? lightOf(filled[at]) / lightOf(plain[at]) : 1;
+ }
+ }
+ return result;
+}
+
+async function cpuTransmittance(volume) {
+ const material = { tag: 'surface', metallic: 0, roughness: 1, color: [0, 0, 0], ior: 1, emission: 1, emissiveColor: [1, 1, 1] };
+ const half = 20;
+ const geometry = {
+ positions: new Float32Array([-half, 0, half, half, 0, half, half, 0, -half, -half, 0, -half]),
+ normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),
+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),
+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+ };
+ const { linear } = await renderPathTracedImage(
+ { parts: [{ name: 'ground', geometry, material }], environment: { localVolumes: [volume] }, camera: LOOKING_DOWN },
+ { width: CPU_SIZE, height: CPU_SIZE, denoise: false, threads: 1, bounces: 1, samples: 4 },
+ );
+ const result = new Float64Array(CPU_SIZE * CPU_SIZE);
+ for (let pixel = 0; pixel < result.length; pixel++) result[pixel] = linear[pixel * 3];
+ return result;
+}
+
+// The mean over a square cell of a square image of `size` pixels, the cell given in the units of a 64 pixel frame.
+function cellMean(values, size, column, row, cell) {
+ const scale = size / SIZE;
+ let total = 0;
+ let count = 0;
+ for (let y = Math.floor(row * cell * scale); y < Math.floor((row + 1) * cell * scale); y++) {
+ for (let x = Math.floor(column * cell * scale); x < Math.floor((column + 1) * cell * scale); x++) {
+ total += values[y * size + x];
+ count++;
+ }
+ }
+ return total / count;
+}
+
+function writeArtifacts(folder, raster, cpu, regions) {
+ mkdirSync(folder, { recursive: true });
+ const scale = 4;
+ const panel = SIZE * scale;
+ const width = panel * 3;
+ const pixels = new Uint8Array(width * panel * 4);
+ for (let y = 0; y < panel; y++) {
+ for (let x = 0; x < panel; x++) {
+ const rasterValue = raster[Math.floor(y / scale) * SIZE + Math.floor(x / scale)];
+ const cpuValue = cpu[Math.floor(y * CPU_SIZE / panel) * CPU_SIZE + Math.floor(x * CPU_SIZE / panel)];
+ const difference = Math.min(1, Math.abs(rasterValue - cpuValue) * 4);
+ [rasterValue, cpuValue, difference].forEach((value, index) => {
+ const at = (y * width + index * panel + x) * 4;
+ pixels.fill(Math.round(Math.max(0, Math.min(1, value)) * 255), at, at + 3);
+ pixels[at + 3] = 255;
+ });
+ }
+ }
+ writeFileSync(join(folder, 'noise-raster-cpu-difference.png'), encodePng(pixels, width, panel));
+ writeFileSync(join(folder, 'noise-transmittance.json'), `${JSON.stringify({
+ volume: NOISY_BOX,
+ note: 'Left to right in the still: rasterizer, CPU path tracer (4 samples), absolute difference times 4. Transmittance of white light looking down through the box.',
+ regionTolerance: REGION_TOLERANCE,
+ meanTolerance: MEAN_TOLERANCE,
+ regions,
+ }, null, 2)}\n`);
+}
+
+test('the rasterizer and the CPU path tracer let the same light through a noisy box', async (context) => {
+ let chromium;
+ try {
+ ({ chromium } = await import('playwright'));
+ } catch {
+ context.skip('playwright is not installed');
+ return;
+ }
+ const port = await freePort();
+ const server = await startServer(port);
+ let browser;
+ try {
+ try {
+ const launchArguments = ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--enable-webgl', '--ignore-gpu-blocklist'];
+ browser = await chromium.launch({ headless: true, args: launchArguments }).catch(() => chromium.launch({ headless: true, channel: 'chrome', args: launchArguments }));
+ } catch (error) {
+ context.skip(`Chrome did not start: ${error.message.split('\n')[0]}`);
+ return;
+ }
+ const page = await browser.newPage({ viewport: { width: SIZE, height: SIZE } });
+ await page.goto(`http://127.0.0.1:${port}/`);
+ const frames = await rasterFrames(page, NOISY_BOX);
+ assert.equal(frames.glError, 0);
+ const raster = rasterTransmittance(frames);
+ const cpu = await cpuTransmittance(NOISY_BOX);
+
+ const cells = 8;
+ const cellSize = SIZE / cells;
+ const regions = [];
+ for (let row = 0; row < cells; row++) {
+ for (let column = 0; column < cells; column++) {
+ const rasterMean = cellMean(raster, SIZE, column, row, cellSize);
+ const cpuMean = cellMean(cpu, CPU_SIZE, column, row, cellSize);
+ regions.push({ column, row, raster: +rasterMean.toFixed(4), cpu: +cpuMean.toFixed(4), difference: +Math.abs(rasterMean - cpuMean).toFixed(4) });
+ }
+ }
+ const meanOf = values => values.reduce((total, value) => total + value, 0) / values.length;
+ const rasterMean = meanOf(Array.from(raster));
+ const cpuMean = meanOf(Array.from(cpu));
+ if (process.env.LOCAL_VOLUME_NOISE_ARTIFACTS) {
+ writeArtifacts(process.env.LOCAL_VOLUME_NOISE_ARTIFACTS, raster, cpu, { whole: { raster: +rasterMean.toFixed(4), cpu: +cpuMean.toFixed(4) }, cells: regions });
+ }
+ const worst = regions.reduce((a, b) => (b.difference > a.difference ? b : a));
+ assert.ok(Math.abs(rasterMean - cpuMean) < MEAN_TOLERANCE, `whole frame: raster ${rasterMean} against CPU ${cpuMean}`);
+ assert.ok(worst.difference < REGION_TOLERANCE, `worst region ${JSON.stringify(worst)}`);
+ const spread = Math.max(...regions.map(region => region.cpu)) - Math.min(...regions.map(region => region.cpu));
+ assert.ok(spread > 0.3, `the box must actually dim some regions more than others (spread ${spread})`);
+ } finally {
+ await browser?.close();
+ server.kill();
+ }
+});
diff --git a/tests/local-volumes-entry-points.test.js b/tests/local-volumes-entry-points.test.js
index 2396fb17..c3d330ef 100644
--- a/tests/local-volumes-entry-points.test.js
+++ b/tests/local-volumes-entry-points.test.js
@@ -47,6 +47,7 @@ async function probeInPage(page) {
const { box } = await import('/src/geometry.js');
const { Renderer67 } = await import('/src/renderer.js');
const { createProgressiveTracer } = await import('/src/path-tracer-progressive.js');
+ const { createRealtimeTracer } = await import('/src/path-tracer-realtime.js');
await import('/src/fog-shader.js');
const wall = { geometry: box(0, 1), matrix: new Float32Array([4, 0, 0, 0, 0, 4, 0, 0, 0, 0, 0.2, 0, 0, 0, -0.1, 1]), material: { tag: 'unlit', color: [0.4, 0.4, 0.4], metallic: 0, roughness: 1, emission: 0 } };
const volume = [{ shape: 'sphere', center: [0, 0, 1], radius: 1 }];
@@ -82,10 +83,17 @@ async function probeInPage(page) {
} catch (failure) {
result.progressive = failure.message;
}
+ try {
+ const tracer = await createRealtimeTracer({ parts: [wall], environment: { localVolumes: volume }, camera: { eye: [0, 0, 5], target: [0, 0, 0], fov: 40 } }, { backend: 'gpu', width: 64, height: 64 });
+ tracer.dispose();
+ result.realtime = null;
+ } catch (failure) {
+ result.realtime = failure.message;
+ }
return result;
}
-test('the renderer rejects a bad localVolumes value before it binds a post program, and the progressive tracer refuses volumes', async (context) => {
+test('the renderer rejects a bad localVolumes value before it binds a post program, and the progressive and WebGL real-time tracers refuse volumes', async (context) => {
let chromium;
try {
({ chromium } = await import('playwright'));
@@ -114,6 +122,7 @@ test('the renderer rejects a bad localVolumes value before it binds a post progr
assert.equal(outcome.noDepth.choseProgram, false);
assert.equal(outcome.valid.message, null);
assert.match(outcome.progressive, /CPU path tracer only; the progressive path tracer cannot draw them/);
+ assert.match(outcome.realtime, /environment.localVolumes is traced by the CPU path tracer only; the WebGL realtime path tracer cannot draw them/);
} finally {
await browser?.close();
server.kill();
diff --git a/tests/local-volumes.test.js b/tests/local-volumes.test.js
index 6b1e83bc..5263a245 100644
--- a/tests/local-volumes.test.js
+++ b/tests/local-volumes.test.js
@@ -38,7 +38,7 @@ test('packing scales absorption by density and emission by strength, and the pro
assert.deepEqual(Array.from(buffers.absorption.slice(0, 4)), [3, 1.5, 0, 0.25]);
assert.deepEqual(Array.from(buffers.emission.slice(0, 4)), [4, 0, 0, 2]);
assert.equal(buffers.steps[0], 10);
- const [volume] = volumes;
+ const [volume] = resolveLocalVolumes([{ ...volumes[0], noiseAmount: 0 }]);
assert.equal(localVolumeProfile(volume, 1, 2, 3), 1);
assert.equal(localVolumeProfile(volume, 3, 2, 3), 0);
assert.equal(localVolumeProfile(volume, 1 + 1.5, 2, 3), 0.5);
@@ -187,9 +187,11 @@ test('the path tracer attenuates by exp(-density * thickness) and adds emission
assert.equal(nothing, clear);
});
-test('the path tracer refuses local volumes on a GPU backend instead of dropping them', async () => {
- await assert.rejects(
- renderPathTracedImage({ parts: ground(1), environment: { localVolumes: [{ shape: 'sphere', center: [0, 1, 0], radius: 1 }] }, camera: LOOKING_DOWN }, { ...IMAGE, backend: 'gpu' }),
- /localVolumes is traced by the CPU path tracer only/,
- );
+test('the path tracer refuses local volumes on every non-CPU backend instead of dropping them', async () => {
+ for (const backend of ['gpu', 'webgpu']) {
+ await assert.rejects(
+ renderPathTracedImage({ parts: ground(1), environment: { localVolumes: [{ shape: 'sphere', center: [0, 1, 0], radius: 1 }] }, camera: LOOKING_DOWN }, { ...IMAGE, backend }),
+ new RegExp(`environment\.localVolumes is traced by the CPU path tracer only; backend "${backend}" cannot draw them`),
+ );
+ }
});
diff --git a/tests/path-tracer-realtime-webgpu-device.test.js b/tests/path-tracer-realtime-webgpu-device.test.js
index c0ae231e..c7e96f35 100644
--- a/tests/path-tracer-realtime-webgpu-device.test.js
+++ b/tests/path-tracer-realtime-webgpu-device.test.js
@@ -2,6 +2,8 @@ import assert from 'node:assert/strict';
import test from 'node:test';
import { createRealtimeTracer } from '../src/path-tracer-realtime.js';
+import { createWebGpuRealtimeTracer } from '../src/path-tracer-realtime-webgpu.js';
+import { resolveRealtimeOptions } from '../src/path-tracer-realtime-options.js';
// A device that records what the real-time tracer asks of it, so the frame logic runs in Node without a GPU.
const usageFlags = { MAP_READ: 1, COPY_SRC: 2, COPY_DST: 4, UNIFORM: 8, STORAGE: 16, RENDER_ATTACHMENT: 32, COMPUTE: 64 };
@@ -158,3 +160,16 @@ test('an update that only moves a part keeps the history and sends the part moti
assert.equal(still[12], 0, 'then the part is still');
tracer.dispose();
});
+
+test('the WebGPU real-time tracer refuses local volumes at creation and on update, naming the field', async () => {
+ installGpu(async () => fakeAdapter);
+ const volumes = [{ shape: 'sphere', center: [0, 1, 0], radius: 1 }];
+ const options = resolveRealtimeOptions({ backend: 'webgpu', width: 64, height: 32 });
+ await assert.rejects(
+ () => createWebGpuRealtimeTracer({ ...scene, environment: { localVolumes: volumes } }, options, fakeCanvas),
+ /environment\.localVolumes is traced by the CPU path tracer only; the WebGPU realtime path tracer cannot draw them/,
+ );
+ const tracer = await createWebGpuRealtimeTracer(scene, options, fakeCanvas);
+ await assert.rejects(() => tracer.update({ parts: scene.parts, environment: { localVolumes: volumes } }), /environment\.localVolumes is traced by the CPU path tracer only/);
+ tracer.dispose();
+});