3D engine that AI agents drive
Derive an unset fog shadowAmbient from how open the sky is (part of #165)
Nguyen Xuan An75849e553d0d
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex 9f1de051..4d56d490 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -613,7 +613,7 @@ Single constants tried on the GPU render of the five fog scenes (the whole frame| glow weight 0.004 | 0.1942 | 0.1093 | 0.0644 | 0.0735 | 0.2474 || glow only from pixels above 1.0, weight 0.02 | 0.2002 | 0.1144 | 0.0665 | 0.0722 | 0.2672 |-Every global value trades a room against the open ground. The floor is now the fog field `shadowAmbient` (default 0.15, so every recipe and scene keeps its picture), and `fog-valley` sets 1: open ground under a sky is lit by the whole sky in shadow too. On the GPU render the valley goes 0.1967, 0.1915 (floor 0.4), 0.1883 (0.6) and 0.1855 (1.0) as the floor rises; the 0.6 and 1.0 renders were measured with two runs overlapping, so only the 1.0 value is kept, and the full run below was made alone.+Every global value trades a room against the open ground. The floor is now the fog field `shadowAmbient`. Left unset it is derived: 32 upward rays from the middle of the fog box give the share that escapes the geometry, and the floor runs from 0.15 (closed room) to 1 (open sky), so `fog-valley` sets nothing and still gets 1 (the stored-Blender rerun with the hand-set value removed: valley 0.1855, `dark-shaft` 0.0619 to 0.0607, `fog` 0.2257 to 0.2243, `temple-hall` 0.0659 to 0.0674, every other scene identical to four places). Open ground under a sky is lit by the whole sky in shadow too. On the GPU render the valley goes 0.1967, 0.1915 (floor 0.4), 0.1883 (0.6) and 0.1855 (1.0) as the floor rises; the 0.6 and 1.0 renders were measured with two runs overlapping, so only the 1.0 value is kept, and the full run below was made alone.Full suite, `npm run reference -- --skip-blender` on the stored Cycles and EEVEE arrays (RTX 3060, GPU and CPU renders):diff --git a/bench/reference/harness.js b/bench/reference/harness.jsindex 2f2d2c39..02ec023e 100644--- a/bench/reference/harness.js+++ b/bench/reference/harness.js@@ -5,6 +5,7 @@ import { GRAND_SCENES } from './grand-scenes.js';import { skinnedGeometry } from '/src/path-tracer-scene.js';import { boxProjectedGeometry } from '/src/export-box-uv.js';import '/src/material-layer-shaders.js';+import { skyOpenness } from '/src/closed-room.js';import { createCascadedShadows } from '/src/cascaded-shadows.js';import { applyLightLinks } from '/src/light-linking.js';import { applyWaterReflection, attachWaterReflection } from '/src/water-reflection.js';@@ -138,7 +139,7 @@ function createSceneRenderer(parts, scene, cascades, { water = WATER_REFLECTIONconst reflecting = water === 'planar' ? applyWaterReflection(parts) : { parts, surface: null };const renderer = new Renderer67(document.querySelector('canvas'), applyLightLinks(reflecting.parts, scene.environment), {ground: false, hdr: true, depth: true, samples: 4, pixelRatio: 1, memoryBudgetMiB: 1024, world: true,- environment: scene.environment, shadowBounds: scene.shadow, shadowCascades: cascades ? createCascadedShadows({ count: cascades }) : null,+ environment: scene.environment, shadowBounds: scene.shadow, shadowCascades: cascades ? createCascadedShadows({ count: cascades }) : null, skyOpenness,});attachWaterReflection(renderer, reflecting.surface);if (water === 'ssr') {diff --git a/bench/reference/scenes.js b/bench/reference/scenes.jsindex 9c01b2eb..6d11da2f 100644--- a/bench/reference/scenes.js+++ b/bench/reference/scenes.js@@ -455,7 +455,7 @@ async function fogValleyScene() {const lighting = await skyLighting();const volumeFog = {density: 0.005, minimum: [-300, 0, -450], maximum: [300, 90, 40],- color: [1, 1, 1], ambient: lighting.meanRadiance, shadowAmbient: 1, anisotropy: 0.4, noiseAmount: 0, steps: 48, maxDistance: 600,+ color: [1, 1, 1], ambient: lighting.meanRadiance, anisotropy: 0.4, noiseAmount: 0, steps: 48, maxDistance: 600,};return {parts, blenderWorld: lighting.blenderWorld,diff --git a/bench/size/budgets.json b/bench/size/budgets.jsonindex 206a037a..f35d3cd0 100644--- a/bench/size/budgets.json+++ b/bench/size/budgets.json@@ -47,7 +47,7 @@"scene:lit-box": 62800,"scene:gltf-box": 84200,"scene:gltf-box+lazy": 87600,- "scene:agent-scene": 104100,- "scene:agent-scene+lazy": 286000+ "scene:agent-scene": 104200,+ "scene:agent-scene+lazy": 286200}}diff --git a/changes/issue-165-fog-default.md b/changes/issue-165-fog-default.mdnew file mode 100644index 00000000..cccefbe2--- /dev/null+++ b/changes/issue-165-fog-default.md@@ -0,0 +1 @@+- An unset `volumeFog.shadowAmbient` is now derived from the scene instead of fixed at 0.15. Pass `skyOpenness` from `src/closed-room.js` to `Renderer67` (the agent preview and the reference harness do) and it shoots 32 upward rays from the middle of the fog box, once per scene and fog box: a closed room keeps 0.15, open ground under a sky gets 1, a partly covered scene lands between. Without the option an unset value stays 0.15, so existing renderers draw as before. A recipe that sets the value keeps it, and the recipe echo no longer lists `shadowAmbient` when it was unset. The `fog-valley` reference scene no longer sets it and scores the same 0.1855 against Cycles (EEVEE 0.1952); `dark-shaft` and `fog` move by 0.0012 and 0.0014 (better) and `temple-hall` by 0.0015 (worse), the rest are unchanged (part of issue #165).diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 1de74e67..fa29db99 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -179,7 +179,7 @@ These controls reuse `resolveVolumeFog` and its existing domain rules.| `noiseAmount` | `0.5` | `0` to `1` || `noiseScale` | `0.3` | `0.001` to `100` || `maxDistance` | `100` | `0.01` to `10000` |-| `shadowAmbient` | `0.15` | `0` to `1` |+| `shadowAmbient` | derived from the scene: 0.15 in a closed room, 1 under open sky | `0` to `1` |Fog bounds reject dimensions that collapse after Float32 rounding.The current volume supports one directional scattering source.diff --git a/docs/volumetric.md b/docs/volumetric.mdindex 762971ec..d9e99b7b 100644--- a/docs/volumetric.md+++ b/docs/volumetric.md@@ -41,7 +41,7 @@ renderer.render({ eye: [0, 2, 5], target: [0, 1, 0], time: 0 });| `noiseScale` | `0.3` | `0.001…100`, inverse scene units || `drift` | `[0.03, 0, 0]` | Three components within ±100, scene units per second || `maxDistance` | `100` | `0.01…10,000`, ray distance in scene units |-| `shadowAmbient` | `0.15` | `0…1`; the share of `ambient` the fog keeps where the sun's shadow covers it. A closed room sees little sky (0.15); open ground under a sky sees all of it (1) |+| `shadowAmbient` | derived | `0…1`; the share of `ambient` the fog keeps where the sun's shadow covers it. Left unset, 32 upward rays from the middle of the fog box decide: a closed room keeps 0.15, open ground under a sky keeps 1, and a partly covered scene lands between. Set it to override |Values must be finite numbers. Active volume fog accepts finite frame time within ±1,000,000 seconds and a nonzero light direction with components within ±1,000,000. Noise samples absolute time, so backward seeks reproduce earlier density.diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex 63cc97e9..cfd49e1e 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -1,6 +1,7 @@import { buildWithKernels, kernelWorkersAvailable, kernelStats, resetKernelStats } from '../src/kernel-offload.js';import { createAgentScene, loadAllAgentSceneModules, allAgentSceneModulesLoaded, needsMeshBooleans, loadMeshBooleans, meshBooleansLoaded, setManifoldModuleLoader, needsPhysics, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader } from '../src/agent-scene.js';import { Renderer67 } from '../src/renderer.js';+import { skyOpenness } from '../src/closed-room.js';import { installCameraEffects } from '../src/camera-effects.js';import { installRenderPasses } from '../src/render-passes.js';import { applyProjection } from '../src/camera.js';@@ -216,6 +217,7 @@ function initializeRenderer(scene, { memoryBudgetMiB, backend }) {environment: { ...scene.environment, map: agentEnvironmentMap(scene.environment) },shadowBounds: resolveAgentShadow(scene.shadow, scene.environment.lightDirection),shadowCascades: cascadesFor(scene),+ skyOpenness,pixelRatio: 1,samples: backend === 'cpu' ? 1 : 4,memoryBudgetMiB,diff --git a/src/closed-room.js b/src/closed-room.jsindex 9d5dbb0f..cbb0c16c 100644--- a/src/closed-room.js+++ b/src/closed-room.js@@ -99,3 +99,32 @@ export function closedRoomShare(parts, worldMatrices) {}return hits / CLOSED_ROOM_RAYS;}++export const SKY_OPENNESS_RAYS = 32;++/**+ * The share of upward rays from `point` that leave the parts without hitting a part's underside, or null when the scene is+ * empty or too large to test. 1 is open ground under the sky, 0 is a closed room. Pass it to `Renderer67` as the+ * `skyOpenness` option and an unset `volumeFog.shadowAmbient` follows it. The rays are the upper half of the same fixed+ * spiral, so the same scene gives the same share.+ */+export function skyOpenness(parts, point) {+ const worldMatrices = new Map(parts.map(part => [part.name, part.matrix]));+ const triangles = worldTriangles(parts.filter(part => part.material?.alphaMode !== 'blend'), worldMatrices);+ if (!triangles) {+ return null;+ }+ const direction = [0, 0, 0];+ let escaped = 0;+ for (let ray = 0; ray < SKY_OPENNESS_RAYS; ray++) {+ fibonacciDirection(ray, SKY_OPENNESS_RAYS * 2, direction);+ let blocked = false;+ for (let triangle = 0; triangle < triangles.triangleCount && !blocked; triangle++) {+ blocked = hitsFrontFace(triangles.corners, triangle * 9, point, direction);+ }+ if (!blocked) {+ escaped++;+ }+ }+ return escaped / SKY_OPENNESS_RAYS;+}diff --git a/src/renderer.js b/src/renderer.jsindex b69f8050..da19a36d 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -8,7 +8,7 @@ import { applyProjection } from './camera.js';import { resolveEffects } from './effects.js';import { createLightingState, updateLightingState } from './lighting.js';import { SHADOW_ATLAS_WIDTH, SHADOW_ATLAS_HEIGHT, tileViewport, writeShadowTile } from './local-shadows.js';-import { resolveVolumeFog } from './volumetric.js';+import { resolveVolumeFog, volumeShadowAmbient } from './volumetric.js';import { assertEnvironmentMap, createEnvironmentResources, environmentBackgroundFragment, environmentBrdfFragment, environmentPrefilterFragment, estimateEnvironmentBytes } from './environment.js';import { validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences } from './skinning.js';import { validateSplatMaterial, splatBatchState, splatTextureBytes, resolveSplatSize, packSplatParameters, buildSplatPixels } from './splat.js';@@ -410,8 +410,11 @@ function allFinite(values) {}export class Renderer67 {- constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, depth = false, memoryBudgetMiB = 256, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null } = {}) {+ constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, depth = false, memoryBudgetMiB = 256, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null, skyOpenness = null } = {}) {this.canvas = canvas;+ this.sceneParts = parts;+ // `skyOpenness` from closed-room.js is passed in, which keeps the ray code out of scenes without volume fog.+ this.skyOpenness = skyOpenness;// `createGpuTimer` from adaptive-quality.js is passed in, which keeps the timer code out of scenes that do not time frames.this.createGpuTimer = createGpuTimer;this.gpuTimer = undefined;@@ -1683,7 +1686,7 @@ export class Renderer67 {context.uniform3fv(post.uniforms.volumeDrift, volume.drift);context.uniform1i(post.uniforms.volumeSteps, volume.steps);context.uniform1f(post.uniforms.volumeAnisotropy, volume.anisotropy);- context.uniform1f(post.uniforms.volumeShadowAmbient, volume.shadowAmbient);+ context.uniform1f(post.uniforms.volumeShadowAmbient, volumeShadowAmbient(volume, this.sceneParts, this.skyOpenness));context.uniform1f(post.uniforms.volumeNoiseAmount, volume.noiseAmount);context.uniform1f(post.uniforms.volumeNoiseScale, volume.noiseScale);context.uniform1f(post.uniforms.volumeMaxDistance, volume.maxDistance);diff --git a/src/volumetric.js b/src/volumetric.jsindex 3b03194a..beace050 100644--- a/src/volumetric.js+++ b/src/volumetric.js@@ -34,6 +34,33 @@ export function resolveVolumeFog(input = {}) {const noiseAmount = finiteRange(input.noiseAmount ?? 0.5, 0, 1, 'Volume noise amount');const noiseScale = finiteRange(input.noiseScale ?? 0.3, 0.001, 100, 'Volume noise scale');const maxDistance = finiteRange(input.maxDistance ?? 100, 0.01, 1e4, 'Volume maximum distance');- const shadowAmbient = finiteRange(input.shadowAmbient ?? 0.15, 0, 1, 'Volume shadow ambient');- return { density, minimum, maximum, color, ambient, drift, steps, anisotropy, noiseAmount, noiseScale, maxDistance, shadowAmbient };+ const resolved = { density, minimum, maximum, color, ambient, drift, steps, anisotropy, noiseAmount, noiseScale, maxDistance };+ // Left out when unset, so the renderer can derive it from the scene (volumeShadowAmbient).+ if (input.shadowAmbient !== undefined) {+ resolved.shadowAmbient = finiteRange(input.shadowAmbient, 0, 1, 'Volume shadow ambient');+ }+ return resolved;+}++const derivedShadowAmbients = new WeakMap();++/**+ * The share of the fog's ambient that survives in the sun's shadow. A set value wins. Otherwise it follows how open the sky is+ * from the middle of the fog: a closed room keeps 0.15, open ground under the sky keeps all of it.+ * `measureOpenness(parts, point)` is the `skyOpenness` option of the renderer (src/closed-room.js), kept out of the core+ * bundle; without it, or for a scene too large to test, the scene counts as enclosed. It runs once per scene and fog box.+ */+export function volumeShadowAmbient(volume, parts, measureOpenness) {+ if (volume.shadowAmbient !== undefined) {+ return volume.shadowAmbient;+ }+ const key = `${volume.minimum}|${volume.maximum}`;+ const cached = derivedShadowAmbients.get(parts);+ if (cached?.key === key) {+ return cached.value;+ }+ const centre = volume.minimum.map((low, axis) => (low + volume.maximum[axis]) / 2);+ const value = 0.15 + 0.85 * (measureOpenness?.(parts, centre) ?? 0);+ derivedShadowAmbients.set(parts, { key, value });+ return value;}diff --git a/tests/support/preview-harness.mjs b/tests/support/preview-harness.mjsindex 7819a415..5323d779 100644--- a/tests/support/preview-harness.mjs+++ b/tests/support/preview-harness.mjs@@ -75,7 +75,7 @@ export function previewHarness() {needsPhysics, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader: () => {},parseGltf, Uint8Array, atob, sessionProblem,applyProjection, mat4, resolveAgentShadow, agentEnvironmentMap, agentSceneModule, BRANCH_LIMITS, createBranchStore, printableLabel,- Renderer67: FaultInjectedRenderer,+ Renderer67: FaultInjectedRenderer, skyOpenness: () => 1,// The fault-injected renderer has no floor part; the automatic floor is covered by agent-ground.test.js and the live smokes.agentGroundPlacement: () => null, createAgentGround: () => null, placeAgentGround: () => {},// The optional addons only plug stages into a real renderer; the fault-injected one needs none.diff --git a/tests/volumetric.test.js b/tests/volumetric.test.jsindex 449d9e9b..3e71f11b 100644--- a/tests/volumetric.test.js+++ b/tests/volumetric.test.js@@ -1,6 +1,7 @@import test from 'node:test';import assert from 'node:assert/strict';-import { resolveVolumeFog } from '../src/volumetric.js';+import { skyOpenness } from '../src/closed-room.js';+import { resolveVolumeFog, volumeShadowAmbient } from '../src/volumetric.js';import { Renderer67 } from '../src/renderer.js';test('bounded volume controls default disabled and preserve ordinary input data', () => {@@ -21,8 +22,26 @@ test('volume preflight rejects malformed controls and Float32 collapsed bounds',assert.throws(() => new Renderer67({}, [], { hdr: true, depth: true, transparent: true, environment: { volumeFog: { density: 0.1 } } }), /opaque/);});-test('volume shadow ambient defaults to the closed room share and accepts the full range', () => {- assert.equal(resolveVolumeFog({ density: 0.1 }).shadowAmbient, 0.15);+test('volume shadow ambient stays unset until the renderer derives it, and accepts the full range', () => {+ assert.equal(resolveVolumeFog({ density: 0.1 }).shadowAmbient, undefined);assert.equal(resolveVolumeFog({ density: 0.1, shadowAmbient: 1 }).shadowAmbient, 1);assert.equal(resolveVolumeFog({ density: 0.1, shadowAmbient: 0 }).shadowAmbient, 0);});++function flatPart(name, height, facesDown) {+ const half = 50;+ const corners = [-half, height, -half, half, height, -half, half, height, half, -half, height, half];+ const indices = facesDown ? [0, 1, 2, 0, 2, 3] : [0, 2, 1, 0, 3, 2];+ const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];+ return { name, geometry: { positions: new Float32Array(corners), indices: new Uint32Array(indices) }, matrix: identity };+}++test('an unset volume shadow ambient follows how open the sky is above the fog', () => {+ const fog = resolveVolumeFog({ density: 0.1, minimum: [-4, 0, -4], maximum: [4, 2, 4] });+ const floor = flatPart('floor', 0, false);+ const room = [floor, flatPart('ceiling', 3, true)];+ assert.equal(volumeShadowAmbient(fog, [floor], skyOpenness), 1);+ assert.ok(volumeShadowAmbient(fog, room, skyOpenness) < 0.3, 'a ceiling over the fog leaves almost nothing open');+ assert.equal(volumeShadowAmbient({ ...fog, shadowAmbient: 0.6 }, room, skyOpenness), 0.6);+ assert.equal(volumeShadowAmbient(fog, [floor]), 0.15, 'without a measure the scene counts as enclosed');+});