@zephyr3d/scene 0.9.25 → 0.9.27

package/dist/render/sky.js

@@ -28,30 +28,37 @@ 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).
+    /**
+   * @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}.
+    /**
+   * @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).
+    /**
+   * @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;
+    /**
+   * @internal
+   *
+   * Direct-sun transmittance floor under full cloud cover. Heavy overcast leaves only a few
+   * percent of direct sunlight; keeping a small non-zero floor lets shadows fade out smoothly
+   * instead of snapping off.
+   */ static CLOUD_SUN_MIN_TRANSMITTANCE = 0.05;
     static _skyCamera = (()=>{
         return new PerspectiveCamera(null, Math.PI * 0.5, 1, 20, 1);
     })();
@@ -110,16 +117,16 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
     _bindgroupFog = null;
     _bindgroupFogNoDepth = null;
     _format;
-    /**
-   * @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).
+    /**
+   * @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).
+    /**
+   * @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
+    /**
+   * Creates an instance of SkyRenderer
    */ constructor(){
         super();
         this._skyType = 'scatter';
@@ -166,8 +173,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
     /** @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;
@@ -212,8 +219,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;
     }
@@ -223,8 +230,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();
     }
@@ -234,8 +241,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Window weights for SH projection
+    /**
+   * Window weights for SH projection
    */ get shWindowWeights() {
         return this._shWindowWeights;
     }
@@ -243,8 +250,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;
     }
@@ -254,8 +261,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Sample count for irradiance convolution
+    /**
+   * Sample count for irradiance convolution
    */ get irradianceConvSamples() {
         return this._irradianceConvSamples;
     }
@@ -382,12 +389,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;
     }
@@ -397,8 +404,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.invalidate();
         }
     }
-    /**
-   * Intensity of the sky color
+    /**
+   * Intensity of the sky color
    */ get cloudIntensity() {
         return this._cloudIntensity;
     }
@@ -408,19 +415,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));
@@ -428,11 +435,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;
     }
@@ -450,8 +457,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, {
@@ -461,8 +468,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();
@@ -477,8 +484,8 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         return this._irradianceSHFB.get();
     }
-    /**
-   * Cube texture for skybox.
+    /**
+   * Cube texture for skybox.
    */ get skyboxTexture() {
         return this._skyboxTexture.get();
     }
@@ -490,8 +497,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;
     }
@@ -534,8 +541,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;
     }
@@ -594,7 +601,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
             this.updateBakedSkyMap(ctx);
             this.renderSkyDistantLut(ctx, this._bakedSkyboxTexture.get());
         }
-        const newSunLight = oldSunLight ? Vector3.mul(ctx.sunLight.color.xyz(), this.sunTransmittance(ctx.sunLight)) : Vector3.zero();
+        // 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
+        // the unoccluded sun above the layer, and the bake is where their scattered share of the
+        // energy re-enters as ambient.
+        const newSunLight = oldSunLight ? Vector3.mul(Vector3.mul(ctx.sunLight.color.xyz(), this.sunTransmittance(ctx.sunLight)), this.cloudSunTransmittance(sunDir)) : Vector3.zero();
         if (oldSunLight) {
             ctx.sunLight.setColor(newSunLight);
         }
@@ -701,11 +712,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         device.popDeviceStates();
         device.setRenderStates(saveRenderStates);
     }
-    /**
-   * @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.
+    /**
+   * @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);
@@ -741,12 +752,12 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         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.
+    /**
+   * @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;
@@ -779,14 +790,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();
@@ -888,33 +899,33 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         }
         device.setRenderStates(savedRenderStates);
     }
-    /**
-   * @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.
+    /**
+   * @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.
+    /**
+   * @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;
@@ -922,11 +933,11 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         // 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.
+    /**
+   * @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);
     }
@@ -969,6 +980,31 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         const t2 = SH + PH;
         return t1 < 0 ? t2 : t1;
     }
+    /**
+   * Transmittance of the cloud layer along the sun direction.
+   *
+   * @remarks
+   * Energy-conservation counterpart of the clouds baked into the environment map: the light the
+   * cloud layer scatters into the sky dome has to be removed from the direct sun, otherwise
+   * raising cloud density only ever adds energy. This method is the seam where a future cloud
+   * renderer plugs in; a volumetric implementation should replace it with the transmittance
+   * ray-marched toward the sun (spectral, hence a Vector3).
+   *
+   * The procedural 2D cloud has no real optical depth, so the sun direction is unused and the
+   * result is a gray-scale estimate from coverage alone. In the scatter shader, cloud opacity is
+   * `smoothStep(1, 1 + cloudy, noise + cloudy)`: by `cloudy = 1` the whole 0..1-ish fbm noise
+   * range falls inside the ramp, i.e. the sky is visually fully covered. `cloudy` (clamped to
+   * 0..1) is therefore used directly as the sky coverage. Squaring it accounts for thin/partial
+   * 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') {
+            return Vector3.one();
+        }
+        const coverage = Math.min(1, Math.max(0, this._cloudy));
+        const t = 1 - coverage * coverage * (1 - SkyRenderer.CLOUD_SUN_MIN_TRANSMITTANCE);
+        return new Vector3(t, t, t);
+    }
     /** @internal */ sunTransmittance(sunLight) {
         const TRANSMITTANCE_SAMPLES = 32;
         const RAYLEIGH_SIGMA = [
@@ -1204,13 +1240,17 @@ const defaultSkyWorldMatrix = Matrix4x4.identity();
         if (!SkyRenderer._renderStatesFog) {
             SkyRenderer._renderStatesFog = device.createRenderStateSet();
             SkyRenderer._renderStatesFog.useRasterizerState().setCullMode('none');
-            SkyRenderer._renderStatesFog.useBlendingState().enable(true).setBlendFunc('one', 'src-alpha');
+            // RGB composites premultiplied inscattering over the scene weighted by transmittance. Alpha is
+            // left untouched: `src-alpha` applied to the alpha channel too would fold transmittance into
+            // the framebuffer coverage (dstA = T + dstA * T), so dense fog drove the backbuffer alpha
+            // toward 0 and the page showed through wherever the canvas alpha is composited.
+            SkyRenderer._renderStatesFog.useBlendingState().enable(true).setBlendFuncRGB('one', 'src-alpha').setBlendFuncAlpha('zero', 'one');
             SkyRenderer._renderStatesFog.useDepthState().enableTest(false).enableWrite(false);
         }
         if (!SkyRenderer._renderStatesFogScatter) {
             SkyRenderer._renderStatesFogScatter = device.createRenderStateSet();
             SkyRenderer._renderStatesFogScatter.useRasterizerState().setCullMode('none');
-            SkyRenderer._renderStatesFogScatter.useBlendingState().enable(true).setBlendFunc('one', 'src-alpha');
+            SkyRenderer._renderStatesFogScatter.useBlendingState().enable(true).setBlendFuncRGB('one', 'src-alpha').setBlendFuncAlpha('zero', 'one');
             SkyRenderer._renderStatesFogScatter.useDepthState().enableTest(true).enableWrite(false).setCompareFunc(DEPTH_COMPARE_FARTHER);
         }
         if (!SkyRenderer._renderStatesDistantLight) {
@@ -1402,11 +1442,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