Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add bake.irradianceGrid: baked L1 SH irradiance grid for sunlit rooms (#506)

Nguyen Xuan Ana53e4c3a939b
diff --git a/changes/506.md b/changes/506.md
new file mode 100644
index 00000000..4c1e14fc
--- /dev/null
+++ b/changes/506.md
@@ -0,0 +1 @@
+- Add `bake.irradianceGrid` (issue #506): an opt-in baked grid of first order spherical harmonics that gives a sunlit closed room the warm multi-bounce light Cycles has. It is traced on the CPU with the bake's ray tracer, stored in one RGBA16F 3D texture and read with one lookup per pixel, so a frame costs no extra ray. It replaces lightmaps for the scene and is off by default. The code is a lazy module (`src/irradiance-grid.js`); the core entry gains one shader slot and one material field.
diff --git a/changes/506.size.md b/changes/506.size.md
new file mode 100644
index 00000000..14deccc5
--- /dev/null
+++ b/changes/506.size.md
@@ -0,0 +1,4 @@
+- scene:agent-scene: +82 bytes gzip (104300 to 104382) for the `irradianceGrid` shader slot, the `irradianceGrid` material field in the renderer's batch key and its feature line; the grid code is a lazy module and loads only with `bake.irradianceGrid`.
+- scene:agent-scene+lazy: +2788 bytes gzip (372792 to 375580), the lazy irradiance grid module (trace, placement, GLSL and texture upload) loaded with the bake.
+- goal:lit-box: +31 bytes gzip (50922 to 50953) for the shader slot and the batch key field. A real capability: a sunlit closed room can get warm multi-bounce light at no cost per frame (issue #506), opt in and off by default.
+- goal:agent-scene: +82 bytes gzip (104300 to 104382), same slot and field; the lead may accept it as a capability trade-off (issue #506).
diff --git a/docs/light-bake.md b/docs/light-bake.md
index 78f119ba..b0fbf514 100644
--- a/docs/light-bake.md
+++ b/docs/light-bake.md
@@ -74,6 +74,12 @@ GLB export writes `lightUvs` as `TEXCOORD_1` and the light map as the emissive t
An open scene with a floor gets the light the floor bounces without a bake and without a frame of extra cost. `groundBounceEnvironment(parts, environment)` from `67js/addons/ground-bounce` finds the floor (the lowest thin part that spans the scene, with a plain coloured, non-metal, opaque, untextured material) and returns the environment with an `irradianceSource` on its map: a copy whose lower half is `albedo * (keyColor * keyIntensity * max(lightDirection.y, 0) / pi + sky irradiance on a level surface)`. Only the diffuse light reads that copy, so walls and figures get the ground's light while the background and the reflections keep the real sky. The environment is returned unchanged when there is no such floor, a part is baked (its light map holds the bounce), the scene is a closed room, a point, spot or area light is present (the term counts the sun and the sky only), there is no map, or `environment.groundBounce` is `false`. `automaticAlbedo` gives the colour of a floor the preview adds when no part forms one. The floor is taken as unshadowed, level and infinite. `withGroundBounce(map, { albedo, keyColor, lightDirection })` is the same with the floor given by hand. On the `brick-flat` wall the mean luminance goes from 0.556 to 0.609 (Cycles 0.615); see "Ground bounce" in `bench/reference/README.md` for every scene.
+## Irradiance grid
+
+`bake: { preset: 'standard', irradianceGrid: true }` (or a node count from 8 to 48 along the longest side; `true` is 24) bakes a grid of diffuse light instead of lightmaps. `src/irradiance-grid.js` (a lazy module that loads with the bake) places a node every cell of the parts' bounds, and for each node traces the light that surfaces send toward it along the six axis directions with the bake's gatherer (emission and direct light at every hit, `bounces` reflections, about a quarter of the preset's samples). The six values become first order spherical harmonics per colour channel, stored in one RGBA16F 3D texture (three texels per node). A lit surface reads it with one trilinear lookup and its normal, so the warm light a sunlit floor sends up to the walls and the ceiling costs no ray per frame. A ray that leaves the scene adds nothing, so the sky stays with the environment map, and the grid replaces lightmaps for the scene. Probes still run.
+
+Nodes inside a solid (most rays hit the back of a face) are filled from their neighbours, and the lookup moves half a cell along the normal. A wall thinner than a cell can still leak light, and the grid is static: it is traced again when the parts, the lights or the bake change, and a part that moves does not move its bounce. The report is `bake.irradianceGrid` (`size`, `cellSize`, `nodes`, `solidNodes`, `seconds`). The sampler takes texture unit 12, which the splat layers also use, so a scene with both is not supported yet.
+
## Reflection probes
A probe is the room around a point, traced once and prefiltered like an environment map (`createEnvironmentResources`), so a glossy part reflects the room and not only the sky. `src/reflection-probes.js` holds placement and the renderer link; `src/probe-trace.js` traces on the CPU with the bake's ray tracer (direct light, bounced light, emission; a ray that leaves the scene reads the environment map or the sky colours), 64 by 32 texels, 32 samples and 2 bounces, deterministic, about 0.2 to 0.3 s per probe. A part takes the nearest probe whose `radius` reaches the middle of its bounds, else the environment. A probe lights the specular term only: diffuse stays with the environment and the bake. No parallax correction (not built: a probe at the centre of a room is wrong near the walls).
diff --git a/src/agent-bake.js b/src/agent-bake.js
index 56727f2c..9ecc94a1 100644
--- a/src/agent-bake.js
+++ b/src/agent-bake.js
@@ -2,6 +2,7 @@ import { planLightmaps, estimateBake, traceLightmaps } from './light-bake.js';
import { runKernel } from './kernel-offload.js';
import { normalizeProbeList, traceProbes } from './probe-trace.js';
import { placeProbes } from './reflection-probes.js';
+import { normalizeIrradianceGrid, placeIrradianceGrid, traceIrradianceGrid } from './irradiance-grid.js';
import { knownKeys, finiteNumber } from './agent-recipe-checks.js';
import { BAKE_PRESETS, BAKE_RANGES, BAKE_MAXIMUM_SECONDS, BAKE_WORKER_MAXIMUM_SECONDS, BAKE_PRESET_PATH_WORK, BAKE_EXPLICIT_PATH_WORK_LIMIT } from './agent-scene-capabilities.js';
@@ -10,7 +11,7 @@ const PRESET_SAMPLES_FLOOR = 16;
// Recipe `bake`: bounced light written into lightmaps when the scene builds. This module loads on demand, so scenes
// without a bake never download the ray tracer.
-const BAKE_FIELDS = ['preset', 'samples', 'bounces', 'texelsPerUnit', 'probes'];
+const BAKE_FIELDS = ['preset', 'samples', 'bounces', 'texelsPerUnit', 'probes', 'irradianceGrid'];
const BAKED_MATERIAL_FIELDS = ['emission', 'emissiveColor', 'emissiveMap', 'lightMap', 'lightMapScale', 'occlusionMap', 'occlusionStrength'];
/** Validates a recipe bake section and returns the plain, resolved form stored in the recipe (null clears it). */
@@ -36,6 +37,11 @@ export function normalizeAgentBake(input) {
} else {
resolved.probes = input.probes === false || input.probes === 'room' ? input.probes : normalizeProbeList(input.probes);
}
+ // Opt in: a grid of diffuse light for every part, traced instead of lightmaps (src/irradiance-grid.js). Not stored when off, so a recipe without it keeps its bytes.
+ const irradianceGrid = normalizeIrradianceGrid(input.irradianceGrid);
+ if (irradianceGrid) {
+ resolved.irradianceGrid = irradianceGrid;
+ }
for (const field of ['samples', 'bounces']) {
if (!Number.isInteger(resolved[field])) {
throw new RangeError(`Bake ${field} must be an integer.`);
@@ -211,6 +217,9 @@ export function bakeAgentParts(parts, worldMatrices, environment, settings, gene
material: { ...part.material },
generatesGeometry: generatedGeometryGenerators.get(part.name) ?? false,
}));
+ if (settings.irradianceGrid) {
+ return bakeIrradianceGridParts(parts, snapshots, lighting, settings);
+ }
const { changed, report, used, reduced, reduction } = runKernel('lightBake', [snapshots, lighting, settings], bakeChangedParts);
// Probes see the unbaked parts, as the bake does, and are traced as a kernel of their own so a worker can take them too.
const probeTrace = !settings.probes ? null
@@ -231,3 +240,25 @@ export function bakeAgentParts(parts, worldMatrices, environment, settings, gene
return { parts: Object.freeze(placed ? placed.parts : bakedParts), report: { ...settings, ...(placed ? { probes: placed.report } : {}), used, reduced, reduction, texels: report.texels, rayWork: report.rayWork, seconds: report.seconds,
bakedParts: report.parts.length, skipped: report.skipped } };
}
+
+// The grid is a few thousand nodes of six gathers each, so its samples are a quarter of the lightmap preset's: about 32 at standard.
+const GRID_SAMPLES_SHARE = 4;
+const GRID_MINIMUM_SAMPLES = 8;
+
+// bake.irradianceGrid: no lightmaps. Every part reads one baked grid of bounced light (the sun's lit patches included), and the
+// probes still run. The grid traces on the page's thread, inside the same time limit as a bake.
+function bakeIrradianceGridParts(parts, snapshots, lighting, settings) {
+ const grid = traceIrradianceGrid(snapshots, lighting, {
+ resolution: settings.irradianceGrid,
+ samples: Math.max(GRID_MINIMUM_SAMPLES, Math.round(settings.samples / GRID_SAMPLES_SHARE)),
+ bounces: settings.bounces,
+ maxSeconds: bakeSecondsLimit(),
+ });
+ const probeTrace = !settings.probes ? null
+ : runKernel('probeTrace', [snapshots, lighting, settings.probes, { environment: lighting, maxSeconds: bakeSecondsLimit() }], traceProbes);
+ const gridParts = placeIrradianceGrid(parts, grid);
+ const placed = probeTrace ? placeProbes(gridParts, probeTrace) : null;
+ const { data, ...gridReport } = grid;
+ return { parts: Object.freeze(placed ? placed.parts : gridParts), report: { ...settings, ...(placed ? { probes: placed.report } : {}), used: settings, reduced: false, reduction: null, texels: 0, rayWork: 0,
+ seconds: grid.seconds, bakedParts: 0, skipped: [], irradianceGrid: gridReport } };
+}
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index 7eb92cf3..5a733093 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -273,7 +273,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
}),
// Recipe bake: bounced light written into lightmaps at build time (src/light-bake.js, loaded on demand).
bake: Object.freeze({
- fields: 'preset, or samples (1-256), bounces (1-3), texelsPerUnit (1-12) over it; probes room by default, false for none, or up to 4 {position, radius?}. Same recipe, same bytes.',
+ fields: 'preset, or samples (1-256), bounces (1-3), texelsPerUnit (1-12) over it; irradianceGrid true or 8-48 nodes: a baked grid of bounced diffuse light in place of lightmaps (opt in, static); probes room by default, false for none, or up to 4 {position, radius?}. Same recipe, same bytes.',
presets: BAKE_PRESETS,
notes: 'Bounced light from point, spot, area and key lights. Reruns when parts, lights, materials or bake change. Skips alpha, skin, morph, hair, cloth (bake.skipped). A preset shrinks to fit, never refuses (bake.used, bake.reduction); explicit settings fail over maxPathWork or past maxSeconds. No environment map or specular. Probes: specular only, none in glTF.',
limits: Object.freeze({ maxSeconds: BAKE_MAXIMUM_SECONDS, workerMaxSeconds: BAKE_WORKER_MAXIMUM_SECONDS, maxPathWork: BAKE_EXPLICIT_PATH_WORK_LIMIT, maxPointLights: MAX_POINT_LIGHTS }),
diff --git a/src/irradiance-grid.js b/src/irradiance-grid.js
new file mode 100644
index 00000000..b85abb16
--- /dev/null
+++ b/src/irradiance-grid.js
@@ -0,0 +1,340 @@
+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,
+} from './light-bake.js';
+import { worldBounds } from './probe-trace.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
+// it with one trilinear lookup and Lambert's cosine, so the warm light a sunlit floor sends up to the ceiling and walls costs
+// no ray per frame. The sky is not in it: a ray that leaves the scene adds nothing, and the environment map keeps lighting
+// that. The grid is static; it is traced again when the scene or its lights change.
+// This module is optional. A scene without `bake.irradianceGrid` never loads it, and the renderer's only link to it is the
+// material field `irradianceGrid`, which batches parts by grid.
+
+export const IRRADIANCE_GRID_LIMITS = Object.freeze({ resolution: [8, 48], samples: [4, 128], bounces: [1, 3], maxNodes: 65536 });
+export const DEFAULT_GRID_RESOLUTION = 24;
+const DEFAULT_GRID_SAMPLES = 32;
+const VALIDITY_DIRECTIONS = buildValidityDirections();
+const BACKFACE_INVALID_SHARE = 0.5;
+const FILL_PASSES = 12;
+const COEFFICIENTS_PER_NODE = 12;
+// The grid is one 3D texture: node (x, y, z) takes three texels along x, one per colour channel, each holding the channel's
+// constant term and its x, y and z terms.
+const TEXTURE_UNIT = 12;
+
+function buildValidityDirections() {
+ const directions = [];
+ for (const axis of [0, 1, 2]) {
+ for (const sign of [-1, 1]) {
+ const direction = [0, 0, 0];
+ direction[axis] = sign;
+ directions.push(direction);
+ }
+ }
+ const diagonal = Math.sqrt(1 / 3);
+ for (const x of [-1, 1]) {
+ for (const y of [-1, 1]) {
+ for (const z of [-1, 1]) {
+ directions.push([x * diagonal, y * diagonal, z * diagonal]);
+ }
+ }
+ }
+ return directions;
+}
+
+/** Validates the recipe field: true, or a node count along the longest side. Returns the plain settings or null. */
+export function normalizeIrradianceGrid(input) {
+ if (input === undefined || input === null || input === false) {
+ return null;
+ }
+ const resolution = input === true ? DEFAULT_GRID_RESOLUTION : input;
+ const [minimum, maximum] = IRRADIANCE_GRID_LIMITS.resolution;
+ if (!Number.isInteger(resolution) || resolution < minimum || resolution > maximum) {
+ throw new RangeError(`bake.irradianceGrid must be true or an integer node count from ${minimum} to ${maximum}.`);
+ }
+ return resolution;
+}
+
+function gridLayout(parts, resolution) {
+ const minimum = [Infinity, Infinity, Infinity];
+ const maximum = [-Infinity, -Infinity, -Infinity];
+ for (const part of parts) {
+ const bounds = worldBounds(part);
+ for (let axis = 0; axis < 3; axis++) {
+ minimum[axis] = Math.min(minimum[axis], bounds.minimum[axis]);
+ maximum[axis] = Math.max(maximum[axis], bounds.maximum[axis]);
+ }
+ }
+ const extent = maximum.map((value, axis) => Math.max(value - minimum[axis], 1e-3));
+ const cellSize = Math.max(...extent) / (resolution - 1);
+ const size = extent.map(length => Math.max(2, Math.round(length / cellSize) + 1));
+ return { origin: minimum, cellSize, size };
+}
+
+// A node inside a solid sees the back of the surfaces around it; its light would be the inside of a wall, not the room's.
+function isInsideSolid(world, tracer, point) {
+ const triangle = new Float64Array(9);
+ let backfaces = 0;
+ let hits = 0;
+ for (const direction of VALIDITY_DIRECTIONS) {
+ const hit = tracer.trace(point[0], point[1], point[2], direction[0], direction[1], direction[2], Infinity, false);
+ if (hit.nearestTriangle < 0) {
+ continue;
+ }
+ hits++;
+ readTriangle(world.positions, world.indices, hit.nearestTriangle, triangle);
+ const normalX = (triangle[4] - triangle[1]) * (triangle[8] - triangle[2]) - (triangle[5] - triangle[2]) * (triangle[7] - triangle[1]);
+ const normalY = (triangle[5] - triangle[2]) * (triangle[6] - triangle[0]) - (triangle[3] - triangle[0]) * (triangle[8] - triangle[2]);
+ const normalZ = (triangle[3] - triangle[0]) * (triangle[7] - triangle[1]) - (triangle[4] - triangle[1]) * (triangle[6] - triangle[0]);
+ if (normalX * direction[0] + normalY * direction[1] + normalZ * direction[2] > 0) {
+ backfaces++;
+ }
+ }
+ return hits > 0 && backfaces / VALIDITY_DIRECTIONS.length > BACKFACE_INVALID_SHARE;
+}
+
+// Nodes inside walls take the mean of their valid neighbours, a few passes deep, so a lookup near a wall never reads black.
+function fillInvalidNodes(data, valid, size) {
+ const [width, height, depth] = size;
+ const strides = [1, width, width * height];
+ for (let pass = 0; pass < FILL_PASSES; pass++) {
+ const newlyValid = [];
+ for (let node = 0; node < valid.length; node++) {
+ if (valid[node]) {
+ continue;
+ }
+ const coordinates = [node % width, Math.floor(node / width) % height, Math.floor(node / (width * height))];
+ const sum = new Float32Array(COEFFICIENTS_PER_NODE);
+ let count = 0;
+ for (let axis = 0; axis < 3; axis++) {
+ for (const step of [-1, 1]) {
+ const moved = coordinates[axis] + step;
+ if (moved < 0 || moved >= size[axis]) {
+ continue;
+ }
+ const neighbour = node + step * strides[axis];
+ if (!valid[neighbour]) {
+ continue;
+ }
+ for (let slot = 0; slot < COEFFICIENTS_PER_NODE; slot++) {
+ sum[slot] += data[neighbour * COEFFICIENTS_PER_NODE + slot];
+ }
+ count++;
+ }
+ }
+ if (count > 0) {
+ for (let slot = 0; slot < COEFFICIENTS_PER_NODE; slot++) {
+ data[node * COEFFICIENTS_PER_NODE + slot] = sum[slot] / count;
+ }
+ newlyValid.push(node);
+ }
+ }
+ if (newlyValid.length === 0) {
+ break;
+ }
+ for (const node of newlyValid) {
+ valid[node] = 1;
+ }
+ }
+}
+
+/**
+ * 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:
+ * the mean of the opposite pair is the constant term and half their difference the slope. Nodes inside solids are filled from
+ * their neighbours. Returns `{ origin, cellSize, size, data, seconds, nodes, solidNodes }`; the same input gives the same bytes.
+ */
+export function traceIrradianceGrid(parts, lighting, { resolution = DEFAULT_GRID_RESOLUTION, samples = DEFAULT_GRID_SAMPLES, bounces = 3, maxSeconds = 60 } = {}) {
+ if (!Array.isArray(parts) || parts.length === 0 || parts.length > MAX_BAKE_PARTS) {
+ throw new RangeError(`The irradiance grid takes from 1 to ${MAX_BAKE_PARTS} parts.`);
+ }
+ parts.forEach(validatePart);
+ const layout = gridLayout(parts, resolution);
+ const nodeCount = layout.size[0] * layout.size[1] * layout.size[2];
+ if (nodeCount > IRRADIANCE_GRID_LIMITS.maxNodes) {
+ throw new RangeError(`The irradiance grid would have ${nodeCount} nodes; the limit is ${IRRADIANCE_GRID_LIMITS.maxNodes}. Lower bake.irradianceGrid.`);
+ }
+ const lights = normalizeLights(lighting);
+ const world = buildWorld(parts);
+ const scale = sceneScale(world.positions);
+ const offset = scale * 1e-4;
+ const tracer = createTracer(world);
+ const 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 started = performance.now();
+ const data = new Float32Array(nodeCount * COEFFICIENTS_PER_NODE);
+ const valid = new Uint8Array(nodeCount);
+ const point = [0, 0, 0];
+ const axisLight = [new Float64Array(3), new Float64Array(3)];
+ const axisNormal = [0, 0, 0];
+ const [width, height] = layout.size;
+ let solidNodes = 0;
+ for (let node = 0; node < nodeCount; node++) {
+ if (performance.now() - started > maxSeconds * 1000) {
+ throw new Error(`Irradiance grid trace passed maxSeconds (${maxSeconds}).`);
+ }
+ point[0] = layout.origin[0] + (node % width) * layout.cellSize;
+ point[1] = layout.origin[1] + (Math.floor(node / width) % height) * layout.cellSize;
+ point[2] = layout.origin[2] + Math.floor(node / (width * height)) * layout.cellSize;
+ if (isInsideSolid(world, tracer, point)) {
+ solidNodes++;
+ continue;
+ }
+ valid[node] = 1;
+ for (let axis = 0; axis < 3; axis++) {
+ for (let side = 0; side < 2; side++) {
+ axisNormal.fill(0);
+ axisNormal[axis] = side === 0 ? 1 : -1;
+ gather(point, axisNormal, node * 6 + axis * 2 + side, axisLight[side]);
+ }
+ for (let channel = 0; channel < 3; channel++) {
+ const 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;
+ }
+ }
+ }
+ fillInvalidNodes(data, valid, layout.size);
+ return { ...layout, data, nodes: nodeCount, solidNodes, seconds: (performance.now() - started) / 1000 };
+}
+
+/** The light a surface with this normal receives from the grid at a point (trilinear, as the shader reads it): what the shader multiplies by the albedo. */
+export function evaluateIrradianceGrid(grid, position, normal) {
+ const coordinates = [0, 1, 2].map(axis => Math.min(Math.max((position[axis] + normal[axis] * grid.cellSize * 0.5 - grid.origin[axis]) / grid.cellSize, 0), grid.size[axis] - 1));
+ const lower = coordinates.map(Math.floor);
+ const fraction = coordinates.map((value, axis) => value - lower[axis]);
+ const result = [0, 0, 0];
+ for (let corner = 0; corner < 8; corner++) {
+ const indices = [0, 1, 2].map(axis => Math.min(lower[axis] + ((corner >> axis) & 1), grid.size[axis] - 1));
+ const weight = [0, 1, 2].reduce((product, axis) => product * ((corner >> axis) & 1 ? fraction[axis] : 1 - fraction[axis]), 1);
+ const base = (indices[0] + grid.size[0] * (indices[1] + grid.size[1] * indices[2])) * COEFFICIENTS_PER_NODE;
+ for (let channel = 0; channel < 3; channel++) {
+ const offset = base + channel * 4;
+ result[channel] += weight * (grid.data[offset] + grid.data[offset + 1] * normal[0] + grid.data[offset + 2] * normal[1] + grid.data[offset + 3] * normal[2]);
+ }
+ }
+ return result.map(value => Math.max(value, 0));
+}
+
+function gridMaterial(liveMaterial, grid, wrappers) {
+ if (!wrappers.has(liveMaterial)) {
+ const wrapper = {};
+ for (const field of Object.keys(liveMaterial)) {
+ Object.defineProperty(wrapper, field, { enumerable: true, get: () => liveMaterial[field] });
+ }
+ Object.defineProperty(wrapper, 'irradianceGrid', { enumerable: true, value: grid });
+ wrappers.set(liveMaterial, Object.freeze(wrapper));
+ }
+ return wrappers.get(liveMaterial);
+}
+
+/** Gives every part the grid, as a material wrapper that keeps reading the live material, so motion on colour still works. */
+export function placeIrradianceGrid(parts, grid) {
+ const wrappers = new Map();
+ return parts.map(part => Object.freeze({ ...part, material: gridMaterial(part.material, grid, wrappers) }));
+}
+
+registerShaderFeatureCode('irradianceGrid', Object.freeze({
+ declarations: [
+ 'uniform highp sampler3D irradianceGridTexture;',
+ 'uniform float irradianceGridEnabled;',
+ 'uniform vec4 irradianceGridOrigin;',
+ 'uniform vec3 irradianceGridSize;',
+ // The grid stores light for the cosine lobe already, so this is the same unit as environmentDiffuse. The x axis is
+ // lerped by hand because three nodes share a row of texels (one per colour channel); y and z use the hardware filter.
+ 'vec3 irradianceGridDiffuse(vec3 position, vec3 normal) {',
+ ' vec3 grid = clamp((position + normal * irradianceGridOrigin.w * 0.5 - irradianceGridOrigin.xyz) / irradianceGridOrigin.w, vec3(0.0), irradianceGridSize - 1.0);',
+ ' float left = floor(grid.x);',
+ ' float right = min(left + 1.0, irradianceGridSize.x - 1.0);',
+ ' float blend = grid.x - left;',
+ ' vec2 across = (grid.yz + 0.5) / irradianceGridSize.yz;',
+ ' float rowWidth = 3.0 * irradianceGridSize.x;',
+ ' vec4 direction = vec4(1.0, normal);',
+ ' vec3 result = vec3(0.0);',
+ ' for (int channel = 0; channel < 3; channel++) {',
+ ' float slot = float(channel) + 0.5;',
+ ' vec4 first = texture(irradianceGridTexture, vec3((3.0 * left + slot) / rowWidth, across));',
+ ' vec4 second = texture(irradianceGridTexture, vec3((3.0 * right + slot) / rowWidth, across));',
+ ' result[channel] = dot(mix(first, second, blend), direction);',
+ ' }',
+ ' return max(result, vec3(0.0));',
+ '}',
+ '',
+ ].join('\n'),
+ irradianceGrid: ' if (irradianceGridEnabled > 0.5) radiance += color * (1.0 - metallic) * irradianceGridDiffuse(worldPosition, normal);\n',
+}));
+
+const rendererStates = new WeakMap();
+
+function stateOf(renderer) {
+ if (!rendererStates.has(renderer)) {
+ const { context, program } = renderer;
+ const locate = name => context.getUniformLocation(program, name);
+ rendererStates.set(renderer, {
+ textures: new Map(),
+ enabled: locate('irradianceGridEnabled'),
+ origin: locate('irradianceGridOrigin'),
+ size: locate('irradianceGridSize'),
+ bound: undefined,
+ });
+ // The sampler must never share a unit with a sampler of another type, so it points at its own unit from the first draw.
+ context.uniform1i(locate('irradianceGridTexture'), TEXTURE_UNIT);
+ }
+ return rendererStates.get(renderer);
+}
+
+function uploadGrid(renderer, grid) {
+ const context = renderer.context;
+ const [nodesX, nodesY, nodesZ] = grid.size;
+ const texture = context.createTexture();
+ const previous = context.getParameter(context.TEXTURE_BINDING_3D);
+ context.bindTexture(context.TEXTURE_3D, texture);
+ context.texImage3D(context.TEXTURE_3D, 0, context.RGBA16F, nodesX * 3, nodesY, nodesZ, 0, context.RGBA, context.FLOAT, grid.data);
+ context.texParameteri(context.TEXTURE_3D, context.TEXTURE_MIN_FILTER, context.LINEAR);
+ context.texParameteri(context.TEXTURE_3D, context.TEXTURE_MAG_FILTER, context.LINEAR);
+ for (const wrap of [context.TEXTURE_WRAP_S, context.TEXTURE_WRAP_T, context.TEXTURE_WRAP_R]) {
+ context.texParameteri(context.TEXTURE_3D, wrap, context.CLAMP_TO_EDGE);
+ }
+ context.bindTexture(context.TEXTURE_3D, previous);
+ renderer.textures.set(Symbol('irradiance-grid'), texture);
+ return texture;
+}
+
+function bindGrid(renderer, mapState) {
+ if (!renderer.shaderFeatures?.has('irradianceGrid')) {
+ return;
+ }
+ const state = stateOf(renderer);
+ const context = renderer.context;
+ const grid = mapState[21] ?? null;
+ if (!grid) {
+ if (state.bound !== null) {
+ context.uniform1f(state.enabled, 0);
+ state.bound = null;
+ }
+ return;
+ }
+ if (!state.textures.has(grid)) {
+ state.textures.set(grid, uploadGrid(renderer, grid));
+ }
+ // Other features share this unit when a batch needs them, so the texture is bound again for every batch with a grid.
+ context.activeTexture(context.TEXTURE0 + TEXTURE_UNIT);
+ context.bindTexture(context.TEXTURE_3D, state.textures.get(grid));
+ if (state.bound !== grid) {
+ context.uniform1f(state.enabled, 1);
+ context.uniform4f(state.origin, grid.origin[0], grid.origin[1], grid.origin[2], grid.cellSize);
+ context.uniform3f(state.size, grid.size[0], grid.size[1], grid.size[2]);
+ state.bound = grid;
+ }
+}
+
+const previousBind = layerTextureSupport.bind;
+layerTextureSupport.bind = (renderer, mapState, layerState, batch) => {
+ previousBind?.(renderer, mapState, layerState, batch);
+ bindGrid(renderer, mapState);
+};
diff --git a/src/light-bake.js b/src/light-bake.js
index b8babd05..093dda2b 100644
--- a/src/light-bake.js
+++ b/src/light-bake.js
@@ -235,7 +235,7 @@ export function averageMapColor(map) {
return sum.map(total => total / (AVERAGE_GRID * AVERAGE_GRID));
}
-function diffuseAlbedo(material) {
+export function diffuseAlbedo(material) {
const keep = 1 - (material.metallic ?? 0);
const mapAverage = averageMapColor(material.map);
return material.color.map((channel, index) => Math.max(channel, 0) * keep * mapAverage[index]);
diff --git a/src/renderer.js b/src/renderer.js
index 9ff6666d..d97118e0 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -80,6 +80,7 @@ function shaderFeaturesOfParts(parts) {
if (material[field]) features.add(MAP_SHADER_FEATURES[index]);
});
if (material.environmentProbe) features.add('probe');
+ if (material.irradianceGrid) features.add('irradianceGrid');
if (material.normalMap?.uvTransform) features.add('normalMapTransform');
Object.keys(material.layerMaps ?? {}).forEach(name => features.add(name));
if (material.layers) features.add('splat');
@@ -168,7 +169,7 @@ function materialMapState(material) {
const occlusionStrength = material.occlusionStrength ?? 1;
if (material.layers || material.splat) requireSplatSupport().validate(material);
if (material.layers && PROCEDURAL_MATERIAL_TAGS.has(material.tag)) throw new Error('Splat layers require a standard PBR material tag.');
- return [...MATERIAL_MAPS.map(field => material[field] ?? null), normalScale[0], normalScale[1], occlusionStrength, ...mossState(material), material.boxMapScale ?? 0, material.boxMapAxis ?? 1, ...lightMapState(material), material.layers ?? null, material.splat ?? null, material.layerMaps ?? null, material.environmentProbe ?? null, material.waterReflection ?? null];
+ return [...MATERIAL_MAPS.map(field => material[field] ?? null), normalScale[0], normalScale[1], occlusionStrength, ...mossState(material), material.boxMapScale ?? 0, material.boxMapAxis ?? 1, ...lightMapState(material), material.layers ?? null, material.splat ?? null, material.layerMaps ?? null, material.environmentProbe ?? null, material.waterReflection ?? null, material.irradianceGrid ?? null];
}
// A baked light map reads the second UV set, so it is only drawn for parts that cannot be skinned or morphed.
diff --git a/src/shaders.js b/src/shaders.js
index f4c92a82..c96c75be 100644
--- a/src/shaders.js
+++ b/src/shaders.js
@@ -685,7 +685,7 @@ ${featureCode("probeSurroundings")} radiance += surroundings * reflectance *
}
// Baked bounced light arrives as irradiance, so the surface colour (pattern and texture included) tints it here.
if (USES_LIGHT_MAP) radiance += color * (1.0 - metallic) * texture(lightMap, lightmapUV).rgb * lightMapScale;
- vec3 keyResponse = keyColor / mix(vec3(5.2, 4.7, 4.1), vec3(3.7, 3.4, 2.9), worldMode);
+${featureCode("irradianceGrid")} vec3 keyResponse = keyColor / mix(vec3(5.2, 4.7, 4.1), vec3(3.7, 3.4, 2.9), worldMode);
keyResponse *= mix(daylight, 1.0, worldMode);
${featureCode("worldLight")} if (USES_SHEEN) radiance = sheenLayer(radiance, normal, viewDirection, visibility);
if (USES_CLEARCOAT) radiance = clearCoatLayer(radiance, normal, viewDirection, visibility);
diff --git a/tests/irradiance-grid.test.js b/tests/irradiance-grid.test.js
new file mode 100644
index 00000000..5ff487ec
--- /dev/null
+++ b/tests/irradiance-grid.test.js
@@ -0,0 +1,105 @@
+import './support/load-agent-scene-modules.mjs';
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { box } from '../src/geometry.js';
+import { createAgentScene } from '../src/agent-scene.js';
+import { normalizeAgentBake } from '../src/agent-bake.js';
+import { evaluateIrradianceGrid, normalizeIrradianceGrid, placeIrradianceGrid, traceIrradianceGrid } from '../src/irradiance-grid.js';
+import { createFragmentShader } from '../src/shaders.js';
+
+const cube = box(0, 1);
+
+function placed(name, translation, scale, color) {
+ const matrix = new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]);
+ return { name, geometry: cube, matrix, material: { tag: 'surface', color, metallic: 0, roughness: 0.8, emission: 0 } };
+}
+
+// A closed room with a warm floor and white walls. The ceiling has a slit, so the sun lights a strip of the floor.
+function sunlitRoom() {
+ const white = [0.8, 0.8, 0.8];
+ return [
+ placed('floor', [0, -0.05, 0], [6, 0.1, 6], [0.8, 0.4, 0.1]),
+ placed('ceiling-left', [-2.2, 3.05, 0], [1.6, 0.1, 6], white),
+ placed('ceiling-right', [2.2, 3.05, 0], [3.6, 0.1, 6], white),
+ placed('back', [0, 1.5, -3.05], [6.2, 3.2, 0.1], white),
+ placed('front', [0, 1.5, 3.05], [6.2, 3.2, 0.1], white),
+ placed('left', [-3.05, 1.5, 0], [0.1, 3.2, 6], white),
+ placed('right', [3.05, 1.5, 0], [0.1, 3.2, 6], white),
+ ];
+}
+
+const sun = { keyColor: [3, 3, 3], lightDirection: [0.2, 1, 0.1] };
+
+test('the recipe field is true, an integer node count or off, and anything else is refused', () => {
+ assert.equal(normalizeIrradianceGrid(undefined), null);
+ assert.equal(normalizeIrradianceGrid(false), null);
+ assert.equal(normalizeIrradianceGrid(true), 24);
+ assert.equal(normalizeIrradianceGrid(16), 16);
+ for (const bad of [4, 49, 1.5, 'big', {}]) {
+ assert.throws(() => normalizeIrradianceGrid(bad), /bake\.irradianceGrid/);
+ }
+ assert.equal(normalizeAgentBake({ preset: 'draft' }).irradianceGrid, undefined);
+ assert.equal(normalizeAgentBake({ preset: 'draft', irradianceGrid: true }).irradianceGrid, 24);
+});
+
+test('a warm floor sends warm light to a wall the sun never reaches, and the same input gives the same bytes', () => {
+ const first = traceIrradianceGrid(sunlitRoom(), sun, { resolution: 12, samples: 16, bounces: 2 });
+ const second = traceIrradianceGrid(sunlitRoom(), sun, { resolution: 12, samples: 16, bounces: 2 });
+ assert.deepEqual(Array.from(first.data), Array.from(second.data));
+ const [red, green, blue] = evaluateIrradianceGrid(first, [0, 1.5, -2.8], [0, 0, 1]);
+ assert.ok(red > 0.01 && red / blue > 1.5, `bounced light is warm: ${red} ${green} ${blue}`);
+ const lookingAtFloor = evaluateIrradianceGrid(first, [0, 1.5, 0], [0, -1, 0]);
+ const lookingAtCeiling = evaluateIrradianceGrid(first, [0, 1.5, 0], [0, 1, 0]);
+ assert.ok(lookingAtFloor[0] > lookingAtCeiling[0], 'the lit floor is seen from above, so the downward lobe is brighter');
+});
+
+test('nodes inside a solid are found and filled from their neighbours', () => {
+ const solid = traceIrradianceGrid([placed('block', [0, 0, 0], [4, 4, 4], [0.5, 0.5, 0.5])], sun, { resolution: 9, samples: 4, bounces: 1 });
+ assert.ok(solid.solidNodes > 0 && solid.solidNodes < solid.nodes, `${solid.solidNodes} of ${solid.nodes}`);
+});
+
+test('nodes inside walls are filled and every coefficient is finite', () => {
+ const grid = traceIrradianceGrid(sunlitRoom(), sun, { resolution: 10, samples: 8, bounces: 1 });
+ assert.ok(grid.data.every(Number.isFinite));
+ assert.equal(grid.data.length, grid.nodes * 12);
+});
+
+test('placing the grid wraps each material once and keeps reading the live material', () => {
+ const parts = sunlitRoom();
+ const grid = traceIrradianceGrid(parts, sun, { resolution: 8, samples: 4, bounces: 1 });
+ const wrapped = placeIrradianceGrid(parts, grid);
+ assert.ok(wrapped.every(part => part.material.irradianceGrid === grid));
+ parts[0].material.color = [0.1, 0.2, 0.3];
+ assert.deepEqual(wrapped[0].material.color, [0.1, 0.2, 0.3]);
+});
+
+test('the shader carries the grid code only for a renderer that asks for the feature', () => {
+ assert.match(createFragmentShader(['irradianceGrid']), /irradianceGridDiffuse\(worldPosition, normal\)/);
+ assert.doesNotMatch(createFragmentShader([]), /irradianceGrid/);
+});
+
+test('a recipe with bake.irradianceGrid skips lightmaps, reports the grid and gives every part the grid', () => {
+ const boxNode = (id, translation, scale, material) => ({ id, geometry: 'box', material, translation, scale });
+ const scene = createAgentScene({
+ format: '67js.scene', schemaVersion: 1,
+ geometries: [{ id: 'box', type: 'box' }],
+ materials: [{ id: 'floor', color: [0.8, 0.4, 0.1] }, { id: 'white', color: [0.8, 0.8, 0.8] }],
+ nodes: [
+ boxNode('floor', [0, -0.05, 0], [4, 0.1, 4], 'floor'),
+ boxNode('ceiling', [0, 3.05, 0], [4, 0.1, 4], 'white'),
+ boxNode('back', [0, 1.5, -2.05], [4.2, 3.2, 0.1], 'white'),
+ boxNode('front', [0, 1.5, 2.05], [4.2, 3.2, 0.1], 'white'),
+ boxNode('left', [-2.05, 1.5, 0], [0.1, 3.2, 4.2], 'white'),
+ boxNode('right', [2.05, 1.5, 0], [0.1, 3.2, 4.2], 'white'),
+ ],
+ camera: { eye: [0, 1.5, 1.9], target: [0, 1.4, -2], fov: 70, near: 0.05, far: 20 },
+ environment: { pointLights: [{ position: [0, 2.7, 0], intensity: 14, radius: 0.1 }], keyIntensity: 0, fillIntensity: 0 },
+ bake: { preset: 'draft', irradianceGrid: 10 },
+ });
+ const report = scene.inspect().bake;
+ assert.equal(report.texels, 0);
+ assert.equal(report.irradianceGrid.size.length, 3);
+ assert.ok(report.irradianceGrid.nodes > 0 && report.irradianceGrid.data === undefined);
+ const parts = scene.getParts?.() ?? scene.parts;
+ assert.ok(parts.every(part => part.material.irradianceGrid && !part.material.lightMap));
+});