Skip to content

3D engine that AI agents drive

Leave portal area lights out of the bake, probes and bounce estimate (#2153)

Nguyen Xuan An57eb5a58438a
diff --git a/changes/2153.md b/changes/2153.md
new file mode 100644
index 00000000..639df553
--- /dev/null
+++ b/changes/2153.md
@@ -0,0 +1 @@
+- A portal area light (`portal: true`) no longer lights the light bake, the object reflection probes or the room bounce estimate as if it were a panel, and is no longer named as the strongest light to turn down (#2153).
diff --git a/docs/light-bake.md b/docs/light-bake.md
index c992c65e..8080cfab 100644
--- a/docs/light-bake.md
+++ b/docs/light-bake.md
@@ -52,7 +52,7 @@ const { parts: bakedParts, report } = await bakeLightmapsAsync(parts, lighting,
The bake traces cosine-weighted paths from each texel through up to `bounces` reflections. Each hit adds its own emission and the direct light it receives from the point lights and the sun, with shadow rays. A texel stores that light times its own albedo. Direct light is not baked: it stays live, so shadows and moving lights keep working. The stored light is only what has bounced at least once, so a scene needs the same lights at run time that it gave the bake.
-Spot lights take the cone and soft edge the renderer uses (`angle`, `penumbra`, default 0.15), with `range` and `radius` as for a point light. An area light is a rectangle that emits from its front side only, with the path tracer's `intensity * cosine / distance squared`. A hit is lit by one shadow ray per area light to a point of the rectangle that changes on every call; the sequence is a hash of the call count, so it repeats exactly, and the many paths of a texel average the soft shadow. At most 8 spot and 7 area lights. A scene without spot or area lights bakes the same bytes as before.
+Spot lights take the cone and soft edge the renderer uses (`angle`, `penumbra`, default 0.15), with `range` and `radius` as for a point light. An area light is a rectangle that emits from its front side only, with the path tracer's `intensity * cosine / distance squared`. A hit is lit by one shadow ray per area light to a point of the rectangle that changes on every call; the sequence is a hash of the call count, so it repeats exactly, and the many paths of a texel average the soft shadow. At most 8 spot and 7 area lights. A scene without spot or area lights bakes the same bytes as before. An area light with `portal: true` is a window and emits nothing: the bake, the object reflection probes and the room bounce estimate leave it out, as the raster view does (it adds none of its own light).
Not baked: the environment map (it already lights every surface at run time) and specular reflection. A metal part reflects no baked light. Fresnel and sheen are ignored.
diff --git a/src/area-light-portal.js b/src/area-light-portal.js
new file mode 100644
index 00000000..2e3dbdbc
--- /dev/null
+++ b/src/area-light-portal.js
@@ -0,0 +1,7 @@
+// A portal area light (#1948) marks a window: it emits nothing and only lets sky light in. Everything that sums or traces the light a
+// panel gives off (light bake, object reflection probes, the room bounce estimate, the strongest-light list) works on this list.
+
+/** The area lights that give off light of their own: the list without its portals. Keeps the order. */
+export function emittingAreaLights(areaLights) {
+ return (areaLights ?? []).filter(light => light.portal !== true);
+}
diff --git a/src/frame-checks.js b/src/frame-checks.js
index 83a2d153..3fbd694f 100644
--- a/src/frame-checks.js
+++ b/src/frame-checks.js
@@ -162,6 +162,7 @@ export function strongestLights(environment) {
const lights = [{ field: 'environment.keyIntensity', intensity: environment.keyIntensity ?? 1 }];
for (const listName of ['pointLights', 'spotLights', 'areaLights']) {
(environment[listName] ?? []).forEach((light, index) => {
+ if (light.portal === true) return;
lights.push({ field: `environment.${listName}[${index}].intensity`, intensity: light.intensity ?? 1 });
});
}
diff --git a/src/ground-bounce.js b/src/ground-bounce.js
index 0d6e4d0d..30edec6e 100644
--- a/src/ground-bounce.js
+++ b/src/ground-bounce.js
@@ -1,6 +1,7 @@
import { computeIrradianceCoefficients, createEnvironmentMap, evaluateIrradiance } from './environment.js'
import { CLOSED_ROOM_SHARE, closedRoomShare, partMatrixLookup } from './closed-room.js'
import { worldBounds } from './probe-trace.js'
+import { emittingAreaLights } from './area-light-portal.js'
// The ground of a scene is its floor: a part that spans the scene (the same test as the automatic floor of agent scenes),
// is thin and is the lowest geometry. Its albedo comes from its material.
@@ -238,7 +239,7 @@ function lightFlux(environment, room) {
}
for (const light of environment.pointLights ?? []) add(light, FULL_SPHERE)
for (const light of environment.spotLights ?? []) add(light, 2 * Math.PI * (1 - Math.cos(light.angle ?? Math.PI / 4)))
- for (const light of environment.areaLights ?? []) add(light, Math.PI)
+ for (const light of emittingAreaLights(environment.areaLights)) add(light, Math.PI)
return flux
}
@@ -315,7 +316,7 @@ function roomBounceEnvironment(parts, environment) {
// it would not count, so it would take the sky's own light away from the lower half and darken the scene (measured on
// `light-linking` and `spot-area`).
function hasLocalLights(environment) {
- return [environment.pointLights, environment.spotLights, environment.areaLights].some(lights => lights?.length > 0)
+ return [environment.pointLights, environment.spotLights, emittingAreaLights(environment.areaLights)].some(lights => lights?.length > 0)
}
// Under a low sun a shadow is lit by more than the sky and the level ground: slopes, walls and roofs that face the sun send
diff --git a/src/light-bake.js b/src/light-bake.js
index 517be178..2e83fbe1 100644
--- a/src/light-bake.js
+++ b/src/light-bake.js
@@ -1,4 +1,5 @@
import { invalidField } from './field-error.js';
+import { emittingAreaLights } from './area-light-portal.js';
import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from './light-limits.js';
import { buildTriangleBvh } from './triangle-bvh.js';
import { readTriangle } from './triangle-math.js';
@@ -168,7 +169,7 @@ export function normalizeLights(lighting) {
return { position: Array.from(light.position), color: Array.from(light.color ?? [1, 1, 1]), intensity: light.intensity, range, radius };
});
const spotSources = lighting.spotLights ?? [];
- const areaSources = lighting.areaLights ?? [];
+ const areaSources = emittingAreaLights(lighting.areaLights);
const spotLights = withAffects(normalizeSpotLights(spotSources), spotSources);
const areaLights = withAffects(normalizeAreaLights(areaSources), areaSources);
const keyColor = lighting.keyColor ?? [0, 0, 0];
diff --git a/tests/area-light-portal-bake.test.js b/tests/area-light-portal-bake.test.js
new file mode 100644
index 00000000..d635a75f
--- /dev/null
+++ b/tests/area-light-portal-bake.test.js
@@ -0,0 +1,82 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { box, sphere } from '../src/geometry.js';
+import { createEnvironmentMap } from '../src/environment.js';
+import { bakeLightmaps } from '../src/light-bake.js';
+import { traceObjectProbes } from '../src/probe-trace.js';
+import { groundBounceEnvironment } from '../src/ground-bounce.js';
+import { strongestLights } from '../src/frame-checks.js';
+import { emittingAreaLights } from '../src/area-light-portal.js';
+
+const cube = box(0, 1);
+const ball = sphere(16, 12);
+
+function placed(name, geometry, translation, scale, material = {}) {
+ 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, matrix, material: { tag: 'surface', color: [0.7, 0.7, 0.7], metallic: 0, roughness: 0.8, emission: 0, ...material } };
+}
+
+// A closed 6 m room; the mirror ball gives the probe test a reflective part.
+function closedRoom() {
+ return [
+ placed('floor', cube, [0, -0.05, 0], [6, 0.1, 6]),
+ placed('ceiling', cube, [0, 3.05, 0], [6, 0.1, 6]),
+ placed('back', cube, [0, 1.5, -3.05], [6, 3.2, 0.1]),
+ placed('left', cube, [-3.05, 1.5, 0], [0.1, 3.2, 6]),
+ placed('right', cube, [3.05, 1.5, 0], [0.1, 3.2, 6]),
+ placed('front', cube, [0, 1.5, 3.05], [6, 3.2, 0.1]),
+ placed('mirror', ball, [1.5, 0.5, 0], [0.5, 0.5, 0.5], { metallic: 1, roughness: 0.05 }),
+ ];
+}
+
+const window = { position: [0, 2.9, 0], direction: [0, -1, 0], up: [0, 0, 1], width: 1, height: 1, color: [1, 1, 1], intensity: 20 };
+const bakeOptions = { samples: 8, bounces: 1, texelsPerUnit: 2, maxResolution: 32 };
+
+function byteSum(bake) {
+ return bake.parts.reduce((total, part) => total + (part.material.emissiveMap?.image.data.reduce((sum, byte) => sum + byte, 0) ?? 0), 0);
+}
+
+test('emittingAreaLights drops portals and keeps the order', () => {
+ const lamp = { ...window, intensity: 3 };
+ assert.deepEqual(emittingAreaLights([lamp, { ...window, portal: true }, lamp]), [lamp, lamp]);
+ assert.deepEqual(emittingAreaLights(undefined), []);
+});
+
+test('a portal adds no light to a bake: a closed room with only a portal bakes like a room with no light', () => {
+ const dark = byteSum(bakeLightmaps(closedRoom(), { keyColor: [0, 0, 0] }, bakeOptions));
+ const portal = byteSum(bakeLightmaps(closedRoom(), { areaLights: [{ ...window, portal: true }], keyColor: [0, 0, 0] }, bakeOptions));
+ const panel = byteSum(bakeLightmaps(closedRoom(), { areaLights: [window], keyColor: [0, 0, 0] }, bakeOptions));
+ assert.equal(portal, dark);
+ assert.ok(panel > portal * 2 + 1000, `a normal panel lights the room (${panel}) and a portal does not (${portal})`);
+});
+
+test('a portal beside a lamp leaves the lamp unchanged in the bake', () => {
+ const lamp = { pointLights: [{ position: [-1.5, 2.5, 0], color: [1, 1, 1], intensity: 8, radius: 0.05 }], keyColor: [0, 0, 0] };
+ const lampOnly = byteSum(bakeLightmaps(closedRoom(), lamp, bakeOptions));
+ const withPortal = byteSum(bakeLightmaps(closedRoom(), { ...lamp, areaLights: [{ ...window, portal: true }] }, bakeOptions));
+ assert.equal(withPortal, lampOnly);
+});
+
+test('object reflection probes do not see a portal as a lamp', () => {
+ const trace = areaLights => traceObjectProbes(closedRoom(), { areaLights, keyColor: [0, 0, 0] }, { width: 32, samples: 8, bounces: 1 }).traced[0].data;
+ const checksum = data => Array.from(data).reduce((sum, value) => sum + value, 0);
+ const none = checksum(trace([]));
+ assert.equal(checksum(trace([{ ...window, portal: true }])), none);
+ assert.ok(checksum(trace([window])) > none, 'a normal panel brightens the probe');
+});
+
+test('the room bounce estimate counts a normal panel and not a portal', () => {
+ const sky = createEnvironmentMap({ width: 8, height: 4, data: new Float32Array(8 * 4 * 3).fill(0.5) });
+ const environment = areaLights => ({ map: sky, keyColor: [0, 0, 0], lightDirection: [0, 1, 0], areaLights });
+ const room = closedRoom().slice(0, 6);
+ const portalOnly = environment([{ ...window, portal: true }]);
+ assert.equal(groundBounceEnvironment(room, portalOnly), portalOnly, 'a closed room with a portal has no light of its own to bounce');
+ const lit = groundBounceEnvironment(room, environment([window]));
+ assert.notEqual(lit, undefined);
+ assert.ok(lit.map.bounce?.some(channel => channel > 0), 'a normal panel gives the walls a bounce colour');
+});
+
+test('strongestLights never names a portal as the light to turn down', () => {
+ const lights = strongestLights({ keyIntensity: 1, areaLights: [{ intensity: 90, portal: true }, { intensity: 5 }] });
+ assert.deepEqual(lights.map(light => light.field), ['environment.areaLights[1].intensity', 'environment.keyIntensity']);
+});