@zephyr3d/scene 0.9.22 → 0.9.23

package/dist/material/shader/helper.js

@@ -1,8 +1,9 @@
-import { Vector3, Vector4, Vector2 } from '@zephyr3d/base';
+import { Vector3, Vector4, Vector2, REVERSE_Z, DEPTH_FARTHEST, DEPTH_REDUCE_CLOSER, DEPTH_REDUCE_FARTHER } from '@zephyr3d/base';
 import { RENDER_PASS_TYPE_DEPTH, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_LIGHT, MaterialVaryingFlags, MAX_CLUSTERED_LIGHTS, MORPH_WEIGHTS_VECTOR_COUNT, MORPH_TARGET_POSITION, MORPH_TARGET_NORMAL, MORPH_TARGET_TANGENT, MORPH_ATTRIBUTE_VECTOR_COUNT } from '../../values.js';
 import { ProgramBuilder } from '@zephyr3d/device';
 import { decodeNormalizedFloatFromRGBA, linearToGamma } from '../../shaders/misc.js';
 import { getSamplerOptions, fetchSampler } from '../../utility/misc.js';
+import { PHYSICAL_BAKE_EXPOSURE } from '../../utility/physical.js';
 import { getDevice } from '../../app/api.js';
 import { getDefaultAtmosphereParams, getAtmosphereParamsStruct } from '../../shaders/atmosphere.js';
 import { getDefaultHeightFogParams, getHeightFogParamsStruct, calculateFog } from '../../shaders/fog.js';
@@ -173,6 +174,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             pb.float('shadowDebugCascades'),
             pb.float('frameDeltaTime'),
             pb.float('elapsedTime'),
+            pb.float('preExposure'),
             pb.int('framestamp')
         ]);
         if (ctx.renderPass.type === RENDER_PASS_TYPE_SHADOWMAP) {
@@ -271,12 +273,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 scope[UNIFORM_NAME_SHADOW_MAP] = tex.uniform(0);
             }
             if (ctx.drawEnvLight) {
-                ctx.env.light.envLight.initShaderBindings(pb);
+                ctx.env.light.envLight.initShaderBindings(pb, ctx);
             }
             if (ctx.linearDepthTexture) {
                 // Depth values must never be filtered across geometry edges; nearest
                 // matches the default sampler for unfilterable float formats.
-                scope[UNIFORM_NAME_LINEAR_DEPTH_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_nearest_nomip'));
+                scope[UNIFORM_NAME_LINEAR_DEPTH_MAP] = pb.tex2D().sampleType('unfilterable-float').uniform(0).withSampler(getSamplerOptions('clamp_nearest_nomip'));
                 scope[UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.sceneColorTexture) {
@@ -286,7 +288,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             }
             if (ctx.HiZTexture) {
                 // Matches the fetchSampler('clamp_nearest') previously passed at runtime
-                scope[UNIFORM_NAME_HIZ_DEPTH_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_nearest'));
+                scope[UNIFORM_NAME_HIZ_DEPTH_MAP] = pb.tex2D().sampleType('unfilterable-float').uniform(0).withSampler(getSamplerOptions('clamp_nearest'));
                 scope[UNIFORM_NAME_HIZ_DEPTH_MAP_INFO] = pb.vec4().uniform(0);
             }
         }
@@ -703,6 +705,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             shadowDebugCascades: camera.shadowDebugCascades ? 1 : 0,
             frameDeltaTime: ctx.device.frameInfo.elapsedFrame * 0.001,
             elapsedTime: ctx.device.frameInfo.elapsedOverall * 0.001,
+            preExposure: this.getPreExposure(ctx),
             framestamp: ctx.device.frameInfo.frameCounter
         };
         if (ctx.motionVectors && ctx.renderPass.type === RENDER_PASS_TYPE_DEPTH) {
@@ -746,12 +749,72 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         bindGroup.setTexture(UNIFORM_NAME_AERIALPERSPECTIVE_LUT, aerialPerspectiveLUT);
         bindGroup.setTexture(UNIFORM_NAME_SKYDISTANTLIGHT_LUT, skyDistantLightLUT);
     }
+    /**
+   * @internal
+   *
+   * Camera pre-exposure factor for scene-linear lighting quantities.
+   *
+   * @remarks
+   * Physical lighting authors light intensities in photometric units (lux, candela, cd/m²), whose
+   * magnitudes (~1e5 for daylight) neither fit an rgba16f render target nor leave usable headroom
+   * for specular highlights. Following Filament, the camera exposure is folded into every light
+   * quantity on the CPU so the HDR target stays near 1.0 and downstream passes need no unit
+   * awareness. Legacy returns 1 so its uploads stay byte-identical.
+   */ static getPreExposure(ctx) {
+        return ctx.scene.lightingMode === 'physical' ? ctx.camera.exposure : 1;
+    }
+    /**
+   * @internal
+   *
+   * Light color/intensity vector with the camera pre-exposure folded into the intensity component.
+   *
+   * @remarks
+   * Only the intensity (`w`) is scaled; the color stays untouched, matching Filament's
+   * `FScene::prepareDynamicLights`. The light's own cached vector is never mutated because it is
+   * shared across every camera rendering the scene.
+   */ static getPreExposedColorIntensity(light, ctx, out) {
+        const src = light.diffuseAndIntensity;
+        const result = out ?? new Vector4();
+        result.setXYZW(src.x, src.y, src.z, src.w * this.getPreExposure(ctx));
+        return result;
+    }
+    /**
+   * @internal
+   *
+   * Environment lighting scale uploaded as `light.envLightStrength`.
+   *
+   * @remarks
+   * Legacy uses the unitless {@link EnvLightWrapper.strength}.
+   *
+   * Physical returns the ratio that converts the cached sky bake from its fixed storage exposure
+   * (`SkyRenderer.PHYSICAL_BAKE_EXPOSURE`) to the live camera exposure. Every environment source is
+   * normalized into that one space before it reaches the IBL -- the scattering atmosphere emits
+   * photometric luminance, authored 0..1 skyboxes/panoramas are lifted by
+   * {@link EnvLightWrapper.intensity} -- so no pass consuming `envLightStrength` has to know the
+   * sky type.
+   *
+   * The bake cannot simply hold raw cd/m²: the environment cubemap is `rg11b10uf`/`rgba16f` and a
+   * daylight sun overflows it to Inf, which `prefilterCubemap` then spreads across the whole IBL.
+   *
+   * {@link EnvLightWrapper.strength} multiplies the result in both modes. It is the only per-frame
+   * dimmer for environment lighting: the photometric `intensity` reaches the image solely through
+   * the cached bake, and a `scatter` sky does not even consult it (its brightness comes from the
+   * sun), so without this factor there would be no way to turn the IBL down without re-baking.
+   */ static getEnvLightLuminance(ctx) {
+        const env = ctx.env;
+        if (!env) {
+            return 0;
+        }
+        const strength = env.light.strength ?? 0;
+        return ctx.scene.lightingMode === 'physical' ? this.getPreExposure(ctx) / PHYSICAL_BAKE_EXPOSURE * strength : strength;
+    }
     /** @internal */ static setLightUniforms(bindGroup, ctx, clusterParams, countParams, lightBuffer, lightIndexTexture) {
+        const envLightStrength = this.getEnvLightLuminance(ctx);
         bindGroup.setValue('light', {
             sunDir: ctx.sunLight ? ctx.sunLight.directionAndCutoff.xyz().scaleBy(-1) : this.defaultSunDir,
             clusterParams: clusterParams,
             countParams: countParams,
-            envLightStrength: ctx.env.light.strength ?? 0,
+            envLightStrength,
             envLightSpecularStrength: ctx.env.light.specularStrength ?? 1,
             lightIndexTexSize: new Int32Array([
                 lightIndexTexture.width,
@@ -772,7 +835,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
         if (ctx.drawEnvLight) {
-            ctx.env.light.envLight.updateBindGroup(bindGroup);
+            ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
         }
     }
     /** @internal */ static setLightUniformsShadow(bindGroup, ctx, light) {
@@ -781,7 +844,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         this._lightUniformShadow.shadowCascades = shadowMapParams.numShadowCascades;
         this._lightUniformShadow.positionAndRange.set(light.positionAndRange);
         this._lightUniformShadow.directionAndCutoff.set(light.directionAndCutoff);
-        this._lightUniformShadow.diffuseAndIntensity.set(light.diffuseAndIntensity);
+        this.getPreExposedColorIntensity(light, ctx, this._lightUniformShadow.diffuseAndIntensity);
         this._lightUniformShadow.extraParams.set(light.extraParams);
         this._lightUniformShadow.cascadeDistances.set(shadowMapParams.cascadeDistances);
         this._lightUniformShadow.depthBiasValues.set(shadowMapParams.depthBiasValues[0]);
@@ -790,13 +853,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         shadowMapParams.impl.getParams(this._lightUniformShadow.implParams);
         this._lightUniformShadow.shadowMatrices.set(shadowMapParams.shadowMatrices);
         this._lightUniformShadow.shadowStrength = light.shadow.shadowStrength;
-        this._lightUniformShadow.envLightStrength = ctx.env?.light.strength ?? 0;
+        this._lightUniformShadow.envLightStrength = this.getEnvLightLuminance(ctx);
         this._lightUniformShadow.envLightSpecularStrength = ctx.env?.light.specularStrength ?? 1;
         bindGroup.setValue('light', this._lightUniformShadow);
         bindGroup.setTexture(UNIFORM_NAME_SHADOW_MAP, shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
         if (ctx.drawEnvLight) {
-            ctx.env.light.envLight.updateBindGroup(bindGroup);
+            ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
         }
     }
     /**
@@ -878,6 +941,36 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope[UNIFORM_NAME_BAKED_SKY_MAP];
     }
     /**
+   * Samples the baked sky cubemap in the same pre-exposed space as the scene color buffer.
+   *
+   * @remarks
+   * The bake is cached and therefore exposure-independent, stored at the fixed
+   * `PHYSICAL_BAKE_EXPOSURE`. Anything that blends it against already-pre-exposed lit color (water
+   * reflection, blueprint sky lookups) must first convert it to the live exposure.
+   * `envLightStrength` carries exactly that ratio in physical mode, and the legacy environment
+   * strength (its established meaning) otherwise.
+   *
+   * @param scope - Current shader scope
+   * @param direction - Sampling direction
+   * @returns Pre-exposed sky radiance
+   */ static sampleBakedSkyPreExposed(scope, direction) {
+        const pb = scope.$builder;
+        return pb.mul(pb.textureSampleLevel(this.getBakedSkyTexture(scope), direction, 0).rgb, this.getEnvLightStrength(scope));
+    }
+    /**
+   * Gets the camera pre-exposure factor.
+   *
+   * @remarks
+   * The multiplier every photometric quantity is scaled by before it reaches the HDR target. 1 in
+   * legacy. Use it for material-authored emitters (emissive), which are not covered by the CPU-side
+   * light pre-exposure.
+   *
+   * @param scope - Current shader scope
+   * @returns The pre-exposure factor
+   */ static getPreExposureUniform(scope) {
+        return scope.camera.preExposure;
+    }
+    /**
    * Gets the elapsed time in seconds
    * @param scope - Current shader scope
    * @returns The elapsed time in seconds
@@ -1288,6 +1381,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    */ static linearDepthToNonLinear(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
+        if (REVERSE_Z) {
+            return pb.div(pb.sub(pb.div(pb.mul(nearFar.x, nearFar.y), depth), nearFar.x), pb.sub(nearFar.y, nearFar.x));
+        }
         return pb.div(pb.sub(nearFar.y, pb.div(pb.mul(nearFar.x, nearFar.y), depth)), pb.sub(nearFar.y, nearFar.x));
     }
     /**
@@ -1300,6 +1396,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    */ static nonLinearDepthToLinear(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
+        if (REVERSE_Z) {
+            return pb.div(pb.mul(nearFar.x, nearFar.y), pb.mix(nearFar.x, nearFar.y, depth));
+        }
         return pb.div(pb.mul(nearFar.x, nearFar.y), pb.mix(nearFar.y, nearFar.x, depth));
     }
     /**
@@ -1312,9 +1411,85 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    */ static nonLinearDepthToLinearNormalized(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
+        if (REVERSE_Z) {
+            return pb.div(nearFar.x, pb.mix(nearFar.x, nearFar.y, depth));
+        }
         return pb.div(nearFar.x, pb.mix(nearFar.y, nearFar.x, depth));
     }
     /**
+   * Converts normalized linear depth back to device non-linear depth.
+   *
+   * @remarks
+   * The normalized linear depth convention (range [near/far, 1] with 1 at
+   * the far plane, as produced by {@link ShaderHelper.nonLinearDepthToLinearNormalized})
+   * is independent of the engine depth convention; only the mapping to
+   * device depth flips under reverse-Z.
+   *
+   * @param scope - Current shader scope
+   * @param depth - The normalized linear depth
+   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
+   * @returns The device non-linear depth
+   */ static linearNormalizedToNonLinearDepth(scope, depth, nearFar) {
+        const pb = scope.$builder;
+        nearFar = nearFar ?? this.getCameraParams(scope);
+        if (REVERSE_Z) {
+            return pb.div(pb.sub(pb.div(nearFar.x, depth), nearFar.x), pb.sub(nearFar.y, nearFar.x));
+        }
+        return pb.div(pb.sub(pb.div(nearFar.x, depth), nearFar.y), pb.sub(nearFar.x, nearFar.y));
+    }
+    /**
+   * Maps a device depth value to the canonical clip-space z coordinate
+   * (GL [-1,1] under standard-Z, zero-to-one under reverse-Z), suitable for
+   * unprojection with the engine's inverse projection matrices.
+   *
+   * @param scope - Current shader scope
+   * @param depth - The device depth value
+   * @returns The canonical clip-space z
+   */ static deviceDepthToClipZ(scope, depth) {
+        const pb = scope.$builder;
+        return REVERSE_Z ? depth : pb.sub(pb.mul(depth, 2), 1);
+    }
+    /**
+   * Clip-space z that places a vertex exactly on the far plane (sky domes,
+   * background geometry).
+   *
+   * @param scope - Current shader scope
+   * @param w - The clip-space w coordinate of the vertex
+   * @returns The clip-space z value for the far plane
+   */ static farthestClipZ(scope, w) {
+        return REVERSE_Z ? 0 : w;
+    }
+    /**
+   * Tests whether a device depth value equals the cleared (farthest) depth,
+   * i.e. no geometry was rendered at this position.
+   *
+   * @param scope - Current shader scope
+   * @param depth - The device depth value
+   * @returns Boolean expression, true for background pixels
+   */ static isFarthestDepth(scope, depth) {
+        return scope.$builder.equal(depth, DEPTH_FARTHEST);
+    }
+    /**
+   * Selects the closer of two device depth values.
+   *
+   * @param scope - Current shader scope
+   * @param a - First device depth value
+   * @param b - Second device depth value
+   * @returns The value closer to the camera
+   */ static closerDepth(scope, a, b) {
+        return scope.$builder[DEPTH_REDUCE_CLOSER](a, b);
+    }
+    /**
+   * Selects the farther of two device depth values.
+   *
+   * @param scope - Current shader scope
+   * @param a - First device depth value
+   * @param b - Second device depth value
+   * @returns The value farther from the camera
+   */ static fartherDepth(scope, a, b) {
+        return scope.$builder[DEPTH_REDUCE_FARTHER](a, b);
+    }
+    /**
    * Sample linear depth from linear depth texture
    * @param scope - Current shader scope
    * @param tex - The linear depth texture
@@ -1335,8 +1510,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             pb.mat4('mat')
         ], function() {
             this.$l.linearDepth = that.sampleLinearDepth(this, depthTex, this.uv, 0);
-            this.$l.nonLinearDepth = pb.div(pb.sub(pb.div(this.cameraNearFar.x, this.linearDepth), this.cameraNearFar.y), pb.sub(this.cameraNearFar.x, this.cameraNearFar.y));
-            this.$l.clipSpacePos = pb.vec4(pb.sub(pb.mul(this.uv, 2), pb.vec2(1)), pb.sub(pb.mul(pb.clamp(this.nonLinearDepth, 0, 1), 2), 1), 1);
+            this.$l.nonLinearDepth = that.linearNormalizedToNonLinearDepth(this, this.linearDepth, this.cameraNearFar);
+            this.$l.clipSpacePos = pb.vec4(pb.sub(pb.mul(this.uv, 2), pb.vec2(1)), that.deviceDepthToClipZ(this, pb.clamp(this.nonLinearDepth, 0, 1)), 1);
             this.$l.wPos = pb.mul(this.mat, this.clipSpacePos);
             this.$return(pb.vec4(pb.div(this.wPos.xyz, this.wPos.w), this.linearDepth));
         });