3D engine that AI agents drive
Bake report names the local volumes the lightmap bake leaves out (#809)
Nguyen Xuan Anf61c0420c5a2
diff --git a/changes/809-volume-bake.md b/changes/809-volume-bake.mdnew file mode 100644index 00000000..a54940ed--- /dev/null+++ b/changes/809-volume-bake.md@@ -0,0 +1 @@+- The bake report names the `environment.localVolumes` the lightmap bake leaves out (`skippedLocalVolumes` and a `warnings` line), and the volumes guide states that a volume emission does not light baked surfaces (#809).diff --git a/changes/809-volume-bake.size.md b/changes/809-volume-bake.size.mdnew file mode 100644index 00000000..0c990d93--- /dev/null+++ b/changes/809-volume-bake.size.md@@ -0,0 +1 @@+- scene:agent-scene+lazy: the bake report names the local volumes it leaves out, which an agent otherwise cannot tell from a missing glow (228 bytes gzip).diff --git a/docs/volumetric.md b/docs/volumetric.mdindex afc9108e..4b5e71e8 100644--- a/docs/volumetric.md+++ b/docs/volumetric.md@@ -127,7 +127,7 @@ In a scene with an irradiance grid (`bake.irradianceGrid`) the bounce term is th| `noiseAmount`, `noiseScale` | `0`, `1` | Raster only. `noiseAmount` `0` to `1` breaks the density up with the cloud noise at `noiseScale` cells per unit || `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. 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 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.### Reference render and frame time@@ -135,4 +135,4 @@ Each volume is marched on its own between its entry and its exit, cut at the fir### Not covered yet-Mesh bounds as a shape, the WebGPU and WebGL path tracers, the lightmap bake and path tracer noise are open work: mesh bounds #807, tracer noise and GPU tracers #808, the bake #809.+Mesh bounds as a shape, the WebGPU and WebGL path tracers and path tracer noise are open work: mesh bounds #807, tracer noise and GPU tracers #808. Lighting baked surfaces from a volume's emission is not planned (#809): the bake reports the limit instead.diff --git a/src/agent-bake.js b/src/agent-bake.jsindex 8d9136a8..d08c3d5d 100644--- a/src/agent-bake.js+++ b/src/agent-bake.js@@ -297,6 +297,25 @@ export function changedPartsOf(bakedParts, snapshots) {* rayWork, seconds, skipped parts with reasons.*/export function bakeAgentParts(parts, worldMatrices, environment, settings, generatedGeometryGenerators = new Map()) {+ const baked = traceAgentBake(parts, worldMatrices, environment, settings, generatedGeometryGenerators);+ const skippedVolumes = skippedLocalVolumes(environment.localVolumes);+ if (skippedVolumes.length === 0) {+ return baked;+ }+ return { ...baked, report: { ...baked.report, skippedLocalVolumes: skippedVolumes, warnings: [localVolumesNotBakedWarning(skippedVolumes)] } };+}++// Local volumes are drawn in the post pass and have no place in a lightmap, so the bake leaves them out; the report names them.+function skippedLocalVolumes(localVolumes) {+ return (localVolumes ?? []).map((volume, index) => ({ index, shape: volume.shape, emissive: volume.emissionStrength > 0 && volume.emission.some(channel => channel > 0) }));+}++function localVolumesNotBakedWarning(skippedVolumes) {+ const names = skippedVolumes.map(volume => `environment.localVolumes[${volume.index}] (${volume.shape}${volume.emissive ? ', emissive' : ''})`).join(', ');+ return `The bake leaves out ${names}: local volumes are drawn in the post pass, so an emissive volume does not light baked surfaces and no volume dims the baked light. Light the surfaces with a point light or an emissive part.`;+}++function traceAgentBake(parts, worldMatrices, environment, settings, generatedGeometryGenerators) {const sunScale = environment.keyIntensity ?? 1;const lighting = {pointLights: environment.pointLights,diff --git a/tests/agent-bake.test.js b/tests/agent-bake.test.jsindex f423e43a..cf83f907 100644--- a/tests/agent-bake.test.js+++ b/tests/agent-bake.test.js@@ -86,3 +86,23 @@ test('a failed bake leaves the scene as it was', () => {assert.equal(scene.revision, 0);assert.equal(scene.inspect().bake.samples, BAKE_PRESETS.draft.samples);});++test('a bake names the local volumes it leaves out and a scene without volumes reports as before', () => {+ const plain = createAgentScene(closedRoom()).inspect().bake;+ assert.equal(plain.skippedLocalVolumes, undefined);+ assert.equal(plain.warnings, undefined);++ const recipe = closedRoom();+ recipe.environment.localVolumes = [+ { shape: 'sphere', center: [0, 1, 0], radius: 0.5, emission: [1, 0.6, 0.2] },+ { shape: 'box', center: [1, 1, 0], size: [1, 1, 1] },+ ];+ const volumed = createAgentScene(recipe).inspect().bake;+ assert.deepEqual(volumed.skippedLocalVolumes, [+ { index: 0, shape: 'sphere', emissive: true },+ { index: 1, shape: 'box', emissive: false },+ ]);+ assert.equal(volumed.warnings.length, 1);+ assert.match(volumed.warnings[0], /localVolumes\[0\] \(sphere, emissive\), environment\.localVolumes\[1\] \(box\)/);+ assert.equal(volumed.texels, plain.texels);+});