Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.py
index 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.mjs
index 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]) : nul
const 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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.js
index 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.js
index 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.js
index 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.js
index 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', 'pro
test('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');
});