3D engine that AI agents drive
Fog: opt-in multiple scattering octaves and sun transmittance, bench flags for component splits (issue #543)
Nguyen Xuan Anae8fb6d64d64
diff --git a/bench/reference/light-components.py b/bench/reference/light-components.pyindex 4da212ea..f0a08059 100644--- a/bench/reference/light-components.py+++ b/bench/reference/light-components.py@@ -162,4 +162,5 @@ def main():print("\n".join(lines))-main()+if __name__ == "__main__":+ main()diff --git a/bench/reference/run.mjs b/bench/reference/run.mjsindex 305837ac..c76c48d8 100644--- a/bench/reference/run.mjs+++ b/bench/reference/run.mjs@@ -107,7 +107,10 @@ const ambient = ambientFlag >= 0 ? Number(argumentsGiven[ambientFlag + 1]) : nulconst keyFlag = argumentsGiven.indexOf('--key');const keyScale = keyFlag >= 0 ? Number(argumentsGiven[keyFlag + 1]) : null;const fogDensityFlag = argumentsGiven.indexOf('--fog-density');-const fogDensity = fogDensityFlag >= 0 ? { density: Number(argumentsGiven[fogDensityFlag + 1]) } : null;+// --fog-set name=value,name=value replaces any other volume fog fields, for example scatterOctaves=3,keyTransmittance=1.+const fogSetFlag = argumentsGiven.indexOf('--fog-set');+const fogSet = fogSetFlag >= 0 ? Object.fromEntries(argumentsGiven[fogSetFlag + 1].split(',').map(pair => pair.split('=')).map(([name, value]) => [name, Number(value)])) : {};+const fogDensity = fogDensityFlag >= 0 || fogSetFlag >= 0 ? { ...fogSet, ...(fogDensityFlag >= 0 ? { density: Number(argumentsGiven[fogDensityFlag + 1]) } : {}) } : null;const pathTracerFlag = argumentsGiven.includes('--path-tracer');const samplesFlag = argumentsGiven.indexOf('--samples');const pathTracerSamples = samplesFlag >= 0 ? Number(argumentsGiven[samplesFlag + 1]) : 64;@@ -123,7 +126,7 @@ const sceneIdsGiven = lookIds ?? (sceneFlag >= 0 ? argumentsGiven[sceneFlag + 1]// The fresh bake.json lands in the work directory and is checked against the committed one (compare-scores.mjs); --update-baseline replaces// the committed bake.json and images/<id>-baked.jpg with it.const bakeScoreRun = bakedSceneIds !== null && !sceneSet && !pathTracerFlag;-const bakeVariantFlags = ['--no-glossy', '--sky-only', '--bake-preset', '--bake-grid', '--bake-grid-fog', '--no-bake-worker', '--bake-bounces', '--bake-backend', '--bake-samples', '--bake-density', '--probes', '--ambient', '--key', '--fog-density', '--ambient-occlusion', '--cascades', '--no-object-probes', '--object-probes', '--no-water', '--ssr-water', '--no-ground-bounce', '--floor-sky', '--floor-sky-rooms', '--no-floor-sky'];+const bakeVariantFlags = ['--no-glossy', '--sky-only', '--bake-preset', '--bake-grid', '--bake-grid-fog', '--no-bake-worker', '--bake-bounces', '--bake-backend', '--bake-samples', '--bake-density', '--probes', '--ambient', '--key', '--fog-density', '--fog-set', '--ambient-occlusion', '--cascades', '--no-object-probes', '--object-probes', '--no-water', '--ssr-water', '--no-ground-bounce', '--floor-sky', '--floor-sky-rooms', '--no-floor-sky'];const bakeScoreIsBaseline = bakeScoreRun && argumentsGiven.includes('--update-baseline') && !bakeVariantFlags.some(flag => argumentsGiven.includes(flag));const onlyScenes = sceneIdsGiven ?? (bakeScoreRun ? bakedSceneIds : null);const skipCpu = skipCpuFlag || bakeScoreRun || Boolean(viewTransform);diff --git a/changes/543-multiscatter.md b/changes/543-multiscatter.mdnew file mode 100644index 00000000..5f650a03--- /dev/null+++ b/changes/543-multiscatter.md@@ -0,0 +1 @@+- Volume fog: opt-in `scatterOctaves`, `multiScatter`, `multiExtinction`, `multiAnisotropy`, `keyTransmittance` and `surfaceTransmittance` approximate multiple scattering of the sun in the haze and dim the sun by the haze between it and a point or surface. Off by default; the scenes without them render the same (#543)diff --git a/changes/543-multiscatter.size.md b/changes/543-multiscatter.size.mdnew file mode 100644index 00000000..dbbc5ff7--- /dev/null+++ b/changes/543-multiscatter.size.md@@ -0,0 +1,3 @@+- entry:fog-shader: the opt-in multiple scattering octaves and sun transmittance add one function set to the lazy fog shader (636 bytes gzip); a frame without volume fog never loads it.+- scene:agent-scene+lazy: the fog shader's opt-in multiple scattering and sun transmittance, measured against Cycles in #543; off by default.+- goal:agent-scene: six validated volume fog fields in agent-look (30 bytes gzip) so recipes can switch the opt-in fog scattering on.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex cdb2a9b8..87d756b3 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -226,6 +226,7 @@ These controls reuse `resolveVolumeFog` and its existing domain rules.| `noiseScale` | `0.3` | `0.001` to `100` || `maxDistance` | `100` | `0.01` to `10000` || `shadowAmbient` | derived from the scene: 0.15 in a closed room, 1 under open sky | `0` to `1` |+| `scatterOctaves`, `multiScatter`, `multiExtinction`, `multiAnisotropy`, `keyTransmittance`, `surfaceTransmittance` | `1`, `0.5`, `0.5`, `0.5`, `0`, `0` | Integer `1` to `4`, then `0` to `1` each; off by default, see [volume fog](https://67js.codepawl.com/volumetric.md) || `detailOctaves`, `detailAmount`, `warp`, `contrast`, `profileSoftness`, `keyScattering` | `1`, `0.5`, `0`, `1`, `0.5`, `1` | Integer `1` to `3`, `0` to `1`, `0` to `4`, `0` to `4`, `0` to `0.95`, `0` to `10`; see [volume fog](https://67js.codepawl.com/volumetric.md) |Fog bounds reject dimensions that collapse after Float32 rounding.diff --git a/docs/volumetric.md b/docs/volumetric.mdindex 12639f2e..ecfdb246 100644--- a/docs/volumetric.md+++ b/docs/volumetric.md@@ -54,6 +54,10 @@ renderer.render({ eye: [0, 2, 5], target: [0, 1, 0], time: 0 });| `contrast` | `1` | `0…4`; stretches the noise around its middle, so thin gaps sit next to thick patches || `profileSoftness` | `0.5` | `0…0.95`; where the `'smoothstep'` layer top starts to fade, as a share of the layer height. Lower tapers from nearer the floor || `keyScattering` | `1` | `0…10`; scales the key light's in-scattering (the shadow-mapped god rays) and leaves `ambient` alone |+| `scatterOctaves` | `1` | Integer `1…4`; above 1 the key light's in-scatter sums octaves that approximate multiple scattering (Wrenninge et al. 2015). Octave n scatters `multiScatter`^n as much, sees `multiExtinction`^n of the extinction and has `multiAnisotropy`^n of the anisotropy. Each octave needs the optical depth to the sun, three extra density taps per step |+| `multiScatter`, `multiExtinction`, `multiAnisotropy` | `0.5`, `0.5`, `0.5` | `0…1` each; the octave factors above. They act only with `scatterOctaves` above 1 |+| `keyTransmittance` | `0` | `0…1`; how much of the fog between a point and the sun dims the key light scattered there (three taps along the light, to the box exit). 0 keeps today's look |+| `surfaceTransmittance` | `0` | `0…1`; the same dimming for the key light on a lit surface inside the box, so a dense haze dims a sunlit floor. 0 keeps today's look |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/src/agent-look.js b/src/agent-look.jsindex 37840c8e..85d0b01e 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -22,7 +22,7 @@ const POINT_LIGHT_FIELDS = ['position', 'color', 'intensity', 'radius', 'range',const SPOT_LIGHT_FIELDS = ['position', 'direction', 'angle', 'penumbra', 'color', 'intensity', 'radius', 'range', 'castShadow', 'affects'];const AREA_LIGHT_FIELDS = ['position', 'direction', 'up', 'width', 'height', 'color', 'intensity', 'affects'];const VOLUME_VECTOR_FIELDS = ['minimum', 'maximum', 'color', 'ambient', 'drift'];-const VOLUME_NUMBER_FIELDS = ['density', 'steps', 'anisotropy', 'noiseAmount', 'noiseScale', 'maxDistance', 'shadowAmbient', 'heightFalloff', 'detailOctaves', 'detailAmount', 'warp', 'contrast', 'profileSoftness', 'keyScattering'];+const VOLUME_NUMBER_FIELDS = ['density', 'steps', 'anisotropy', 'noiseAmount', 'noiseScale', 'maxDistance', 'shadowAmbient', 'heightFalloff', 'detailOctaves', 'detailAmount', 'warp', 'contrast', 'profileSoftness', 'keyScattering', 'scatterOctaves', 'multiScatter', 'multiExtinction', 'multiAnisotropy', 'keyTransmittance', 'surfaceTransmittance'];const BLOOM_FIELDS = ['strength', 'threshold', 'radius'];const DEPTH_OF_FIELD_FIELDS = ['blur', 'focusDistance'];const MOTION_BLUR_FIELDS = ['shutter'];diff --git a/src/fog-field.js b/src/fog-field.jsindex ed1b8cad..bbe2d9b6 100644--- a/src/fog-field.js+++ b/src/fog-field.js@@ -6,7 +6,7 @@ export const FOG_LIGHT_LIMIT = 8;export const DEFAULT_FLOW_STRENGTH = 1;export const DEFAULT_FLOW_PERIOD = 2;// What a fog without detail controls uses: one octave, no warp, the noise as is, the layer top fading from half its height.-const DEFAULT_DETAIL = { detailOctaves: 1, detailAmount: 0.5, warp: 0, contrast: 1, profileSoftness: 0.5, keyScattering: 1 };+const DEFAULT_DETAIL = { detailOctaves: 1, detailAmount: 0.5, warp: 0, contrast: 1, profileSoftness: 0.5, keyScattering: 1, scatterOctaves: 1, multiScatter: 0.5, multiExtinction: 0.5, multiAnisotropy: 0.5, keyTransmittance: 0, surfaceTransmittance: 0 };const DETAIL_LIMITS = {detailOctaves: [1, 3, 'Volume detail octaves'],detailAmount: [0, 1, 'Volume detail amount'],@@ -14,6 +14,12 @@ const DETAIL_LIMITS = {contrast: [0, 4, 'Volume contrast'],profileSoftness: [0, 0.95, 'Volume profile softness'],keyScattering: [0, 10, 'Volume key scattering'],+ scatterOctaves: [1, 4, 'Volume scatter octaves'],+ multiScatter: [0, 1, 'Volume multi scatter'],+ multiExtinction: [0, 1, 'Volume multi extinction'],+ multiAnisotropy: [0, 1, 'Volume multi anisotropy'],+ keyTransmittance: [0, 1, 'Volume key transmittance'],+ surfaceTransmittance: [0, 1, 'Volume surface transmittance'],};/** The six detail fields of a resolved volume fog with defaults filled in. Anything unset or out of range throws like the core fields. */@@ -23,6 +29,7 @@ export function resolveFogDetail(volume) {if (volume[field] !== undefined) detail[field] = finiteRange(volume[field], minimum, maximum, label);}if (!Number.isInteger(detail.detailOctaves)) throw new RangeError('Volume detail octaves must be an integer');+ if (!Number.isInteger(detail.scatterOctaves)) throw new RangeError('Volume scatter octaves must be an integer');return detail;}diff --git a/src/fog-shader.js b/src/fog-shader.jsindex 31e67c4e..ebf69487 100644--- a/src/fog-shader.js+++ b/src/fog-shader.js@@ -44,6 +44,12 @@ function bindDetail(context, post, volume) {context.uniform1f(locate('volumeContrast'), detail.contrast);context.uniform1f(locate('volumeProfileStart'), detail.profileSoftness);context.uniform1f(locate('volumeKeyScattering'), detail.keyScattering);+ context.uniform1i(locate('volumeScatterOctaves'), detail.scatterOctaves);+ context.uniform1f(locate('volumeMultiScatter'), detail.multiScatter);+ context.uniform1f(locate('volumeMultiExtinction'), detail.multiExtinction);+ context.uniform1f(locate('volumeMultiAnisotropy'), detail.multiAnisotropy);+ context.uniform1f(locate('volumeKeyTransmittance'), detail.keyTransmittance);+ context.uniform1f(locate('volumeSurfaceTransmittance'), detail.surfaceTransmittance);}// The fog's field texture and light buffers; a program without those steps has no such uniforms, and a null location is ignored.@@ -104,6 +110,12 @@ uniform float volumeWarp;uniform float volumeContrast;uniform float volumeProfileStart;uniform float volumeKeyScattering;+uniform int volumeScatterOctaves;+uniform float volumeMultiScatter;+uniform float volumeMultiExtinction;+uniform float volumeMultiAnisotropy;+uniform float volumeKeyTransmittance;+uniform float volumeSurfaceTransmittance;uniform int volumeLightCount;uniform vec4 volumeLightPositions[8];uniform vec4 volumeLightColors[8];@@ -183,6 +195,57 @@ float densityNoise(vec3 samplePosition, vec2 velocity) {float layerProfile(float relativeHeight) {return volumeProfile > 0.5 ? 1.0 - smoothstep(volumeProfileStart, 1.0, relativeHeight) : exp(-relativeHeight);}+// The density factor at one point: the noise, times the field's layer profile or the height falloff. Zero where the fog is absent.+float fogDensityFactor(vec3 position) {+ float noise = 1.0;+ vec4 field = POST_FIELD ? texture(volumeField, (position.xz - volumeMinimum.xz) / (volumeMaximum.xz - volumeMinimum.xz)) : vec4(1);+ if (volumeNoiseAmount > 0.0) {+ float lookup = densityNoise(position - volumeDrift * time, field.zw);+ noise = mix(1.0, lookup * 2.0, volumeNoiseAmount);+ }+ if (POST_FIELD) noise *= field.r * layerProfile((position.y - volumeMinimum.y) / max(field.g, 0.0001));+ else if (volumeHeightFalloff > 0.0) noise *= exp((volumeMinimum.y - position.y) / volumeHeightFalloff);+ return noise;+}+// The share of the key light that reaches a point: the shadow map.+float keyVisibility(vec3 position) {+ vec4 lightPosition = volumeLightProjection * vec4(position, 1);+ vec3 shadow = lightPosition.xyz / lightPosition.w * 0.5 + 0.5;+ if (all(greaterThanEqual(shadow, vec3(0))) && all(lessThanEqual(shadow, vec3(1)))) {+ return texture(volumeShadowMap, vec3(shadow.xy, shadow.z - 0.0008));+ }+ return 1.0;+}+// The optical depth of the fog between a point and the sun, from three taps along the light direction up to the box exit.+float sunOpticalDepth(vec3 position, vec3 towardSun) {+ float exitDistance = volumeMaxDistance;+ for (int axis = 0; axis < 3; axis++) {+ if (towardSun[axis] == 0.0) continue;+ float first = (volumeMinimum[axis] - position[axis]) / towardSun[axis];+ float second = (volumeMaximum[axis] - position[axis]) / towardSun[axis];+ exitDistance = min(exitDistance, max(first, second));+ }+ exitDistance = max(exitDistance, 0.0);+ float sum = 0.0;+ for (int tap = 0; tap < 3; tap++) sum += fogDensityFactor(position + towardSun * (exitDistance * (float(tap) + 0.5) / 3.0));+ return volumeDensity * sum * exitDistance / 3.0;+}+// The sun's in-scatter at a point. The octave sum approximates multiple scattering (Wrenninge et al. 2015, "Oz: the great and+// volumetric"): octave n scatters multiScatter^n as much, sees half^n of the extinction and has half^n of the anisotropy.+float keyInScatter(float cosine, float opticalDepth) {+ float total = 0.0;+ float weight = 1.0;+ float extinction = 1.0;+ float anisotropy = volumeAnisotropy;+ for (int octave = 0; octave < 4; octave++) {+ if (octave >= volumeScatterOctaves) break;+ total += weight * henyeyGreenstein(cosine, anisotropy) * exp(-opticalDepth * volumeKeyTransmittance * extinction);+ weight *= volumeMultiScatter;+ extinction *= volumeMultiExtinction;+ anisotropy *= volumeMultiAnisotropy;+ }+ return total;+}vec3 volumeFog(vec3 background) {vec2 clipXY = textureCoordinate * 2.0 - 1.0;vec4 farPoint = inverseViewProjection * vec4(clipXY, 1.0, 1.0);@@ -194,6 +257,7 @@ vec3 volumeFog(vec3 background) {float surfaceDistance = volumeMaxDistance;if (surfacePoint.w > 0.0) surfaceDistance = max(0.0, dot(surfacePoint.xyz - origin * surfacePoint.w, direction) / surfacePoint.w);float exitDistance = min(volumeMaxDistance, surfaceDistance);+ float boxExit = volumeMaxDistance;float entry = 0.0;for (int axis = 0; axis < 3; axis++) {if (direction[axis] == 0.0) {@@ -203,6 +267,7 @@ vec3 volumeFog(vec3 background) {float second = (volumeMaximum[axis] - origin[axis]) / direction[axis];entry = max(entry, min(first, second));exitDistance = min(exitDistance, max(first, second));+ boxExit = min(boxExit, max(first, second));}}if (entry >= exitDistance) return background;@@ -210,33 +275,25 @@ vec3 volumeFog(vec3 background) {vec3 lightDirection = normalize(volumeLightDirection);float cosine = dot(direction, lightDirection);float anisotropy = volumeAnisotropy;- float phase = henyeyGreenstein(cosine, anisotropy);+ vec3 towardSun = lightDirection;+ bool sunTransmittance = volumeKeyTransmittance > 0.0 || volumeScatterOctaves > 1;float jitter = hash(vec3(gl_FragCoord.xy, 0));float transmittance = 1.0;vec3 accumulated = vec3(0);for (int index = 0; index < 48; index++) {if (index >= volumeSteps) break;vec3 position = origin + direction * (entry + (float(index) + jitter) * stepSize);- float noise = 1.0;- vec4 field = POST_FIELD ? texture(volumeField, (position.xz - volumeMinimum.xz) / (volumeMaximum.xz - volumeMinimum.xz)) : vec4(1);- if (volumeNoiseAmount > 0.0) {- float lookup = densityNoise(position - volumeDrift * time, field.zw);- noise = mix(1.0, lookup * 2.0, volumeNoiseAmount);- }- if (POST_FIELD) noise *= field.r * layerProfile((position.y - volumeMinimum.y) / max(field.g, 0.0001));- else if (volumeHeightFalloff > 0.0) noise *= exp((volumeMinimum.y - position.y) / volumeHeightFalloff);+ float noise = fogDensityFactor(position);float opacity = 1.0 - exp(-volumeDensity * noise * stepSize);- vec4 lightPosition = volumeLightProjection * vec4(position, 1);- vec3 shadow = lightPosition.xyz / lightPosition.w * 0.5 + 0.5;- float visibility = 1.0;- if (all(greaterThanEqual(shadow, vec3(0))) && all(lessThanEqual(shadow, vec3(1)))) {- visibility = texture(volumeShadowMap, vec3(shadow.xy, shadow.z - 0.0008));- }+ float visibility = keyVisibility(position);vec4 skyCell = POST_SKY ? texture(fogSkyVisibility, (position - volumeMinimum) / (volumeMaximum - volumeMinimum)) : vec4(0);float shadowShare = POST_SKY ? 0.1 + 0.9 * min(1.0, 30.0 * skyCell.r) : volumeShadowAmbient;float ambientShare = mix(shadowShare, 1.0, visibility);if (volumeGridFog > 0.5) ambientShare = min(1.0, 30.0 * skyCell.r);- vec3 scattering = volumeColor * (volumeAmbient * ambientShare + volumeLightColor * (phase * visibility * volumeKeyScattering) + 0.6 * skyCell.gba);+ float opticalDepth = 0.0;+ if (sunTransmittance && visibility > 0.001) opticalDepth = sunOpticalDepth(position, towardSun);+ float phase = keyInScatter(cosine, opticalDepth);+ vec3 scattering = volumeColor * (volumeAmbient * ambientShare + 0.6 * skyCell.gba + volumeLightColor * (phase * visibility * volumeKeyScattering));if (POST_LIGHTS) scattering += volumeColor * fogLightScattering(position, direction);accumulated += transmittance * opacity * scattering;transmittance *= 1.0 - opacity;@@ -248,7 +305,14 @@ vec3 volumeFog(vec3 background) {vec2 offset = vec2(cos(index * 2.4) * resolution.y / resolution.x, sin(index * 2.4)) * radius;accumulated += textureLod(frameTexture, textureCoordinate + offset, log2(0.7 * radius * resolution.y)).rgb * volumeColor * (0.009 * (1.0 - transmittance) / (1.0 + 0.04 * index));}- return accumulated + background * transmittance;+ float surfaceSun = 1.0;+ if (volumeSurfaceTransmittance > 0.0 && surfacePoint.w > 0.0 && surfaceDistance <= boxExit) {+ // A surface inside the box: its sun passes through the fog too. A lit surface takes mostly sun, so the whole colour dims by its share.+ vec3 surfacePosition = origin + direction * surfaceDistance + towardSun * 0.05;+ float surfaceVisibility = keyVisibility(surfacePosition);+ if (surfaceVisibility > 0.001) surfaceSun = mix(1.0, exp(-sunOpticalDepth(surfacePosition, towardSun) * volumeSurfaceTransmittance), surfaceVisibility);+ }+ return accumulated + background * transmittance * surfaceSun;}`,});diff --git a/tests/fog-field.test.js b/tests/fog-field.test.jsindex 920bde7f..c6a5147c 100644--- a/tests/fog-field.test.js+++ b/tests/fog-field.test.js@@ -84,7 +84,7 @@ const DETAIL_FIELDS = ['detailOctaves', 'detailAmount', 'warp', 'contrast', 'protest('a fog without detail controls resolves to the default detail and needs no detail step', () => {const resolved = resolveVolumeFog({ density: 0.1 });for (const key of DETAIL_FIELDS) assert.equal(Object.hasOwn(resolved, key), false, key);- assert.deepEqual(resolveFogDetail(resolved), { detailOctaves: 1, detailAmount: 0.5, warp: 0, contrast: 1, profileSoftness: 0.5, keyScattering: 1 });+ assert.deepEqual(resolveFogDetail(resolved), { detailOctaves: 1, detailAmount: 0.5, warp: 0, contrast: 1, profileSoftness: 0.5, keyScattering: 1, scatterOctaves: 1, multiScatter: 0.5, multiExtinction: 0.5, multiAnisotropy: 0.5, keyTransmittance: 0, surfaceTransmittance: 0 });assert.equal(fogUsesDetail(resolved), false);assert.equal(fogUsesDetail(resolveVolumeFog({ density: 0.1, detailOctaves: 1, warp: 0, contrast: 1, profileSoftness: 0.2, keyScattering: 3 })), false, 'profile and key scattering are plain uniforms');});