@zephyr3d/scene 0.9.22 → 0.9.24

package/dist/render/sky.js

@@ -2,7 +2,7 @@ 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 } from '@zephyr3d/base';
+import { Matrix4x4, Disposable, DRef, Vector4, Vector2, Vector3, CubeFace, objectKeys, DEPTH_FARTHEST, DEPTH_COMPARE_DEFAULT, DEPTH_COMPARE_FARTHER } from '@zephyr3d/base';
 import { Primitive } from './primitive.js';
 import { BoxShape } from '../shapes/box.js';
 import '../shapes/capsule.js';
@@ -13,6 +13,7 @@ import '../shapes/sphere.js';
 import '../shapes/tetrahedron.js';
 import { prefilterCubemap } from '../utility/pmrem.js';
 import { ShaderHelper } from '../material/shader/helper.js';
+import { PHYSICAL_BAKE_EXPOSURE } from '../utility/physical.js';
 import { fetchSampler } from '../utility/misc.js';
 import { CubemapSHProjector } from '../utility/shprojector.js';
 import { uniformSphereSamples, Fog } from '../values.js';
@@ -27,10 +28,30 @@ const fogTypeMap = {
     none: Fog.FOG_TYPE_NONE
 };
 const defaultSkyWorldMatrix = Matrix4x4.identity();
-/**
- * The sky renderer
- * @public
+/**
+ * The sky renderer
+ * @public
  */ class SkyRenderer extends Disposable {
+    /**
+   * @internal
+   *
+   * The atmospheric scattering model predates photometric lighting and was authored around a
+   * sun input of 10. This normalization maps the physical daylight reference (100,000 lux at
+   * Sunny 16, whose camera exposure is 1 / 38,400) onto that model reference: 10 / (100000 / 38400).
+   */ static PHYSICAL_ATMOSPHERE_LUMINANCE_SCALE = 3.84;
+    /**
+   * @internal
+   * Fixed exposure the physical sky bake is stored at. See {@link PHYSICAL_BAKE_EXPOSURE}.
+   */ static PHYSICAL_BAKE_EXPOSURE = PHYSICAL_BAKE_EXPOSURE;
+    /**
+   * @internal
+   *
+   * Reference-exposure anchor previously used to lift authored fog colors into photometric space.
+   *
+   * @deprecated Physical fog now derives its luminance from `EnvLightWrapper.intensity`, mirroring
+   * Filament, which scales fog color by `iblLuminance`. Retained only because it documents the
+   * Sunny-16 equivalence: 38,400 = 1 / exposure(f/16, 1/125s, ISO 100).
+   */ static FOG_PHYSICAL_LUMINANCE = 38400;
     static _skyCamera = (()=>{
         return new PerspectiveCamera(null, Math.PI * 0.5, 1, 20, 1);
     })();
@@ -89,8 +110,16 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
     _bindgroupFog = null;
     _bindgroupFogNoDepth = null;
     _format;
-    /**
-   * Creates an instance of SkyRenderer
+    /**
+   * @internal Scale lifting the authored 0..1 height-fog colors into the pre-exposed space for the
+   * current frame (1 in legacy, `EnvLightWrapper.intensity * cameraExposure` in physical).
+   */ _fogLuminanceScale;
+    /**
+   * @internal Ratio converting the fog shader's atmosphere-derived LUT samples from the fixed bake
+   * exposure to the live one (1 in legacy).
+   */ _fogPreExposure;
+    /**
+   * Creates an instance of SkyRenderer
    */ constructor(){
         super();
         this._skyType = 'scatter';
@@ -131,12 +160,14 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         this._bindgroupFog = new DRef();
         this._bindgroupFogNoDepth = new DRef();
         this._format = null;
+        this._fogLuminanceScale = 1;
+        this._fogPreExposure = 1;
     }
     /** @internal */ getHash(_ctx) {
         return `${this.skyType}:${this.fogType}`;
     }
-    /**
-   * Gets the preferred environment texture format.
+    /**
+   * Gets the preferred environment texture format.
    */ get envTextureFormat() {
         if (!this._format) {
             const texCaps = getDevice().getDeviceCaps().textureCaps;
@@ -181,8 +212,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return this._bakedSkyboxTexture.get();
     }
-    /**
-   * The color used when sky type is `image`
+    /**
+   * The color used when sky type is `image`
    */ get skyColor() {
         return this._skyColor;
     }
@@ -192,8 +223,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * The image used when sky type is `image`
+    /**
+   * The image used when sky type is `image`
    */ get skyImage() {
         return this._skyImage.get();
     }
@@ -203,8 +234,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Window weights for SH projection
+    /**
+   * Window weights for SH projection
    */ get shWindowWeights() {
         return this._shWindowWeights;
     }
@@ -212,8 +243,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         this._shWindowWeights.set(weights);
         this.invalidate();
     }
-    /**
-   * Sample count for radiance convolution
+    /**
+   * Sample count for radiance convolution
    */ get radianceConvSamples() {
         return this._radianceConvSamples;
     }
@@ -223,8 +254,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Sample count for irradiance convolution
+    /**
+   * Sample count for irradiance convolution
    */ get irradianceConvSamples() {
         return this._irradianceConvSamples;
     }
@@ -351,12 +382,12 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Light density of the sky.
-   *
-   * @remarks
-   * This value controls how much cloud should be rendered when the sky type is scatter.
-   * Typically, the value should be in the range of 0 to 1.
+    /**
+   * Light density of the sky.
+   *
+   * @remarks
+   * This value controls how much cloud should be rendered when the sky type is scatter.
+   * Typically, the value should be in the range of 0 to 1.
    */ get cloudy() {
         return this._cloudy;
     }
@@ -366,8 +397,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Intensity of the sky color
+    /**
+   * Intensity of the sky color
    */ get cloudIntensity() {
         return this._cloudIntensity;
     }
@@ -377,19 +408,19 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Wind velocity
-   *
-   * @remarks
-   * This value affects the movement of the cloud
+    /**
+   * Wind velocity
+   *
+   * @remarks
+   * This value affects the movement of the cloud
    */ get wind() {
         return this._wind;
     }
     set wind(val) {
         this._wind.set(val);
     }
-    /**
-   * Radiance map of the sky.
+    /**
+   * Radiance map of the sky.
    */ get radianceMap() {
         if (!this._radianceMap.get()) {
             this._radianceMap.set(getDevice().createCubeTexture(this.envTextureFormat, this._radianceMapWidth));
@@ -397,11 +428,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return this._radianceMap.get();
     }
-    /**
-   * Radiance map of the sky reused for sheen.
-   *
-   * @remarks
-   * Dynamic sky is smooth enough that the GGX-prefiltered radiance map is a practical approximation for sheen.
+    /**
+   * Radiance map of the sky reused for sheen.
+   *
+   * @remarks
+   * Dynamic sky is smooth enough that the GGX-prefiltered radiance map is a practical approximation for sheen.
    */ get sheenRadianceMap() {
         return this.radianceMap;
     }
@@ -419,8 +450,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return this._radianceFrameBuffer.get();
     }
-    /**
-   * Irradiance SH coeffecients buffer
+    /**
+   * Irradiance SH coeffecients buffer
    */ get irradianceSH() {
         if (!this._irradianceSH.get()) {
             const buffer = getDevice().createBuffer(4 * 4 * 9, {
@@ -430,8 +461,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return this._irradianceSH.get();
     }
-    /**
-   * Irradiance SH coeffecients texture
+    /**
+   * Irradiance SH coeffecients texture
    */ get irradianceSHFB() {
         if (!this._irradianceSHFB.get()) {
             const device = getDevice();
@@ -446,8 +477,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return this._irradianceSHFB.get();
     }
-    /**
-   * Cube texture for skybox.
+    /**
+   * Cube texture for skybox.
    */ get skyboxTexture() {
         return this._skyboxTexture.get();
     }
@@ -459,8 +490,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             }
         }
     }
-    /**
-   * Additional euler rotation (in degrees) applied to skybox.
+    /**
+   * Additional euler rotation (in degrees) applied to skybox.
    */ get skyboxRotation() {
         return this._skyboxRotation;
     }
@@ -503,8 +534,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
     /** @internal */ get fogPresents() {
         return this._skyType === 'scatter' || this._fogType !== 'none';
     }
-    /**
-   * Force the radiance map and irradiance map to be regenerated.
+    /**
+   * Force the radiance map and irradiance map to be regenerated.
    */ invalidate() {
         this._bakedSkyboxDirty = true;
     }
@@ -518,6 +549,18 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         return this._skyDistantLightLut.get().getColorAttachments()[0];
     }
     update(ctx) {
+        // 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.
+        // The fog shader mixes two differently-scaled sources, so it needs both factors:
+        //  - the atmosphere-derived LUTs (distant sky, aerial perspective) are stored at the fixed bake
+        //    exposure, so they convert with the bake-to-live ratio;
+        //  - the authored 0..1 fog colors are lifted by the environment intensity (lux) -- the same
+        //    anchor the sky and IBL use, mirroring Filament's `fogColor *= iblLuminance` -- and then
+        //    take the plain camera pre-exposure.
+        // Legacy leaves both at 1 so its authored colors are untouched.
+        this._fogPreExposure = SkyRenderer.getBakeToPreExposedScale(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);
@@ -545,16 +588,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         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.
             this.updateBakedSkyMap(ctx);
             this.renderSkyDistantLut(ctx, this._bakedSkyboxTexture.get());
-            if (ctx.scene.env.light.radianceMap && (ctx.scene.env.light.radianceMap === this.radianceMap || this._irradianceSH.get() && ctx.scene.env.light.irradianceSH === this.irradianceSH || this._irradianceSHFB.get() && ctx.scene.env.light.irradianceSHFB === this.irradianceSHFB)) {
-                prefilterCubemap(this._bakedSkyboxTexture.get(), 'ggx', this.radianceFramebuffer, this._radianceConvSamples);
-                ctx.scene.env.light.sheenRadianceMap = this.radianceMap;
-                this._shProjector.projectCubemapToTexture(this._bakedSkyboxTexture.get(), this.irradianceSHFB);
-                ctx.scene.env.light.irradianceSHFB = this.irradianceSHFB;
-                ctx.scene.env.light.irradianceSH = null;
-                ctx.scene.env.light.irradianceWindow = this._shWindowWeights;
-            }
         }
         const newSunLight = oldSunLight ? Vector3.mul(ctx.sunLight.color.xyz(), this.sunTransmittance(ctx.sunLight)) : Vector3.zero();
         if (oldSunLight) {
@@ -565,7 +603,14 @@ 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);
-            this._heightFogParams.lightColor.set(newSunLight);
+            // 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);
+            } else {
+                this._heightFogParams.lightColor.set(newSunLight);
+            }
             this._heightFogParams.lightDir.set(SkyRenderer._getSunDir(ctx.sunLight));
         }
         return oldSunLight;
@@ -573,7 +618,12 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
     renderAtmosphereLUTs(ctx) {
         this._atmosphereParams.lightDir.set(SkyRenderer._getSunDir(ctx.sunLight));
         this._atmosphereParams.lightColor.set(SkyRenderer._getSunColor(ctx.sunLight));
-        this._atmosphereParams.lightColor.w *= this._atmosphereExposure;
+        // 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);
         renderAtmosphereLUTs(this._atmosphereParams);
@@ -586,6 +636,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         ctx.device.setFramebuffer(this._skyDistantLightLut.get());
         ctx.device.clearFrameBuffer(new Vector4(0, 0, 0, 1), null, null);
         this._bindgroupDistantLight.get().setTexture('skybox', skybox, fetchSampler('clamp_linear_nomip'));
+        this._bindgroupDistantLight.get().setValue('physical', ctx.scene.lightingMode === 'physical' ? 1 : 0);
         ctx.device.setBindGroup(0, this._bindgroupDistantLight.get());
         SkyRenderer._primitiveDistantLight.draw();
         ctx.device.popDeviceStates();
@@ -615,10 +666,24 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         ]){
             camera.lookAtCubeFace(face);
             this._bakedSkyboxFrameBuffer.get().setColorAttachmentCubeFace(0, face);
-            this._renderSky(camera, false);
+            // 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));
         }
         device.popDeviceStates();
         this.renderSkyDistantLut(ctx, tex);
+        // Publish the texture reference before deriving IBL so _updateIBLFromBakedSky reads the
+        // current cubemap.
+        this._bakedSkyboxTexture.set(tex);
+        // Derive the IBL from the fog-free cubemap. Height fog is a view/position-dependent participating
+        // medium applied per-pixel in screen space (see lightpass renderFog); baking it into the distant
+        // environment probe would both double-count it against that screen-space pass and wrongly lift the
+        // lower hemisphere (ground direction) from the atmosphere's dark value to a bright fog color. The
+        // same reasoning that keeps the sun disk out of the IBL applies to fog, for diffuse and specular alike.
+        this._updateIBLFromBakedSky(ctx, tex);
+        // Composite fog into the cubemap afterwards. This copy is only used as the visible skybox
+        // background (UNIFORM_NAME_BAKED_SKY_MAP), where the fogged distant sky is desired.
         device.pushDeviceStates();
         device.setFramebuffer(this._bakedSkyboxFrameBuffer.get());
         for (const face of [
@@ -635,7 +700,21 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         device.popDeviceStates();
         device.setRenderStates(saveRenderStates);
-        this._bakedSkyboxTexture.set(tex);
+    }
+    /**
+   * @internal
+   * Updates the scene's IBL (GGX-prefiltered specular radiance map + irradiance SH) from the given
+   * cubemap, provided the scene environment light is still driven by this dynamic sky. Must be called
+   * with the fog-free cubemap so height fog does not leak into the environment lighting.
+   */ _updateIBLFromBakedSky(ctx, skybox) {
+        if (ctx.scene.env.light.radianceMap && (ctx.scene.env.light.radianceMap === this.radianceMap || this._irradianceSH.get() && ctx.scene.env.light.irradianceSH === this.irradianceSH || this._irradianceSHFB.get() && ctx.scene.env.light.irradianceSHFB === this.irradianceSHFB)) {
+            prefilterCubemap(skybox, 'ggx', this.radianceFramebuffer, this._radianceConvSamples);
+            ctx.scene.env.light.sheenRadianceMap = this.radianceMap;
+            this._shProjector.projectCubemapToTexture(skybox, this.irradianceSHFB);
+            ctx.scene.env.light.irradianceSHFB = this.irradianceSHFB;
+            ctx.scene.env.light.irradianceSH = null;
+            ctx.scene.env.light.irradianceWindow = this._shWindowWeights;
+        }
     }
     renderUberFog(camera, depthTexture) {
         const device = getDevice();
@@ -655,13 +734,34 @@ 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._heightFogParams);
+        bindgroup.setValue('heightFogParams', this._getUploadHeightFogParams());
         device.setProgram(fogProgram);
         device.setBindGroup(0, bindgroup);
         device.setVertexLayout(SkyRenderer._vertexLayout);
         device.setRenderStates(renderStates);
         device.draw('triangle-strip', 0, 4);
     }
+    /**
+   * @internal
+   * Height-fog upload params with the authored base/directional colors lifted into the pre-exposed
+   * 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() {
+        const scale = this._fogLuminanceScale;
+        const p = this._heightFogParams;
+        if (scale === 1 && this._fogPreExposure === 1) {
+            return p;
+        }
+        const p1 = p.parameter1;
+        const p4 = p.parameter4;
+        return {
+            ...p,
+            parameter1: new Vector4(p1.x * scale, p1.y * scale, p1.z * scale, p1.w),
+            parameter4: new Vector4(p4.x * scale, p4.y * scale, p4.z * scale, p4.w),
+            preExposure: this._fogPreExposure
+        };
+    }
     /** @internal */ renderFog(camera) {
         const device = getDevice();
         const currentFramebuffer = device.getFramebuffer();
@@ -679,14 +779,14 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         const savedRenderStates = device.getRenderStates();
         this._prepareSkyBox(device);
         this.renderUberFog(camera, depthBuffer);
-        /*
-    if (this._skyType === 'scatter') {
-      this.renderAtmosphericFog(ctx, depthBuffer);
-    }
-    */ /*
-    if (this._fogType === 'height_fog') {
-      this.renderHeightFog(ctx, depthBuffer);
-    }
+        /*
+    if (this._skyType === 'scatter') {
+      this.renderAtmosphericFog(ctx, depthBuffer);
+    }
+    */ /*
+    if (this._fogType === 'height_fog') {
+      this.renderHeightFog(ctx, depthBuffer);
+    }
     */ device.setRenderStates(savedRenderStates);
         if (fogFramebuffer) {
             device.popDeviceStates();
@@ -726,7 +826,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         const framebuffer = this._beginSingleColorPass(true);
         try {
-            this._renderSky(skyCamera, true);
+            this._renderSky(skyCamera, true, true, this._getSkyScreenLuminanceScale(ctx));
         } finally{
             this._endSingleColorPass(framebuffer);
         }
@@ -774,23 +874,67 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             });
         }
     }
-    /** @internal */ _renderSky(camera, depthTest) {
+    /** @internal */ _renderSky(camera, depthTest, includeSunDisk, luminanceScale = 1) {
         const device = getDevice();
         const savedRenderStates = device.getRenderStates();
         this._prepareSkyBox(device);
         if (this._skyType === 'scatter') {
-            this._drawScattering(camera, depthTest);
+            // The atmosphere LUTs already hold physical luminance, so only the caller's exposure applies.
+            this._drawScattering(camera, depthTest, includeSunDisk, luminanceScale);
         } else if (this._skyType === 'skybox' && this.skyboxTexture) {
-            this._drawSkybox(camera, depthTest);
+            this._drawSkybox(camera, depthTest, luminanceScale);
         } else {
-            this._drawSkyColor(camera, depthTest);
+            this._drawSkyColor(camera, depthTest, luminanceScale);
         }
         device.setRenderStates(savedRenderStates);
     }
-    /** @internal */ _drawSkyColor(camera, depthTest) {
+    /**
+   * @internal
+   *
+   * Converts a value stored at {@link PHYSICAL_BAKE_EXPOSURE} into the live pre-exposed space.
+   *
+   * @remarks
+   * Everything derived from the cached sky bake (the IBL, the distant-light LUT, the visible baked
+   * skybox) is stored at the fixed reference exposure. Multiplying by this ratio yields the same
+   * result as if the live camera exposure had been baked in, without invalidating the cache when
+   * the camera stops down. Returns 1 in legacy.
+   */ static getBakeToPreExposedScale(ctx) {
+        return ctx.scene.lightingMode === 'physical' ? ShaderHelper.getPreExposure(ctx) / SkyRenderer.PHYSICAL_BAKE_EXPOSURE : 1;
+    }
+    /**
+   * @internal
+   *
+   * Scale that normalizes a sky into the IBL bake's storage space.
+   *
+   * @remarks
+   * An authored 0..1 `skybox` / `image` is treated as an emitter of `EnvLightWrapper.intensity` lux.
+   * The scattering atmosphere needs no lift: its LUTs already carry photometric sun illuminance.
+   *
+   * Both are then scaled to {@link PHYSICAL_BAKE_EXPOSURE}. The bake is cached and only invalidated
+   * by sun changes, so it must be exposure-independent; storing it at raw photometric magnitude
+   * would overflow the environment cubemap's float range (see {@link PHYSICAL_BAKE_EXPOSURE}).
+   *
+   * Returns 1 in legacy so its bake stays byte-identical.
+   */ _getSkyBakeLuminanceScale(ctx) {
+        if (ctx.scene.lightingMode !== 'physical') {
+            return 1;
+        }
+        // scatter already includes the bake exposure via renderAtmosphereLUTs().
+        return this._skyType === 'scatter' ? 1 : ctx.scene.env.light.intensity * SkyRenderer.PHYSICAL_BAKE_EXPOSURE;
+    }
+    /**
+   * @internal
+   *
+   * On-screen sky scale: the bake-time normalization converted from the stored reference exposure
+   * to the live one, so the visible sky lands in the same pre-exposed space as every lit surface.
+   */ _getSkyScreenLuminanceScale(ctx) {
+        return this._getSkyBakeLuminanceScale(ctx) * SkyRenderer.getBakeToPreExposedScale(ctx);
+    }
+    /** @internal */ _drawSkyColor(camera, depthTest, luminanceScale) {
         const device = getDevice();
         const bindgroup = this._bindgroupSky.image.get();
         bindgroup.setValue('color', this._skyColor);
+        bindgroup.setValue('luminanceScale', luminanceScale);
         bindgroup.setTexture('texture', this._skyImage.get() ?? SkyRenderer._defaultSkyImage.get(), fetchSampler('clamp_linear_nomip'));
         bindgroup.setValue('flip', device.getFramebuffer() && device.type === 'webgpu' ? -1 : 1);
         bindgroup.setValue('srgbOut', device.getFramebuffer() ? 0 : 1);
@@ -798,10 +942,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         device.setBindGroup(0, bindgroup);
         drawFullscreenQuad(depthTest ? SkyRenderer._renderStatesSky : SkyRenderer._renderStatesSkyNoDepthTest);
     }
-    /** @internal */ _drawSkybox(camera, depthTest) {
+    /** @internal */ _drawSkybox(camera, depthTest, luminanceScale) {
         const device = getDevice();
         const bindgroup = this._bindgroupSky.skybox.get();
         bindgroup.setTexture('skyCubeMap', this.skyboxTexture, fetchSampler('clamp_linear_nomip'));
+        bindgroup.setValue('luminanceScale', luminanceScale);
         bindgroup.setValue('flip', device.getFramebuffer() && device.type === 'webgpu' ? new Vector4(1, -1, 1, 1) : new Vector4(1, 1, 1, 1));
         bindgroup.setValue('viewProjMatrix', camera.viewProjectionMatrix);
         bindgroup.setValue('worldMatrix', this._skyWorldMatrix);
@@ -877,7 +1022,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return new Vector3(Math.exp(-sum.x), Math.exp(-sum.y), Math.exp(-sum.z));
     }
-    /** @internal */ _drawScattering(camera, depthTest) {
+    /** @internal */ _drawScattering(camera, depthTest, includeSunDisk, luminanceScale) {
         const device = getDevice();
         const tLut = getTransmittanceLut();
         const skyLut = getSkyViewLut();
@@ -890,6 +1035,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         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('luminanceScale', luminanceScale);
         bindgroup.setTexture('tLut', tLut, fetchSampler('clamp_linear_nomip'));
         bindgroup.setTexture('skyLut', skyLut, fetchSampler('clamp_linear_nomip'));
         bindgroup.setValue('cloudy', this._cloudy);
@@ -930,9 +1077,14 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 fragment (pb) {
                     this.$outputs.color = pb.vec4();
                     this.skybox = pb.texCube().uniform(0);
+                    this.physical = pb.int().uniform(0);
                     pb.main(function() {
                         this.$l.sunColor = pb.vec4();
-                        this.$l.skyColor = pb.textureSampleLevel(this.skybox, this.$inputs.vector, 0).rgb;
+                        // Height-fog in-scattering is lit by the sky hemisphere. The old full-sphere average
+                        // is retained verbatim in legacy mode; in physical mode, mirror lower samples into the
+                        // upper hemisphere so a dark ground/lower sky cannot turn the horizon into a black band.
+                        this.$l.sampleDirection = this.$choice(pb.notEqual(this.physical, 0), pb.vec3(this.$inputs.vector.x, pb.abs(this.$inputs.vector.y), this.$inputs.vector.z), this.$inputs.vector);
+                        this.$l.skyColor = pb.textureSampleLevel(this.skybox, this.sampleDirection, 0).rgb;
                         this.$outputs.color = pb.vec4(pb.mul(this.skyColor, 1 / 64), 1);
                     });
                 }
@@ -962,7 +1114,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                     this.$outputs.uv = pb.vec2();
                     this.flip = pb.int().uniform(0);
                     pb.main(function() {
-                        this.$builtins.position = pb.vec4(this.$inputs.pos, 1, 1);
+                        this.$builtins.position = pb.vec4(this.$inputs.pos, DEPTH_FARTHEST, 1);
                         this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos.xy, 0.5), pb.vec2(0.5));
                         if (device.type !== 'webgpu') {
                             this.$builtins.position.y = pb.neg(this.$builtins.position.y);
@@ -974,9 +1126,12 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                     this.color = pb.vec4().uniform(0);
                     this.texture = pb.tex2D().uniform(0);
                     this.srgbOut = pb.int().uniform(0);
+                    this.luminanceScale = pb.float().uniform(0);
                     pb.main(function() {
                         this.$l.sampleColor = pb.textureSampleLevel(this.texture, this.$inputs.uv, 0);
-                        this.$l.outColor = pb.mul(this.sampleColor, this.color);
+                        // luminanceScale is 1 in legacy and for the IBL bake; on screen in physical mode it
+                        // carries the environment intensity (lux) pre-multiplied by the camera exposure.
+                        this.$l.outColor = pb.mul(this.sampleColor, this.color, this.luminanceScale);
                         this.$if(pb.equal(this.srgbOut, 0), function() {
                             this.$outputs.outColor = pb.vec4(this.outColor.rgb, 1);
                         }).$else(function() {
@@ -1010,16 +1165,19 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                         this.$outputs.texCoord = this.$inputs.pos;
                         this.$l.worldPos = pb.add(this.cameraPos, pb.mul(this.worldMatrix, pb.vec4(this.$inputs.pos, 0)).xyz);
                         this.$builtins.position = pb.mul(this.viewProjMatrix, pb.vec4(this.worldPos, 1), this.flip);
-                        this.$builtins.position.z = this.$builtins.position.w;
+                        this.$builtins.position.z = ShaderHelper.farthestClipZ(this, this.$builtins.position.w);
                     });
                 },
                 fragment (pb) {
                     this.$outputs.outColor = pb.vec4();
                     this.skyCubeMap = pb.texCube().uniform(0);
                     this.srgbOut = pb.int().uniform(0);
+                    this.luminanceScale = pb.float().uniform(0);
                     pb.main(function() {
                         this.$l.texCoord = pb.normalize(this.$inputs.texCoord);
-                        this.$l.color = pb.textureSampleLevel(this.skyCubeMap, this.texCoord, 0).rgb;
+                        // luminanceScale is 1 in legacy and for the IBL bake; on screen in physical mode it
+                        // carries the environment intensity (lux) pre-multiplied by the camera exposure.
+                        this.$l.color = pb.mul(pb.textureSampleLevel(this.skyCubeMap, this.texCoord, 0).rgb, this.luminanceScale);
                         this.$if(pb.equal(this.srgbOut, 0), function() {
                             this.$outputs.outColor = pb.vec4(this.color, 1);
                         }).$else(function() {
@@ -1035,7 +1193,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         if (!SkyRenderer._renderStatesSky) {
             SkyRenderer._renderStatesSky = device.createRenderStateSet();
-            SkyRenderer._renderStatesSky.useDepthState().enableTest(true).enableWrite(false).setCompareFunc('le');
+            SkyRenderer._renderStatesSky.useDepthState().enableTest(true).enableWrite(false).setCompareFunc(DEPTH_COMPARE_DEFAULT);
             SkyRenderer._renderStatesSky.useRasterizerState().setCullMode('none');
         }
         if (!SkyRenderer._renderStatesSkyNoDepthTest) {
@@ -1053,7 +1211,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             SkyRenderer._renderStatesFogScatter = device.createRenderStateSet();
             SkyRenderer._renderStatesFogScatter.useRasterizerState().setCullMode('none');
             SkyRenderer._renderStatesFogScatter.useBlendingState().enable(true).setBlendFunc('one', 'src-alpha');
-            SkyRenderer._renderStatesFogScatter.useDepthState().enableTest(true).enableWrite(false).setCompareFunc('gt');
+            SkyRenderer._renderStatesFogScatter.useDepthState().enableTest(true).enableWrite(false).setCompareFunc(DEPTH_COMPARE_FARTHER);
         }
         if (!SkyRenderer._renderStatesDistantLight) {
             SkyRenderer._renderStatesDistantLight = device.createRenderStateSet();
@@ -1107,7 +1265,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 this.$inputs.pos = pb.vec2().attrib('position');
                 this.$outputs.uv = pb.vec2();
                 pb.main(function() {
-                    this.$builtins.position = pb.vec4(this.$inputs.pos, 1, 1);
+                    this.$builtins.position = pb.vec4(this.$inputs.pos, DEPTH_FARTHEST, 1);
                     this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos.xy, 0.5), pb.vec2(0.5));
                     if (device.type === 'webgpu') {
                         this.$if(pb.notEqual(this.rt, 0), function() {
@@ -1134,11 +1292,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 this.srgbOut = pb.int().uniform(0);
                 this.$outputs.outColor = pb.vec4();
                 pb.main(function() {
-                    this.$l.depthValue = noDepth ? pb.float(1) : pb.textureSample(this.depthTex, this.$inputs.uv).r;
-                    this.$l.clipSpacePos = pb.vec4(pb.sub(pb.mul(this.$inputs.uv, 2), pb.vec2(1)), pb.sub(pb.mul(this.depthValue, 2), 1), 1);
+                    this.$l.depthValue = noDepth ? pb.float(DEPTH_FARTHEST) : pb.textureSample(this.depthTex, this.$inputs.uv).r;
+                    this.$l.clipSpacePos = pb.vec4(pb.sub(pb.mul(this.$inputs.uv, 2), pb.vec2(1)), ShaderHelper.deviceDepthToClipZ(this, this.depthValue), 1);
                     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 = pb.equal(this.$l.depthValue, 1);
+                    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.$if(pb.equal(this.srgbOut, 0), function() {
                         this.$outputs.outColor = this.color;
@@ -1184,7 +1342,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 pb.main(function() {
                     this.$outputs.worldDirection = pb.mul(this.worldMatrix, pb.vec4(this.$inputs.pos, 0)).xyz;
                     this.$builtins.position = pb.mul(this.viewProjMatrix, pb.vec4(pb.add(this.$outputs.worldDirection, this.cameraPos), 1), this.flip);
-                    this.$builtins.position.z = this.$builtins.position.w;
+                    this.$builtins.position.z = ShaderHelper.farthestClipZ(this, this.$builtins.position.w);
                 });
             },
             fragment (pb) {
@@ -1192,6 +1350,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 this.tLut = pb.tex2D().uniform(0);
                 this.skyLut = pb.tex2D().uniform(0);
                 this.params = getAtmosphereParamsStruct(pb)().uniform(0);
+                this.includeSunDisk = pb.int().uniform(0);
                 if (cloud) {
                     this.cloudy = pb.float().uniform(0);
                     this.cloudIntensity = pb.float().uniform(0);
@@ -1199,6 +1358,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                     this.velocity = pb.vec2().uniform(0);
                 }
                 this.srgbOut = pb.int().uniform(0);
+                this.luminanceScale = pb.float().uniform(0);
                 pb.func('noise', [
                     pb.vec3('p'),
                     pb.float('t')
@@ -1222,7 +1382,7 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                 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.tLut, this.skyLut).rgb;
+                    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);
                     this.$l.sunDir = this.params.lightDir;
                     // ad-hoc
@@ -1242,11 +1402,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                             this.noiseValue = pb.smoothStep(1, pb.add(1, this.cloudy), this.noiseValue);
                         });
                         // use sun color as cloud color
-                        /*
-            this.$l.sunColor = pb.mul(
-              pb.textureSampleLevel(this.skyLut, viewDirToUV(this, this.sunDir), 0),
-              this.sunIntensity
-            );
+                        /*
+            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
@@ -1258,6 +1418,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
                     } 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.equal(this.srgbOut, 0), function() {
                         this.$outputs.outColor = pb.vec4(this.color, 1);
                     }).$else(function() {