3D engine that AI agents drive
WIP: fog in-scatter in the irradiance grid trace (issue #543), not mergeable
Nguyen Xuan An7372fde77faf
diff --git a/src/agent-bake.js b/src/agent-bake.jsindex 9ecc94a1..3a60e0cf 100644--- a/src/agent-bake.js+++ b/src/agent-bake.js@@ -209,6 +209,7 @@ export function bakeAgentParts(parts, worldMatrices, environment, settings, geneskyTop: environment.skyTop,skyBottom: environment.skyBottom,lightDirection: environment.lightDirection,+ volumeFog: environment.volumeFog,};// A hair, particle or cloth node is drawn from geometry built every frame, which has no lightmap UVs.const snapshots = parts.map(part => ({diff --git a/src/grid-medium.js b/src/grid-medium.jsnew file mode 100644index 00000000..50c34a8c--- /dev/null+++ b/src/grid-medium.js@@ -0,0 +1,61 @@+import { hashUnit } from './light-bake.js';+import { henyeyGreensteinPhase, resolveTraceVolume, volumeInterval } from './path-tracer-volume.js';++// The fog a path of the irradiance grid crosses. It is optional and lives here, so a trace of a scene without fog runs the plain gatherer.++const FOUR_PI = 4 * Math.PI;++/**+ * The fog along one leg of a grid path, from the same box, density, colour and Henyey-Greenstein anisotropy the renderer's+ * `environment.volumeFog` uses. It returns null when the lighting has no fog. Otherwise it returns+ * `medium(origin, direction, distance, throughput, sum, texelIndex, sample, bounce)`: one scattering point drawn from the leg's+ * free-flight distribution, the light it scatters toward the path added to `sum`, and `throughput` dimmed by the leg's+ * transmittance, which the surface beyond the leg inherits. The scattered light is the sun (one shadow ray) and, when+ * `surfaceRadiance(point, direction, out)` is given, the light the nearest surface in one random direction sends back+ * (the fog's second scattering, which a bounce off the lit walls feeds). Neither is dimmed by the fog on its way.+ */+export function createGridMedium({ lighting, sun, tracer, scale, surfaceRadiance = null }) {+ const volume = resolveTraceVolume(lighting.volumeFog);+ if (!volume) return null;+ const interval = [0, 0];+ const point = [0, 0, 0];+ const sampleDirection = [0, 0, 0];+ const surfaceColor = [0, 0, 0];+ const scattered = [0, 0, 0];+ const shadowReach = scale * 1e6;+ return function medium(origin, direction, distance, throughput, sum, texelIndex, sample, bounce) {+ if (!volumeInterval(volume, origin[0], origin[1], origin[2], direction[0], direction[1], direction[2], distance, interval)) return;+ const transmittance = Math.exp(-volume.density * (interval[1] - interval[0]));+ const scatteredShare = 1 - transmittance;+ const seed = bounce * 4;+ const along = interval[0] - Math.log(1 - hashUnit(texelIndex, sample, seed + 201) * scatteredShare) / volume.density;+ for (let axis = 0; axis < 3; axis++) point[axis] = origin[axis] + direction[axis] * along;+ scattered[0] = 0;+ scattered[1] = 0;+ scattered[2] = 0;+ if (sun) {+ const sunBlocked = tracer.trace(point[0], point[1], point[2], sun.direction[0], sun.direction[1], sun.direction[2], shadowReach, true).nearestTriangle >= 0;+ if (!sunBlocked) {+ const phase = henyeyGreensteinPhase(volume.anisotropy, direction[0] * sun.direction[0] + direction[1] * sun.direction[1] + direction[2] * sun.direction[2]);+ for (let channel = 0; channel < 3; channel++) scattered[channel] += sun.color[channel] * phase;+ }+ }+ if (surfaceRadiance) {+ const height = 1 - 2 * hashUnit(texelIndex, sample, seed + 202);+ const ring = Math.sqrt(Math.max(0, 1 - height * height));+ const angle = 2 * Math.PI * hashUnit(texelIndex, sample, seed + 203);+ sampleDirection[0] = ring * Math.cos(angle);+ sampleDirection[1] = height;+ sampleDirection[2] = ring * Math.sin(angle);+ surfaceRadiance(point, sampleDirection, surfaceColor);+ const cosine = direction[0] * sampleDirection[0] + direction[1] * sampleDirection[1] + direction[2] * sampleDirection[2];+ // Uniform directions have the density 1 / (4 pi), so the estimate is the radiance times the phase times 4 pi.+ const weight = henyeyGreensteinPhase(volume.anisotropy, cosine) * FOUR_PI;+ for (let channel = 0; channel < 3; channel++) scattered[channel] += surfaceColor[channel] * weight;+ }+ for (let channel = 0; channel < 3; channel++) {+ sum[channel] += throughput[channel] * scatteredShare * volume.albedo[channel] * scattered[channel];+ throughput[channel] *= transmittance;+ }+ };+}diff --git a/src/irradiance-grid.js b/src/irradiance-grid.jsindex d0eff3d5..f13c9d3b 100644--- a/src/irradiance-grid.js+++ b/src/irradiance-grid.js@@ -2,9 +2,10 @@ import { createTracer } from './ray-query.js';import { readTriangle } from './triangle-math.js';import { registerShaderFeatureCode, layerTextureSupport } from './shader-registry.js';import {- MAX_BAKE_PARTS, buildWorld, createDirectIrradiance, createGatherer, diffuseAlbedo, emittedRadiance, normalizeLights, sceneScale, validatePart, withReach,+ MAX_BAKE_PARTS, buildWorld, createDirectIrradiance, createGatherer, diffuseAlbedo, emittedRadiance, hitNormal, normalizeLights, sceneScale, validatePart, withReach,} from './light-bake.js';import { worldBounds } from './probe-trace.js';+import { createGridMedium } from './grid-medium.js';// A baked grid of diffuse light: at each node of a 3D grid the light that other surfaces bounce toward it (the sun's lit// patches included, over several bounces), stored as first order spherical harmonics per colour channel. A lit surface reads@@ -215,6 +216,30 @@ function smoothNodes(data, valid, size, isConnected) {}}+const SURFACE_SCATTER = true;++// The radiance the nearest surface along a ray sends back: its emission and its direct light (what one bounce of the gatherer adds).+function createSurfaceRadiance({ world, tracer, albedoOfPart, emissionOfPart, directIrradiance }) {+ const hitPoint = [0, 0, 0];+ const normal = [0, 0, 0];+ return function surfaceRadiance(point, direction, out) {+ out[0] = 0;+ out[1] = 0;+ out[2] = 0;+ const hit = tracer.trace(point[0], point[1], point[2], direction[0], direction[1], direction[2], Infinity, false);+ const triangle = hit.nearestTriangle;+ if (triangle < 0) return;+ const distance = hit.nearestDistance;+ for (let axis = 0; axis < 3; axis++) hitPoint[axis] = point[axis] + direction[axis] * distance;+ hitNormal(world, triangle, direction, normal);+ const owner = world.triangleOwner[triangle];+ const irradiance = directIrradiance(hitPoint, normal, owner);+ for (let channel = 0; channel < 3; channel++) {+ out[channel] = emissionOfPart[owner][channel] + albedoOfPart[owner][channel] * irradiance[channel] / Math.PI;+ }+ };+}+/*** Traces the grid. For each node, the cosine weighted light arriving along the six axis directions (the bake's gatherer:* emission and direct light at every hit, bounced over `bounces` reflections) becomes a first order fit per colour channel:@@ -239,12 +264,18 @@ export function traceIrradianceGrid(parts, lighting, { resolution = true, sampleconst directIrradiance = createDirectIrradiance(tracer, withReach(lights, parts), offset, scale);const albedoOfPart = parts.map(part => diffuseAlbedo(part.material));const emissionOfPart = parts.map(part => emittedRadiance(part.material));- const gather = createGatherer({ world, tracer, albedoOfPart, emissionOfPart, directIrradiance, offset, samples, bounces });+ const sun = lights.sun ?? null;+ const surfaceRadiance = createSurfaceRadiance({ world, tracer, albedoOfPart, emissionOfPart, directIrradiance });+ const medium = createGridMedium({ lighting, sun, tracer, scale, surfaceRadiance: SURFACE_SCATTER ? surfaceRadiance : null });+ const gather = createGatherer({ world, tracer, albedoOfPart, emissionOfPart, directIrradiance, offset, samples, bounces, medium });const started = performance.now();const data = new Float32Array(nodeCount * COEFFICIENTS_PER_NODE);+ // The part of `data` that the fog scattered into the paths. The fog drawn on screen already scatters the sun itself, so it reads the grid without this part.+ const scatteredData = medium ? new Float32Array(nodeCount * COEFFICIENTS_PER_NODE) : null;const valid = new Uint8Array(nodeCount);const point = [0, 0, 0];const axisLight = [new Float64Array(3), new Float64Array(3)];+ const axisScattered = [new Float64Array(3), new Float64Array(3)];const axisSky = [0, 0];const axisNormal = [0, 0, 0];const [width, height] = layout.size;@@ -265,7 +296,7 @@ export function traceIrradianceGrid(parts, lighting, { resolution = true, samplefor (let side = 0; side < 2; side++) {axisNormal.fill(0);axisNormal[axis] = side === 0 ? 1 : -1;- axisSky[side] = gather(point, axisNormal, node * 6 + axis * 2 + side, axisLight[side]);+ axisSky[side] = gather(point, axisNormal, node * 6 + axis * 2 + side, axisLight[side], axisScattered[side]);}const skyBase = node * COEFFICIENTS_PER_NODE + SKY_SLOT;data[skyBase] += (axisSky[0] + axisSky[1]) / 6;@@ -274,6 +305,10 @@ export function traceIrradianceGrid(parts, lighting, { resolution = true, sampleconst base = node * COEFFICIENTS_PER_NODE + channel * 4;data[base] += (axisLight[0][channel] + axisLight[1][channel]) / 6;data[base + 1 + axis] = (axisLight[0][channel] - axisLight[1][channel]) / 2;+ if (scatteredData) {+ scatteredData[base] += (axisScattered[0][channel] + axisScattered[1][channel]) / 6;+ scatteredData[base + 1 + axis] = (axisScattered[0][channel] - axisScattered[1][channel]) / 2;+ }}}}@@ -291,12 +326,25 @@ export function traceIrradianceGrid(parts, lighting, { resolution = true, sampleconst length = Math.hypot(dx, dy, dz);return tracer.trace(point[0], point[1], point[2], dx / length, dy / length, dz / length, length, true).nearestTriangle < 0;};+ if (scatteredData) {+ fillInvalidNodes(scatteredData, Uint8Array.from(valid), layout.size);+ smoothNodes(scatteredData, valid, layout.size, isConnected);+ }fillInvalidNodes(data, valid, layout.size);smoothNodes(data, valid, layout.size, isConnected);const grid = { ...layout, data, nodes: nodeCount, solidNodes, seconds: (performance.now() - started) / 1000 };+ const scatteredGrid = scatteredData ? { ...layout, data: scatteredData } : null;// The fog's scattering reads the grid without importing this lazy module: the mean light arriving at a point from every// direction is the constant term of the fit. Not enumerable, so the report that copies the grid's fields stays plain data.- Object.defineProperty(grid, 'meanRadiance', { value: position => evaluateIrradianceGrid(grid, position, NO_DIRECTION) });+ // It leaves out the light the fog scattered, which the fog on screen adds again with its own sun term.+ Object.defineProperty(grid, 'meanRadiance', {+ value: position => {+ const total = evaluateIrradianceGrid(grid, position, NO_DIRECTION);+ if (!scatteredGrid) return total;+ const scattered = evaluateIrradianceGrid(scatteredGrid, position, NO_DIRECTION);+ return total.map((value, channel) => Math.max(0, value - scattered[channel]));+ },+ });return grid;}diff --git a/src/light-bake.js b/src/light-bake.jsindex a70224eb..43a6ceee 100644--- a/src/light-bake.js+++ b/src/light-bake.js@@ -451,16 +451,18 @@ const SCRATCH_TRIANGLE = new Float64Array(9);* The mean radiance arriving at one texel from other surfaces: cosine-weighted paths of up to `bounces` reflections,* each hit adding its own emission and its direct light. The caller multiplies by the texel's albedo.*/-export function createGatherer({ world, tracer, albedoOfPart, emissionOfPart, directIrradiance, offset, samples, bounces }) {+export function createGatherer({ world, tracer, albedoOfPart, emissionOfPart, directIrradiance, offset, samples, bounces, medium = null }) {+ const scatterSum = [0, 0, 0];const direction = [0, 0, 0];const origin = [0, 0, 0];const normal = [0, 0, 0];const hitPoint = [0, 0, 0];const throughput = [1, 1, 1];- return function gather(point, surfaceNormal, texelIndex, sum) {+ return function gather(point, surfaceNormal, texelIndex, sum, fogLight = null) {sum[0] = 0;sum[1] = 0;sum[2] = 0;+ scatterSum.fill(0);const rotation = hashUnit(texelIndex, 1, 7);// Rays that leave the scene on their first leg see the sky, so the share of them is how much sky this point sees.let escaped = 0;@@ -476,13 +478,18 @@ export function createGatherer({ world, tracer, albedoOfPart, emissionOfPart, dithroughput[2] = 1;for (let bounce = 0; bounce < bounces; bounce++) {const hit = tracer.trace(origin[0], origin[1], origin[2], direction[0], direction[1], direction[2], Infinity, false);- if (hit.nearestTriangle < 0) {+ // The tracer reuses its hit record, and the fog traces rays of its own, so the hit is read first.+ const hitTriangle = hit.nearestTriangle;+ const hitDistance = hit.nearestDistance;+ // The fog along this leg scatters light into the path and dims what lies beyond it.+ if (medium) medium(origin, direction, hitTriangle < 0 ? Infinity : hitDistance, throughput, scatterSum, texelIndex, sample, bounce);+ if (hitTriangle < 0) {if (bounce === 0) escaped++;break;}- for (let axis = 0; axis < 3; axis++) hitPoint[axis] = origin[axis] + direction[axis] * hit.nearestDistance;- hitNormal(world, hit.nearestTriangle, direction, normal);- const owner = world.triangleOwner[hit.nearestTriangle];+ for (let axis = 0; axis < 3; axis++) hitPoint[axis] = origin[axis] + direction[axis] * hitDistance;+ hitNormal(world, hitTriangle, direction, normal);+ const owner = world.triangleOwner[hitTriangle];const albedo = albedoOfPart[owner];const emission = emissionOfPart[owner];const irradiance = directIrradiance(hitPoint, normal, owner);@@ -497,7 +504,12 @@ export function createGatherer({ world, tracer, albedoOfPart, emissionOfPart, dicosineDirection(normal, hashUnit(texelIndex, sample, bounce * 2 + 11), hashUnit(texelIndex, sample, bounce * 2 + 12), direction);}}- for (let channel = 0; channel < 3; channel++) sum[channel] /= samples;+ // `sum` holds the fog's light too; `fogLight`, when given, gets that part alone.+ for (let channel = 0; channel < 3; channel++) {+ scatterSum[channel] /= samples;+ sum[channel] = sum[channel] / samples + scatterSum[channel];+ if (fogLight) fogLight[channel] = scatterSum[channel];+ }return escaped / samples;};}diff --git a/tests/grid-medium.test.js b/tests/grid-medium.test.jsnew file mode 100644index 00000000..8448d146--- /dev/null+++ b/tests/grid-medium.test.js@@ -0,0 +1,50 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { createGridMedium } from '../src/grid-medium.js';++const OPEN_SPACE = { trace: () => ({ nearestTriangle: -1, nearestDistance: Infinity }) };+const WALLED_IN = { trace: () => ({ nearestTriangle: 0, nearestDistance: 0.5 }) };+const FOG_BOX = { density: 0.5, minimum: [-10, -10, -10], maximum: [10, 10, 10], color: [1, 0.5, 0.25], anisotropy: 0, maxDistance: 100 };+const SUN = { color: [2, 2, 2], direction: [0, 1, 0] };++function runLeg(medium, distance) {+ const throughput = [1, 1, 1];+ const sum = [0, 0, 0];+ medium([0, 0, 0], [1, 0, 0], distance, throughput, sum, 3, 5, 0);+ return { throughput, sum };+}++test('lighting without fog gives no medium', () => {+ assert.equal(createGridMedium({ lighting: {}, sun: SUN, tracer: OPEN_SPACE, scale: 1, surfaceRadiance: null }), null);+ assert.equal(createGridMedium({ lighting: { volumeFog: { density: 0 } }, sun: SUN, tracer: OPEN_SPACE, scale: 1, surfaceRadiance: null }), null);+});++test('a leg through fog is dimmed by its transmittance and gains the single scattered sun', () => {+ const medium = createGridMedium({ lighting: { volumeFog: FOG_BOX }, sun: SUN, tracer: OPEN_SPACE, scale: 1, surfaceRadiance: null });+ const { throughput, sum } = runLeg(medium, 2);+ const transmittance = Math.exp(-0.5 * 2);+ for (const value of throughput) assert.ok(Math.abs(value - transmittance) < 1e-12);+ // Isotropic phase is 1 / (4 pi), whatever point of the leg scatters.+ FOG_BOX.color.forEach((albedo, channel) => {+ const expected = (1 - transmittance) * albedo * 2 / (4 * Math.PI);+ assert.ok(Math.abs(sum[channel] - expected) < 1e-12, `channel ${channel}: ${sum[channel]} against ${expected}`);+ });+});++test('a shadowed sun scatters nothing, and a leg outside the box is untouched', () => {+ const shadowed = createGridMedium({ lighting: { volumeFog: FOG_BOX }, sun: SUN, tracer: WALLED_IN, scale: 1, surfaceRadiance: null });+ assert.deepEqual(runLeg(shadowed, 2).sum, [0, 0, 0]);+ const outside = createGridMedium({ lighting: { volumeFog: { ...FOG_BOX, minimum: [20, 20, 20], maximum: [30, 30, 30] } }, sun: SUN, tracer: OPEN_SPACE, scale: 1, surfaceRadiance: null });+ const { throughput, sum } = runLeg(outside, 2);+ assert.deepEqual(throughput, [1, 1, 1]);+ assert.deepEqual(sum, [0, 0, 0]);+});++test('fog also scatters the light of the surface it sees, in proportion to it', () => {+ const dim = createGridMedium({ lighting: { volumeFog: FOG_BOX }, sun: null, tracer: OPEN_SPACE, scale: 1, surfaceRadiance: (point, direction, out) => out.fill(0.5) });+ const bright = createGridMedium({ lighting: { volumeFog: FOG_BOX }, sun: null, tracer: OPEN_SPACE, scale: 1, surfaceRadiance: (point, direction, out) => out.fill(1) });+ const dimSum = runLeg(dim, 2).sum;+ const brightSum = runLeg(bright, 2).sum;+ assert.ok(dimSum[0] > 0);+ assert.ok(Math.abs(brightSum[0] / dimSum[0] - 2) < 1e-9);+});