@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/render/sky.js

@@ -1,9 +1,10 @@
 import { linearToGamma } from '../shaders/misc.js';
 import { smoothNoise3D } from '../shaders/noise.js';
 import { getDevice, getEngine } from '../app/api.js';
-import { getDefaultAtmosphereParams, getAerialPerspectiveLut, renderAtmosphereLUTs, getAtmosphereParamsStruct, createTransmittanceLutProgram, createMultiScatteringLutProgram, createSkyViewLutProgram, createAPLutProgram, skyBox, atmosphereLUTRendered, getTransmittanceLut, getSkyViewLut } from '../shaders/atmosphere.js';
-import { Matrix4x4, Disposable, DRef, Vector4, Vector2, Vector3, CubeFace, objectKeys, DEPTH_FARTHEST, DEPTH_COMPARE_DEFAULT, DEPTH_COMPARE_FARTHER } from '@zephyr3d/base';
+import { getDefaultAtmosphereParams, getAerialPerspectiveLut, renderAtmosphereLUTs, MIN_OBSERVER_ALTITUDE, getMultiScatteringLut, getAtmosphereParamsStruct, createTransmittanceLutProgram, createMultiScatteringLutProgram, createSkyViewLutProgram, createAPLutProgram, skyBox, rayIntersectSphere, transmittanceToSky, atmosphereLUTRendered, getTransmittanceLut, getSkyViewLut } from '../shaders/atmosphere.js';
+import { Matrix4x4, Disposable, DRef, Vector4, Vector3, Vector2, CubeFace, objectKeys, DEPTH_FARTHEST, DEPTH_COMPARE_DEFAULT, DEPTH_COMPARE_FARTHER } from '@zephyr3d/base';
 import { Primitive } from './primitive.js';
+import '../node_modules/meshoptimizer/meshopt_simplifier.js';
 import { BoxShape } from '../shapes/box.js';
 import '../shapes/capsule.js';
 import '../shapes/cylinder.js';
@@ -20,14 +21,22 @@ import { uniformSphereSamples, Fog } from '../values.js';
 import { getDefaultHeightFogParams, MAX_FOG_HEIGHT, getHeightFogParamsStruct, calculateFog } from '../shaders/fog.js';
 import { drawFullscreenQuad } from './fullscreenquad.js';
 import { panoramaToCubemap } from '../utility/panorama.js';
+import { VolumetricCloud } from './volumetric_cloud/volumetric_cloud.js';
+import { VolumetricCloudResources } from './volumetric_cloud/resources.js';
+import { drawVolumetricCloudDebug } from './volumetric_cloud/debug_view.js';
+import { VolumetricCloudSkyCache } from './volumetric_cloud/sky_cache.js';
+import { cloudCacheEncode } from './volumetric_cloud/cloud_common.js';
 import '../camera/camera.js';
 import { PerspectiveCamera } from '../camera/perspectivecamera.js';
+import '../camera/follow.js';
 
 const fogTypeMap = {
     height_fog: Fog.FOG_TYPE_HEIGHT,
     none: Fog.FOG_TYPE_NONE
 };
 const defaultSkyWorldMatrix = Matrix4x4.identity();
+const SKY_OUTPUT_MAX = 64512 * 0.5;
+/** Volumetric clouds give way to procedural ones this far below the cloud base, in meters */ const VOLUMETRIC_CLOUD_CEILING_MARGIN = 500;
 /**
  * The sky renderer
  * @public
@@ -97,10 +106,29 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
     _radianceMapWidth;
     _atmosphereParams;
     _atmosphereExposure;
+    _lowerHemisphereIsBlack;
+    _physicalSunDisk;
+    /** Observer local up (planet center to observer) of the current frame, in world space. */ _observerUp;
+    /** Observer altitude and local up the IBL was last baked at; altitude < 0 when never baked. */ _bakedObserverAltitude;
+    _bakedObserverUp;
+    _rebakeAltitudeRatio;
+    _rebakeAngle;
     _fogType;
     _heightFogParams;
     _cloudy;
     _cloudIntensity;
+    _cloudMode;
+    _volumetricCloud;
+    _volumetricCloudResources;
+    _volumetricCloudCache;
+    /** Volumetric clouds drawn this frame: requested, supported and the observer below the layer */ _volumetricActive;
+    _bindgroupSkyVolumetric;
+    static _programSkyVolumetric = null;
+    static _volumetricAltitudeWarned = false;
+    _cloudDebugView;
+    _cloudDebugSlice;
+    _cloudDebugChannel;
+    static _volumetricFallbackWarned = false;
     _debugAerialPerspective;
     _wind;
     _skyboxRotation;
@@ -125,6 +153,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
    * @internal Ratio converting the fog shader's atmosphere-derived LUT samples from the fixed bake
    * exposure to the live one (1 in legacy).
    */ _fogPreExposure;
+    /** @internal Cubemap latched in update() for the height fog sky light term. */ _fogSkyLightCubemap;
     /**
    * Creates an instance of SkyRenderer
    */ constructor(){
@@ -147,15 +176,33 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         this._irradianceFrameBuffer = new DRef();
         this._atmosphereParams = getDefaultAtmosphereParams();
         this._atmosphereExposure = 1;
+        this._lowerHemisphereIsBlack = true;
+        this._physicalSunDisk = false;
+        this._observerUp = Vector3.axisPY();
+        this._bakedObserverAltitude = -1;
+        this._bakedObserverUp = Vector3.axisPY();
+        this._rebakeAltitudeRatio = 0.05;
+        this._rebakeAngle = 0.5;
         this._debugAerialPerspective = 0;
         this._fogType = 'height_fog';
         this._heightFogParams = getDefaultHeightFogParams();
         this._cloudy = 0.45;
         this._cloudIntensity = 15;
+        this._cloudMode = 'procedural';
+        this._volumetricCloud = new VolumetricCloud();
+        this._volumetricCloudResources = new VolumetricCloudResources();
+        this._volumetricCloudCache = new VolumetricCloudSkyCache();
+        this._volumetricActive = false;
+        this._bindgroupSkyVolumetric = new DRef();
+        this._cloudDebugView = 'none';
+        this._cloudDebugSlice = 0;
+        this._cloudDebugChannel = 0;
         this._wind = new Vector2(0, 0);
         this._skyboxRotation = new Vector3(0, 0, 0);
         this._skyWorldMatrix = defaultSkyWorldMatrix;
-        this._lastSunDir = SkyRenderer._getSunDir(null);
+        // Copied: without a sun light _getSunDir returns the shared ShaderHelper.defaultSunDir, which
+        // update() would otherwise overwrite with the last scene's sun direction.
+        this._lastSunDir = new Vector3(SkyRenderer._getSunDir(null));
         this._lastSunColor = SkyRenderer._getSunColor(null);
         this._panoramaAsset = '';
         this._shProjector = new CubemapSHProjector(10000);
@@ -169,6 +216,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         this._format = null;
         this._fogLuminanceScale = 1;
         this._fogPreExposure = 1;
+        this._fogSkyLightCubemap = null;
     }
     /** @internal */ getHash(_ctx) {
         return `${this.skyType}:${this.fogType}`;
@@ -272,7 +320,10 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /** Aerial perspective density */ get aerialPerspectiveDistance() {
+    /**
+   * Distance covered by the aerial perspective LUT, in atmosphere meters (world distance times
+   * {@link SkyRenderer.cameraHeightScale}). Beyond it aerial perspective no longer increases.
+   */ get aerialPerspectiveDistance() {
         return this._atmosphereParams.apDistance;
     }
     set aerialPerspectiveDistance(val) {
@@ -281,6 +332,40 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
+    /**
+   * Whether the environment lighting baked from the scattering sky sees black below the horizon.
+   */ get lowerHemisphereIsBlack() {
+        return this._lowerHemisphereIsBlack;
+    }
+    set lowerHemisphereIsBlack(val) {
+        if (val !== this._lowerHemisphereIsBlack) {
+            this._lowerHemisphereIsBlack = val;
+            this.invalidate();
+        }
+    }
+    /**
+   * Strength of the aerial perspective: scales the distance the atmosphere is integrated over
+   * between the camera and the scene, so distant objects get hazier (>1) or clearer (<1). The sky
+   * itself is unaffected.
+   */ get aerialPerspectiveViewDistanceScale() {
+        return this._atmosphereParams.apViewDistanceScale;
+    }
+    set aerialPerspectiveViewDistanceScale(val) {
+        val = Math.max(0, val);
+        if (val !== this._atmosphereParams.apViewDistanceScale) {
+            this._atmosphereParams.apViewDistanceScale = val;
+        }
+    }
+    /**
+   * Distance from the camera where aerial perspective starts, in the same units as
+   * {@link SkyRenderer.aerialPerspectiveDistance} (atmosphere meters). Nearer surfaces get no
+   * atmospheric haze.
+   */ get aerialPerspectiveStartDepth() {
+        return this._atmosphereParams.apStartDepth;
+    }
+    set aerialPerspectiveStartDepth(val) {
+        this._atmosphereParams.apStartDepth = Math.max(0, val);
+    }
     /** Atmosphere exposure */ get atmosphereExposure() {
         return this._atmosphereExposure;
     }
@@ -290,7 +375,52 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /** Aerial perspective density */ get cameraHeightScale() {
+    /**
+   * Color of the virtual planet ground of the scattering sky.
+   *
+   * @remarks
+   * Shown below the horizon where no scene geometry covers the sky, lit by the sun through the
+   * atmosphere, and bounced back into the sky as part of multiple scattering.
+   */ get groundAlbedo() {
+        return this._atmosphereParams.groundAlbedo;
+    }
+    set groundAlbedo(val) {
+        if (!val.equalsTo(this._atmosphereParams.groundAlbedo)) {
+            this._atmosphereParams.groundAlbedo.set(val);
+            this.invalidate();
+        }
+    }
+    /**
+   * Relative change of the observer altitude that re-bakes the environment lighting of the
+   * scattering sky, e.g. 0.05 re-bakes after climbing or descending 5% (and at least 10 m).
+   *
+   * @remarks
+   * The on-screen sky and aerial perspective follow the camera every frame; only the cached IBL
+   * bake, which is expensive, waits for this threshold or {@link SkyRenderer.atmosphereRebakeAngle}.
+   */ get atmosphereRebakeAltitudeRatio() {
+        return this._rebakeAltitudeRatio;
+    }
+    set atmosphereRebakeAltitudeRatio(val) {
+        this._rebakeAltitudeRatio = Math.max(0, val);
+    }
+    /**
+   * Angle in degrees the local vertical may turn, by travelling across the curved planet, before
+   * the environment lighting of the scattering sky is re-baked. 0.5 degrees is about 55 km on Earth.
+   */ get atmosphereRebakeAngle() {
+        return this._rebakeAngle;
+    }
+    set atmosphereRebakeAngle(val) {
+        this._rebakeAngle = Math.max(0, val);
+    }
+    /**
+   * Atmosphere meters per world unit.
+   *
+   * @remarks
+   * The planet top sits at the world origin with its center straight below.
+   * The camera position, scaled by this factor, places the observer in the
+   * atmosphere: its altitude, and for large horizontal distances where on the
+   * curved planet it stands. Aerial perspective distances are scaled the same way.
+   */ get cameraHeightScale() {
         return this._atmosphereParams.cameraHeightScale;
     }
     set cameraHeightScale(val) {
@@ -390,6 +520,38 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
     }
     /**
+   * How much distant height fog takes the color of the environment behind it (0..1).
+   */ get heightFogSkyLightStrength() {
+        return this._heightFogParams.skyLightStrength;
+    }
+    set heightFogSkyLightStrength(val) {
+        if (val !== this._heightFogParams.skyLightStrength) {
+            this._heightFogParams.skyLightStrength = val;
+            this.invalidate();
+        }
+    }
+    /**
+   * Blurriness of the environment seen through the fog, as a roughness selecting the radiance map
+   * mip.
+   */ get heightFogSkyLightRoughness() {
+        return this._heightFogParams.skyLightRoughness;
+    }
+    set heightFogSkyLightRoughness(val) {
+        if (val !== this._heightFogParams.skyLightRoughness) {
+            this._heightFogParams.skyLightRoughness = val;
+            this.invalidate();
+        }
+    }
+    /**
+   * @internal
+   * Cubemap the height fog samples for {@link SkyRenderer.heightFogSkyLightStrength}: the scene's
+   * IBL radiance map, or the sky's own radiance map as a placeholder binding when there is none
+   * (the fog then sees a zero scale and skips it).
+   */ getFogSkyLightCubemap(ctx) {
+        const light = ctx.scene.env.light;
+        return light.type === 'ibl' && light.radianceMap || this.radianceMap;
+    }
+    /**
    * Light density of the sky.
    *
    * @remarks
@@ -416,6 +578,98 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
     }
     /**
+   * How the clouds of the scatter sky are drawn.
+   *
+   * @remarks
+   * `volumetric` needs a WebGPU device; on other devices the procedural clouds are drawn instead,
+   * see {@link SkyRenderer.effectiveCloudMode}.
+   */ get cloudMode() {
+        return this._cloudMode;
+    }
+    set cloudMode(val) {
+        if (val !== this._cloudMode) {
+            this._cloudMode = val;
+            this.invalidate();
+        }
+    }
+    /** The cloud mode actually drawn: `volumetric` falls back to `procedural` off WebGPU. */ get effectiveCloudMode() {
+        if (this._cloudMode === 'volumetric' && getDevice().type !== 'webgpu') {
+            if (!SkyRenderer._volumetricFallbackWarned) {
+                SkyRenderer._volumetricFallbackWarned = true;
+                console.warn('Volumetric clouds require WebGPU, drawing procedural clouds instead');
+            }
+            return 'procedural';
+        }
+        return this._cloudMode;
+    }
+    /** Parameters of the volumetric clouds. */ get volumetricCloud() {
+        return this._volumetricCloud;
+    }
+    /**
+   * Base shape noise of the volumetric clouds, as a 2D atlas of the slices of a cubic volume,
+   * or null to generate it.
+   *
+   * @remarks
+   * An N^3 volume is stored as N slices of N x N texels laid out row by row, left to right, so
+   * that the atlas holds width * height = N^3 texels, e.g. 128^3 as 2048 x 1024 (16 x 8 slices).
+   * Channels: R Perlin-Worley, GBA Worley fbm of increasing frequency.
+   */ get cloudBaseNoise() {
+        return this._volumetricCloudResources.baseNoiseSource;
+    }
+    set cloudBaseNoise(tex) {
+        this._volumetricCloudResources.baseNoiseSource = tex;
+        this._volumetricCloudCache.invalidate();
+    }
+    /**
+   * Detail noise of the volumetric clouds as a slice atlas (see {@link SkyRenderer.cloudBaseNoise}),
+   * or null to generate it. Channels: RGB Worley fbm of increasing frequency.
+   */ get cloudDetailNoise() {
+        return this._volumetricCloudResources.detailNoiseSource;
+    }
+    set cloudDetailNoise(tex) {
+        this._volumetricCloudResources.detailNoiseSource = tex;
+        this._volumetricCloudCache.invalidate();
+    }
+    /**
+   * Weather map (the cloud map of Nubis 2017) of the volumetric clouds, or null to generate it.
+   * Channels: R coverage of the connected formation, G coverage of the isolated formation (clouds
+   * grow where it is highest; Coverage lowers the threshold, rather than prescribing sky area),
+   * B cloud type (0 stratus, 0.5 stratocumulus, 1 cumulus).
+   */ get cloudWeatherMap() {
+        return this._volumetricCloudResources.weatherMapSource;
+    }
+    set cloudWeatherMap(tex) {
+        this._volumetricCloudResources.weatherMapSource = tex;
+        this._volumetricCloudCache.invalidate();
+    }
+    /** Draws a volumetric cloud resource over the sky, for inspection. */ get cloudDebugView() {
+        return this._cloudDebugView;
+    }
+    set cloudDebugView(val) {
+        this._cloudDebugView = val;
+    }
+    /** @internal Whether {@link SkyRenderer.drawCloudDebugView} has anything to draw this frame. */ get cloudDebugViewActive() {
+        return this._cloudDebugView !== 'none' && this._skyType === 'scatter' && this.effectiveCloudMode === 'volumetric';
+    }
+    /**
+   * @internal Draws {@link SkyRenderer.cloudDebugView} over the current render target. Called on
+   * the presented image, after tone mapping, so the texels show their stored values.
+   */ drawCloudDebugView() {
+        drawVolumetricCloudDebug(this._volumetricCloudResources, this._cloudDebugView, this._cloudDebugSlice, this._cloudDebugChannel, this._volumetricCloudCache.densityParams);
+    }
+    /** Slice, 0 to 1: noise volume depth, density XY depth, or density XZ altitude. */ get cloudDebugSlice() {
+        return this._cloudDebugSlice;
+    }
+    set cloudDebugSlice(val) {
+        this._cloudDebugSlice = Math.min(1, Math.max(0, val));
+    }
+    /** Channel shown by {@link SkyRenderer.cloudDebugView}: 0 RGB, 1-4 R, G, B or A as grey. */ get cloudDebugChannel() {
+        return this._cloudDebugChannel;
+    }
+    set cloudDebugChannel(val) {
+        this._cloudDebugChannel = Math.min(4, Math.max(0, Math.round(val)));
+    }
+    /**
    * Wind velocity
    *
    * @remarks
@@ -556,6 +810,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         return this._skyDistantLightLut.get().getColorAttachments()[0];
     }
     update(ctx) {
+        const wantVolumetric = this._skyType === 'scatter' && this.effectiveCloudMode === 'volumetric';
         // Latch the fog scales for this frame. The bake path (updateBakedSkyMap) uses the sky camera
         // whose scene is null, so it cannot read lightingMode itself; both bake and main pass run after
         // update(), so caching them here keeps them consistent.
@@ -567,15 +822,25 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         //    take the plain camera pre-exposure.
         // Legacy leaves both at 1 so its authored colors are untouched.
         this._fogPreExposure = SkyRenderer.getBakeToPreExposedScale(ctx);
+        this._physicalSunDisk = ctx.scene.lightingMode === 'physical';
+        // Sky light for height fog: radiance map samples times the same scale the IBL applies to them.
+        const envLight = ctx.scene.env.light;
+        const fogSkyLightMap = envLight.type === 'ibl' ? envLight.radianceMap : null;
+        // Same scale as ShaderHelper.getEnvLightLuminance(), which cannot be used here: it reads ctx.env,
+        // and update() runs before the render graph sets it.
+        this._heightFogParams.skyLightScale = fogSkyLightMap ? SkyRenderer.getBakeToPreExposedScale(ctx) * (envLight.strength ?? 0) : 0;
+        this._heightFogParams.skyLightMaxLod = fogSkyLightMap ? fogSkyLightMap.mipLevelCount - 1 : 0;
+        this._fogSkyLightCubemap = this.getFogSkyLightCubemap(ctx);
         this._fogLuminanceScale = ctx.scene.lightingMode === 'physical' ? ctx.scene.env.light.intensity * ShaderHelper.getPreExposure(ctx) : 1;
         const useScatter = this._skyType === 'scatter';
         if (useScatter || !atmosphereLUTRendered()) {
             this.renderAtmosphereLUTs(ctx);
         }
+        this._updateVolumetricClouds(ctx, wantVolumetric);
         const oldSunLight = ctx.sunLight && useScatter ? ctx.sunLight.color : null;
         const sunDir = SkyRenderer._getSunDir(ctx.sunLight);
         const sunColor = SkyRenderer._getSunColor(ctx.sunLight);
-        if (this._skyType === 'scatter' && (this._wind.x !== 0 || this._wind.y !== 0)) {
+        if (this._skyType === 'scatter' && !this._volumetricActive && (this._wind.x !== 0 || this._wind.y !== 0)) {
             this._bakedSkyboxDirty = true;
         }
         if (!this._skyDistantLightLut.get()) {
@@ -593,13 +858,23 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this._lastSunColor.set(sunColor);
             this._bakedSkyboxDirty = true;
         }
+        // The scattering sky seen from the observer changes as the camera climbs or travels across the
+        // planet. Re-baking the IBL every frame would be far too expensive, so it waits for thresholds.
+        if (useScatter) {
+            const altitude = this._atmosphereParams.observerAltitude;
+            const baked = this._bakedObserverAltitude;
+            if (baked < 0 || Math.abs(altitude - baked) > Math.max(10, this._rebakeAltitudeRatio * baked) || Vector3.dot(this._observerUp, this._bakedObserverUp) < Math.cos(this._rebakeAngle * Math.PI / 180)) {
+                this._bakedObserverAltitude = altitude;
+                this._bakedObserverUp.set(this._observerUp);
+                this._bakedSkyboxDirty = true;
+            }
+        }
         if (this._bakedSkyboxDirty) {
             this._bakedSkyboxDirty = false;
-            // updateBakedSkyMap derives the IBL (specular prefilter + irradiance SH) from the fog-free
-            // cubemap internally, before compositing fog. The distant-light LUT is re-baked here against
-            // the fogged cubemap to preserve the pre-refactor fog shading appearance.
+            // updateBakedSkyMap derives both the IBL and the distant-sky LUT from the fog-free cubemap,
+            // before compositing fog. Deriving the distant-sky LUT from the fogged cubemap would feed the
+            // fog color back into its own ambient term.
             this.updateBakedSkyMap(ctx);
-            this.renderSkyDistantLut(ctx, this._bakedSkyboxTexture.get());
         }
         // Atmosphere extinction times cloud occlusion. The cloud term intentionally applies only to
         // the scene's directional light, not to the sky bake: the clouds in the cubemap are lit by
@@ -614,11 +889,9 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             const cameraY = Math.min(this._heightFogParams.parameter2.y + MAX_FOG_HEIGHT, ctx.camera.getWorldPosition().y);
             const p = Math.max(-125, Math.min(126, -this._heightFogParams.parameter1.w * (cameraY - this._heightFogParams.parameter2.y)));
             this._heightFogParams.parameter3.z = this._heightFogParams.parameter2.x * Math.pow(2, p);
-            // The legacy directional fog term expects a display-relative 0..1 light color. It cannot be
-            // mixed directly with photometric illuminance; physical fog instead receives its radiance
-            // from the distant-sky integration below.
             if (ctx.scene.lightingMode === 'physical') {
-                this._heightFogParams.lightColor.setXYZ(0, 0, 0);
+                const sunIlluminance = ctx.sunLight ? ctx.sunLight.intensity : 0;
+                this._heightFogParams.lightColor.set(Vector3.scale(newSunLight, sunIlluminance * ShaderHelper.getPreExposure(ctx) / (4 * Math.PI)));
             } else {
                 this._heightFogParams.lightColor.set(newSunLight);
             }
@@ -626,19 +899,78 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return oldSunLight;
     }
+    /**
+   * Advances the volumetric cloud sky cache, after the atmosphere parameters of the frame are set.
+   * The sky cache only holds what an observer below the layer sees; above that the procedural
+   * clouds are drawn instead.
+   */ _updateVolumetricClouds(ctx, wanted) {
+        let active = wanted;
+        if (active) {
+            const altitude = this._atmosphereParams.observerAltitude;
+            if (altitude > this._volumetricCloud.layerBottomAltitude - VOLUMETRIC_CLOUD_CEILING_MARGIN) {
+                active = false;
+                if (!SkyRenderer._volumetricAltitudeWarned) {
+                    SkyRenderer._volumetricAltitudeWarned = true;
+                    console.warn('Volumetric clouds are only drawn below the cloud layer, drawing procedural clouds instead');
+                }
+            }
+        }
+        if (active) {
+            this._volumetricCloudResources.update(this._volumetricCloud.noiseSeed);
+            this._volumetricCloudCache.update(this._volumetricCloud, this._volumetricCloudResources, this._atmosphereParams, ctx.camera.getWorldPosition(), ctx.device.frameInfo.elapsedOverall * 0.001);
+            active = !!this._volumetricCloudCache.toMap;
+            if (this._volumetricCloudCache.roundCompleted) {
+                // The environment lighting follows the clouds once per round
+                this._bakedSkyboxDirty = true;
+            }
+        } else if (this._volumetricActive) {
+            // Resumes with a full rebuild rather than a fade from stale maps
+            this._volumetricCloudCache.invalidate();
+        }
+        if (active !== this._volumetricActive) {
+            this._volumetricActive = active;
+            this._bakedSkyboxDirty = true;
+        }
+    }
     renderAtmosphereLUTs(ctx) {
         this._atmosphereParams.lightDir.set(SkyRenderer._getSunDir(ctx.sunLight));
         this._atmosphereParams.lightColor.set(SkyRenderer._getSunColor(ctx.sunLight));
-        // Physical: the sun input is photometric (lux), normalized onto the model's authored reference
-        // and stored at the fixed PHYSICAL_BAKE_EXPOSURE rather than the live camera exposure. That
-        // keeps the cached IBL bake exposure-independent while staying inside the environment cubemap's
-        // limited float range -- raw luminance would overflow it to Inf. Consumers rescale to the live
-        // exposure via getBakeToPreExposedScale().
         this._atmosphereParams.lightColor.w *= this._atmosphereExposure * (ctx.scene.lightingMode === 'physical' ? SkyRenderer.PHYSICAL_ATMOSPHERE_LUMINANCE_SCALE * SkyRenderer.PHYSICAL_BAKE_EXPOSURE : 1);
         this._atmosphereParams.cameraAspect = ctx.camera.getAspect();
-        this._atmosphereParams.cameraWorldMatrix.set(ctx.camera.worldMatrix);
+        this._atmosphereParams.cameraTanHalfFovy = ctx.camera.isPerspective() ? ctx.camera.getTanHalfFovy() : 1;
+        const referential = this._updateObserver(ctx.camera.getWorldPosition());
+        Matrix4x4.multiply(referential, ctx.camera.worldMatrix, this._atmosphereParams.cameraWorldMatrix);
+        referential.transformVectorAffine(this._atmosphereParams.lightDir, this._atmosphereParams.lightDir);
         renderAtmosphereLUTs(this._atmosphereParams);
     }
+    /**
+   * Places the observer for the camera at `cameraPos` and returns the world to observer-local
+   * rotation, also stored in the atmosphere params.
+   */ _updateObserver(cameraPos) {
+        const params = this._atmosphereParams;
+        const scale = params.cameraHeightScale;
+        const R = params.plantRadius;
+        const px = cameraPos.x * scale;
+        const py = R + cameraPos.y * scale;
+        const pz = cameraPos.z * scale;
+        const len = Math.hypot(px, py, pz);
+        params.observerAltitude = Math.max(len - R, MIN_OBSERVER_ALTITUDE);
+        const up = len > 0 ? new Vector3(px / len, py / len, pz / len) : Vector3.axisPY();
+        this._observerUp.set(up);
+        // Duff et al. would do, but projecting a fixed axis keeps the identity at the origin.
+        const ref = Math.abs(up.x) < 0.999 ? Vector3.axisPX() : Vector3.axisPZ();
+        const localX = Vector3.sub(ref, Vector3.scale(up, Vector3.dot(ref, up))).inplaceNormalize();
+        const localZ = Vector3.cross(localX, up).inplaceNormalize();
+        // Rows of the world to local rotation are the local axes. Matrix4x4 is column-major: its
+        // setColXYZW(i, ...) writes the strided elements transformVectorAffine and shader mat * vec
+        // treat as row i.
+        const m = params.skyViewReferential;
+        m.setColXYZW(0, localX.x, localX.y, localX.z, 0);
+        m.setColXYZW(1, up.x, up.y, up.z, 0);
+        m.setColXYZW(2, localZ.x, localZ.y, localZ.z, 0);
+        m.setColXYZW(3, 0, 0, 0, 1);
+        return m;
+    }
     renderSkyDistantLut(ctx, skybox) {
         this._prepareSkyBox(ctx.device);
         ctx.device.pushDeviceStates();
@@ -680,7 +1012,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             // Direct sunlight is represented by the scene's directional sun light. Keep the analytic
             // sun disk out of both diffuse and specular IBL to avoid baking that direct contribution a
             // second time. Atmospheric scattering and clouds remain in the cubemap.
-            this._renderSky(camera, false, false, this._getSkyBakeLuminanceScale(ctx));
+            this._renderSky(camera, false, false, this._getSkyBakeLuminanceScale(ctx), this._lowerHemisphereIsBlack);
         }
         device.popDeviceStates();
         this.renderSkyDistantLut(ctx, tex);
@@ -737,6 +1069,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         bindgroup.setTexture('skyDistantLightLut', this._skyDistantLightLut.get().getColorAttachments()[0], fetchSampler('clamp_nearest_nomip'));
         bindgroup.setTexture('apLut', getAerialPerspectiveLut(), fetchSampler('clamp_linear_nomip'));
+        bindgroup.setTexture('skyLightCubemap', this._fogSkyLightCubemap ?? this.radianceMap, fetchSampler('clamp_linear'));
         bindgroup.setValue('rt', device.getFramebuffer() ? 1 : 0);
         bindgroup.setValue('invProjViewMatrix', camera.invViewProjectionMatrix);
         bindgroup.setValue('cameraNearFar', new Vector2(camera.getNearPlane(), camera.getFarPlane()));
@@ -745,7 +1078,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         bindgroup.setValue('withAerialPerspective', this.skyType === 'scatter' ? 1 : 0);
         bindgroup.setValue('fogType', this.mappedFogType);
         bindgroup.setValue('atmosphereParams', this._atmosphereParams);
-        bindgroup.setValue('heightFogParams', this._getUploadHeightFogParams());
+        bindgroup.setValue('heightFogParams', this.getUploadHeightFogParams());
         device.setProgram(fogProgram);
         device.setBindGroup(0, bindgroup);
         device.setVertexLayout(SkyRenderer._vertexLayout);
@@ -758,7 +1091,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
    * physical space when physical lighting is active, plus the pre-exposure the shader applies to its
    * atmosphere-derived LUT samples. Legacy returns the stored params untouched so its upload stays
    * byte-identical. Stored authored values are never mutated.
-   */ _getUploadHeightFogParams() {
+   */ getUploadHeightFogParams() {
         const scale = this._fogLuminanceScale;
         const p = this._heightFogParams;
         if (scale === 1 && this._fogPreExposure === 1) {
@@ -853,6 +1186,9 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         this._irradianceSHFB.dispose();
         this._irradianceFrameBuffer.dispose();
         this._shProjector.dispose();
+        this._volumetricCloudResources.dispose();
+        this._volumetricCloudCache.dispose();
+        this._bindgroupSkyVolumetric.dispose();
         if (this._skyDistantLightLut.get()) {
             this._skyDistantLightLut.get().getColorAttachments()[0].dispose();
             this._skyDistantLightLut.dispose();
@@ -885,13 +1221,13 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             });
         }
     }
-    /** @internal */ _renderSky(camera, depthTest, includeSunDisk, luminanceScale = 1) {
+    /** @internal */ _renderSky(camera, depthTest, includeSunDisk, luminanceScale = 1, lowerHemisphereBlack = false) {
         const device = getDevice();
         const savedRenderStates = device.getRenderStates();
         this._prepareSkyBox(device);
         if (this._skyType === 'scatter') {
             // The atmosphere LUTs already hold physical luminance, so only the caller's exposure applies.
-            this._drawScattering(camera, depthTest, includeSunDisk, luminanceScale);
+            this._drawScattering(camera, depthTest, includeSunDisk, luminanceScale, lowerHemisphereBlack);
         } else if (this._skyType === 'skybox' && this.skyboxTexture) {
             this._drawSkybox(camera, depthTest, luminanceScale);
         } else {
@@ -998,7 +1334,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
    * clouds at low coverage barely attenuating the sun, while full cover drops to the
    * heavy-overcast floor {@link SkyRenderer.CLOUD_SUN_MIN_TRANSMITTANCE}.
    */ cloudSunTransmittance(_sunDir) {
-        if (this._skyType !== 'scatter') {
+        // Volumetric clouds shade the sun per pixel through their shadow instead
+        if (this._skyType !== 'scatter' || this._volumetricActive) {
             return Vector3.one();
         }
         const coverage = Math.min(1, Math.max(0, this._cloudy));
@@ -1021,25 +1358,25 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         ];
         function rayleighSc(params, fH) {
             const sigma = new Vector3(RAYLEIGH_SIGMA[0] * 1e-6, RAYLEIGH_SIGMA[1] * 1e-6, RAYLEIGH_SIGMA[2] * 1e-6);
-            const rho_h = Math.exp(-fH / params.rayleighScatteringHeight);
+            const rho_h = Math.exp(-Math.max(fH, 0) / params.rayleighScatteringHeight);
             return Vector3.scale(sigma, rho_h);
         }
         function mieSc(params, fH) {
             const sigma = new Vector3(MIE_SIGMA * 1e-6, MIE_SIGMA * 1e-6, MIE_SIGMA * 1e-6);
-            const rho_h = Math.exp(-(fH / params.mieScatteringHeight));
+            const rho_h = Math.exp(-Math.max(fH, 0) / params.mieScatteringHeight);
             return Vector3.scale(sigma, rho_h);
         }
         function mieAb(params, fH) {
             const sigma = new Vector3(MIE_ABSORPTION_SIGMA * 1e-6, MIE_ABSORPTION_SIGMA * 1e-6, MIE_ABSORPTION_SIGMA * 1e-6);
-            const rho_h = Math.exp(-(fH / params.mieScatteringHeight));
+            const rho_h = Math.exp(-Math.max(fH, 0) / params.mieScatteringHeight);
             return Vector3.scale(sigma, rho_h);
         }
         function ozoneAb(params, fH) {
             const sigma = new Vector3(OZONE_ABSORPTION_SIGMA[0] * 1e-6, OZONE_ABSORPTION_SIGMA[1] * 1e-6, OZONE_ABSORPTION_SIGMA[2] * 1e-6);
-            const rho_h = Math.max(0, 1 - Math.abs(fH - params.ozoneCenter) * 0.5 / params.ozoneWidth);
+            const rho_h = Math.max(0, 1 - Math.abs(fH - params.ozoneCenter) / params.ozoneWidth);
             return Vector3.scale(sigma, rho_h);
         }
-        const eyePos = new Vector3(0, this._atmosphereParams.plantRadius + this._atmosphereParams.cameraHeightScale, 0);
+        const eyePos = new Vector3(0, this._atmosphereParams.plantRadius + MIN_OBSERVER_ALTITUDE, 0);
         const lightDir = SkyRenderer._getSunDir(sunLight);
         const d = this._rayIntersectSphere(this._atmosphereParams.plantRadius + this._atmosphereParams.atmosphereHeight, eyePos, lightDir);
         if (d < 0) {
@@ -1058,27 +1395,38 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return new Vector3(Math.exp(-sum.x), Math.exp(-sum.y), Math.exp(-sum.z));
     }
-    /** @internal */ _drawScattering(camera, depthTest, includeSunDisk, luminanceScale) {
+    /** @internal */ _drawScattering(camera, depthTest, includeSunDisk, luminanceScale, lowerHemisphereBlack) {
         const device = getDevice();
         const tLut = getTransmittanceLut();
         const skyLut = getSkyViewLut();
         //const apLut = ScatteringLut.getAerialPerspectiveLut(alpha, 8000);
-        const program = SkyRenderer._programSky.scatter;
-        const bindgroup = this._bindgroupSky.scatter.get();
+        const volumetric = this._volumetricActive;
+        const program = volumetric ? SkyRenderer._programSkyVolumetric : SkyRenderer._programSky.scatter;
+        const bindgroup = volumetric ? this._bindgroupSkyVolumetric.get() : this._bindgroupSky.scatter.get();
+        if (volumetric) {
+            const cache = this._volumetricCloudCache;
+            bindgroup.setTexture('cloudFrom', cache.fromMap, fetchSampler('clamp_linear_nomip'));
+            bindgroup.setTexture('cloudTo', cache.toMap, fetchSampler('clamp_linear_nomip'));
+            bindgroup.setValue('cloudBlend', new Vector4(cache.blend, cache.fromDelta, cache.toDelta, 0));
+        }
         bindgroup.setValue('flip', device.getFramebuffer() && device.type === 'webgpu' ? new Vector4(1, -1, 1, 1) : new Vector4(1, 1, 1, 1));
         bindgroup.setValue('params', this._atmosphereParams);
         bindgroup.setValue('viewProjMatrix', camera.viewProjectionMatrix);
         bindgroup.setValue('worldMatrix', this._skyWorldMatrix);
         bindgroup.setValue('cameraPos', camera.getWorldPosition());
         bindgroup.setValue('srgbOut', device.getFramebuffer() ? 0 : 1);
-        bindgroup.setValue('includeSunDisk', includeSunDisk ? 1 : 0);
+        bindgroup.setValue('includeSunDisk', includeSunDisk ? this._physicalSunDisk ? 2 : 1 : 0);
+        bindgroup.setValue('lowerHemisphereBlack', lowerHemisphereBlack ? 1 : 0);
         bindgroup.setValue('luminanceScale', luminanceScale);
         bindgroup.setTexture('tLut', tLut, fetchSampler('clamp_linear_nomip'));
         bindgroup.setTexture('skyLut', skyLut, fetchSampler('clamp_linear_nomip'));
-        bindgroup.setValue('cloudy', this._cloudy);
-        bindgroup.setValue('cloudIntensity', this._cloudIntensity);
-        bindgroup.setValue('time', device.frameInfo.elapsedOverall * 0.001);
-        bindgroup.setValue('velocity', this._wind);
+        bindgroup.setTexture('msLut', getMultiScatteringLut(), fetchSampler('clamp_linear_nomip'));
+        if (!volumetric) {
+            bindgroup.setValue('cloudy', this._cloudy);
+            bindgroup.setValue('cloudIntensity', this._cloudIntensity);
+            bindgroup.setValue('time', device.frameInfo.elapsedOverall * 0.001);
+            bindgroup.setValue('velocity', this._wind);
+        }
         device.setProgram(program);
         device.setBindGroup(0, bindgroup);
         device.setRenderStates(depthTest ? SkyRenderer._renderStatesSky : SkyRenderer._renderStatesSkyNoDepthTest);
@@ -1182,7 +1530,13 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this._bindgroupSky.image = new DRef(device.createBindGroup(SkyRenderer._programSky.image.bindGroupLayouts[0]));
         }
         if (!SkyRenderer._programSky.scatter) {
-            SkyRenderer._programSky.scatter = SkyRenderer._createScatterProgram(device, true);
+            SkyRenderer._programSky.scatter = SkyRenderer._createScatterProgram(device, 'procedural');
+        }
+        if (!SkyRenderer._programSkyVolumetric) {
+            SkyRenderer._programSkyVolumetric = SkyRenderer._createScatterProgram(device, 'volumetric');
+        }
+        if (!this._bindgroupSkyVolumetric.get()) {
+            this._bindgroupSkyVolumetric.set(device.createBindGroup(SkyRenderer._programSkyVolumetric.bindGroupLayouts[0]));
         }
         if (!this._bindgroupSky.scatter) {
             this._bindgroupSky.scatter = new DRef(device.createBindGroup(SkyRenderer._programSky.scatter.bindGroupLayouts[0]));
@@ -1322,6 +1676,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 }
                 this.apLut = pb.tex2D().uniform(0);
                 this.skyDistantLightLut = pb.tex2D().uniform(0);
+                this.skyLightCubemap = pb.texCube().uniform(0);
                 this.invProjViewMatrix = pb.mat4().uniform(0);
                 this.cameraNearFar = pb.vec2().uniform(0);
                 this.cameraPosition = pb.vec3().uniform(0);
@@ -1337,7 +1692,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                     this.$l.hPos = pb.mul(this.invProjViewMatrix, this.clipSpacePos);
                     this.$l.worldPos = pb.div(this.$l.hPos, this.$l.hPos.w).xyz;
                     this.$l.isSky = ShaderHelper.isFarthestDepth(this, this.$l.depthValue);
-                    this.$l.color = calculateFog(this, this.withAerialPerspective, this.fogType, this.atmosphereParams, this.heightFogParams, this.$inputs.uv, this.isSky, this.cameraPosition, this.worldPos, 0, this.apLut, this.skyDistantLightLut);
+                    this.$l.color = calculateFog(this, this.withAerialPerspective, this.fogType, this.atmosphereParams, this.heightFogParams, this.$inputs.uv, this.isSky, this.cameraPosition, this.worldPos, 0, this.apLut, this.skyDistantLightLut, this.skyLightCubemap);
                     this.$if(pb.equal(this.srgbOut, 0), function() {
                         this.$outputs.outColor = this.color;
                     }).$else(function() {
@@ -1371,7 +1726,9 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.APLutProgram = createAPLutProgram(device);
         }
     }
-    static _createScatterProgram(device, cloud) {
+    static _createScatterProgram(device, cloudMode) {
+        const cloud = cloudMode === 'procedural';
+        const volumetric = cloudMode === 'volumetric';
         const program = device.buildRenderProgram({
             vertex (pb) {
                 this.$inputs.pos = pb.vec3().attrib('position');
@@ -1389,8 +1746,16 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 this.$outputs.outColor = pb.vec4();
                 this.tLut = pb.tex2D().uniform(0);
                 this.skyLut = pb.tex2D().uniform(0);
+                this.msLut = pb.tex2D().uniform(0);
                 this.params = getAtmosphereParamsStruct(pb)().uniform(0);
                 this.includeSunDisk = pb.int().uniform(0);
+                this.lowerHemisphereBlack = pb.int().uniform(0);
+                if (volumetric) {
+                    this.cloudFrom = pb.tex2D().uniform(0);
+                    this.cloudTo = pb.tex2D().uniform(0);
+                    // (blend, delta of cloudFrom, delta of cloudTo, 0)
+                    this.cloudBlend = pb.vec4().uniform(0);
+                }
                 if (cloud) {
                     this.cloudy = pb.float().uniform(0);
                     this.cloudIntensity = pb.float().uniform(0);
@@ -1399,67 +1764,132 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 }
                 this.srgbOut = pb.int().uniform(0);
                 this.luminanceScale = pb.float().uniform(0);
+                // Six-octave fbm. `footprint` is the pixel size in p units: an octave whose features get close
+                // to it is faded to its mean (0.5) instead of aliasing into speckles, e.g. seen from space.
                 pb.func('noise', [
                     pb.vec3('p'),
-                    pb.float('t')
+                    pb.float('t'),
+                    pb.float('footprint')
                 ], function() {
-                    this.p2 = pb.mul(this.p, 0.25);
-                    this.f = pb.mul(smoothNoise3D(this, this.p2), 0.5);
-                    this.p2 = pb.mul(this.p2, 3.02);
-                    this.p2.y = pb.sub(this.p2.y, pb.mul(this.t, 0.02));
-                    this.f = pb.add(this.f, pb.mul(smoothNoise3D(this, this.p2), 0.25));
-                    this.p2 = pb.mul(this.p2, 3.03);
-                    this.p2.y = pb.add(this.p2.y, pb.mul(this.t, 0.01));
-                    this.f = pb.add(this.f, pb.mul(smoothNoise3D(this, this.p2), 0.125));
-                    this.p2 = pb.mul(this.p2, 3.02);
-                    this.f = pb.add(this.f, pb.mul(smoothNoise3D(this, this.p2), 0.0625));
-                    this.p2 = pb.mul(this.p2, 3.01);
-                    this.f = pb.add(this.f, pb.mul(smoothNoise3D(this, this.p2), 0.03125));
-                    this.p2 = pb.mul(this.p2, 3.01);
-                    this.f = pb.add(this.f, pb.mul(smoothNoise3D(this, this.p2), 0.015625));
+                    this.$l.p2 = pb.mul(this.p, 0.25);
+                    this.$l.freq = pb.float(0.25);
+                    this.$l.f = pb.float(0);
+                    const octaves = [
+                        {
+                            mul: 1,
+                            weight: 0.5,
+                            dt: 0
+                        },
+                        {
+                            mul: 3.02,
+                            weight: 0.25,
+                            dt: -0.02
+                        },
+                        {
+                            mul: 3.03,
+                            weight: 0.125,
+                            dt: 0.01
+                        },
+                        {
+                            mul: 3.02,
+                            weight: 0.0625,
+                            dt: 0
+                        },
+                        {
+                            mul: 3.01,
+                            weight: 0.03125,
+                            dt: 0
+                        },
+                        {
+                            mul: 3.01,
+                            weight: 0.015625,
+                            dt: 0
+                        }
+                    ];
+                    for (const o of octaves){
+                        if (o.mul !== 1) {
+                            this.p2 = pb.mul(this.p2, o.mul);
+                            this.freq = pb.mul(this.freq, o.mul);
+                        }
+                        if (o.dt !== 0) {
+                            this.p2.y = pb.add(this.p2.y, pb.mul(this.t, o.dt));
+                        }
+                        this.$l.fade = pb.sub(1, pb.smoothStep(0.25, 0.75, pb.mul(this.footprint, this.freq)));
+                        this.f = pb.add(this.f, pb.mul(pb.mix(0.5, smoothNoise3D(this, this.p2), this.fade), o.weight));
+                    }
                     this.$return(this.f);
                 });
                 pb.main(function() {
-                    // Calculate sky color
-                    this.$l.sunColor = pb.vec4();
-                    this.$l.skyColor = skyBox(this, this.params, this.sunColor, this.$inputs.worldDirection, pb.float(0.01), this.includeSunDisk, this.tLut, this.skyLut).rgb;
-                    this.$l.rayDir = pb.normalize(this.$inputs.worldDirection);
+                    // Everything below runs in the observer's local frame (up = +Y), see skyViewReferential.
+                    this.$l.rayDir = pb.normalize(pb.mul(this.params.skyViewReferential, pb.vec4(this.$inputs.worldDirection, 0)).xyz);
                     this.$l.sunDir = this.params.lightDir;
-                    // ad-hoc
-                    this.$l.sunIntensity = pb.sqrt(pb.max(0, pb.mul(this.sunDir.y, this.rayDir.y)));
-                    // compute cloud
+                    // Angular size of a pixel, taken here in uniform control flow (WGSL requires it).
+                    this.$l.pixelAngle = pb.length(pb.fwidth(this.rayDir));
+                    // The sun disk's anti-aliasing wants the pixel pitch itself; the fwidth sum above runs up
+                    // to twice that along diagonals, which is fine for fading noise but would blur the rim.
+                    this.$l.sunPixelAngle = pb.max(pb.length(pb.dpdx(this.rayDir)), pb.length(pb.dpdy(this.rayDir)));
+                    this.$l.sunColor = pb.vec4();
+                    this.$l.skyColor = skyBox(this, this.params, this.sunColor, this.rayDir, pb.float(0.01), this.includeSunDisk, this.sunPixelAngle, pb.div(SKY_OUTPUT_MAX, pb.max(this.luminanceScale, 1e-8)), this.tLut, this.skyLut, this.msLut).rgb;
+                    // Procedural cloud layer: a spherical shell 3 km above the ground, so it is seen from
+                    // below, from above and wrapped around the planet from space. Near the world origin the
+                    // shell point matches the flat layer this used to be.
                     if (cloud) {
-                        this.$l.noiseValue = pb.float();
-                        this.$if(pb.lessThanEqual(this.rayDir.y, 0), function() {
-                            this.noiseValue = 0;
-                        }).$else(function() {
-                            this.$l.tMin = pb.div(3000, this.rayDir.y);
-                            this.$l.cloudPoint = pb.mul(this.rayDir, this.tMin);
+                        this.$l.eyePos = pb.vec3(0, pb.add(this.params.plantRadius, this.params.observerAltitude), 0);
+                        this.$l.cloudRadius = pb.add(this.params.plantRadius, 3000);
+                        this.$l.tCloud = rayIntersectSphere(this, pb.vec3(0), this.cloudRadius, this.eyePos, this.rayDir);
+                        this.$l.tGround = rayIntersectSphere(this, pb.vec3(0), this.params.plantRadius, this.eyePos, this.rayDir);
+                        // Below the shell the ray leaves through it unless the ground is in the way; above it the
+                        // shell is always hit before the ground.
+                        this.$l.hasCloud = pb.and(pb.greaterThan(this.tCloud, 0), pb.or(pb.greaterThanEqual(this.params.observerAltitude, 3000), pb.or(pb.lessThanEqual(this.tGround, 0), pb.lessThan(this.tCloud, this.tGround))));
+                        this.$l.noiseValue = pb.float(0);
+                        this.$l.cloudColor = pb.vec3(0);
+                        this.$l.vfactor = pb.float(0);
+                        this.$if(this.hasCloud, function() {
+                            this.$l.hitPos = pb.add(this.eyePos, pb.mul(this.rayDir, this.tCloud));
+                            this.$l.hitUp = pb.normalize(this.hitPos);
+                            // Anchor the clouds to the planet, not to the observer: back to the world-aligned planet
+                            // frame (the transpose of the rotation), relative to the planet top at the world origin.
+                            this.$l.planetHit = pb.mul(pb.vec4(this.hitPos, 0), this.params.skyViewReferential).xyz;
+                            this.$l.cloudPoint = pb.sub(this.planetHit, pb.vec3(0, this.params.plantRadius, 0));
                             this.speed = pb.mul(pb.vec3(this.velocity.x, 0, this.velocity.y), this.time);
                             this.$l.noiseScale = pb.float(4e-4);
-                            this.noiseValue = this.noise(pb.mul(pb.add(this.cloudPoint, this.speed), this.noiseScale), this.time);
+                            this.noiseValue = this.noise(pb.mul(pb.add(this.cloudPoint, this.speed), this.noiseScale), this.time, pb.mul(this.tCloud, this.pixelAngle, this.noiseScale));
                             this.noiseValue = pb.add(this.noiseValue, this.cloudy);
                             this.noiseValue = pb.smoothStep(1, pb.add(1, this.cloudy), this.noiseValue);
+                            // Ad hoc lighting, generalized from the flat layer: sun elevation at the cloud times
+                            // the viewing obliquity, lit from either side. The sun reaches the cloud through the
+                            // atmosphere above it (planet shadowed on the night side).
+                            this.$l.cosView = pb.abs(pb.dot(this.rayDir, this.hitUp));
+                            this.$l.sunIntensity = pb.sqrt(pb.max(0, pb.mul(pb.dot(this.hitUp, this.sunDir), this.cosView)));
+                            this.$l.sunAtCloud = transmittanceToSky(this, this.params, this.hitPos, this.sunDir, this.tLut);
+                            this.cloudColor = pb.mul(this.params.lightColor.rgb, this.sunAtCloud, this.sunIntensity, pb.mul(this.noiseValue, this.cloudIntensity));
+                            // Fade out at grazing angles, where the layer aliases
+                            this.vfactor = pb.clamp(pb.div(pb.sub(this.cosView, 0.01), pb.sub(0.03, 0.01)), 0, 1);
                         });
-                        // use sun color as cloud color
-                        /*
-            this.$l.sunColor = pb.mul(
-              pb.textureSampleLevel(this.skyLut, viewDirToUV(this, this.sunDir), 0),
-              this.sunIntensity
-            );
-            */ this.$l.cloudColor = pb.mul(this.sunColor.rgb, this.sunIntensity, pb.mul(this.noiseValue, this.cloudIntensity));
-                    }
-                    // Compute sky color
-                    if (cloud) {
-                        // blend
-                        this.$l.vfactor = pb.clamp(pb.div(pb.sub(this.rayDir.y, 0.01), pb.sub(0.03, 0.01)), 0, 1);
                         this.$l.factor = pb.clamp(pb.mul(this.noiseValue, this.vfactor), 0, 1);
                         this.$l.color = pb.mix(this.skyColor, this.cloudColor, this.factor);
+                    } else if (volumetric) {
+                        // Cached clouds: (luminance, transmittance) over the sky, blended between the two
+                        // latest completed maps. Below -delta a map holds no clouds.
+                        this.$l.color = this.skyColor;
+                        this.$l.elevation = pb.asin(pb.clamp(this.rayDir.y, -1, 1));
+                        this.$l.cFrom = pb.vec4(0, 0, 0, 1);
+                        this.$l.cTo = pb.vec4(0, 0, 0, 1);
+                        this.$if(pb.greaterThanEqual(this.elevation, pb.neg(this.cloudBlend.y)), function() {
+                            this.cFrom = pb.textureSampleLevel(this.cloudFrom, cloudCacheEncode(this, this.rayDir, this.cloudBlend.y), 0);
+                        });
+                        this.$if(pb.greaterThanEqual(this.elevation, pb.neg(this.cloudBlend.z)), function() {
+                            this.cTo = pb.textureSampleLevel(this.cloudTo, cloudCacheEncode(this, this.rayDir, this.cloudBlend.z), 0);
+                        });
+                        this.$l.clouds = pb.mix(this.cFrom, this.cTo, this.cloudBlend.x);
+                        this.color = pb.add(pb.mul(this.color, this.clouds.a), this.clouds.rgb);
                     } else {
                         this.$l.color = this.skyColor;
                     }
-                    // 1 for legacy and for the IBL bake; the camera pre-exposure when drawn on screen.
-                    this.color = pb.mul(this.color, this.luminanceScale);
+                    this.$if(pb.and(pb.notEqual(this.lowerHemisphereBlack, 0), pb.lessThan(this.rayDir.y, 0)), function() {
+                        this.color = pb.vec3(0);
+                    });
+                    this.color = pb.min(pb.mul(this.color, this.luminanceScale), pb.vec3(SKY_OUTPUT_MAX));
                     this.$if(pb.equal(this.srgbOut, 0), function() {
                         this.$outputs.outColor = pb.vec4(this.color, 1);
                     }).$else(function() {
@@ -1468,7 +1898,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 });
             }
         });
-        program.name = cloud ? '@SkyScatterCloud' : '@SkyScatter';
+        program.name = cloud ? '@SkyScatterCloud' : volumetric ? '@SkyScatterVolumetricCloud' : '@SkyScatter';
         return program;
     }
 }