@zephyr3d/scene 0.9.22 → 0.9.24

package/dist/material/shader/helper.js

@@ -1,8 +1,9 @@
-import { Vector3, Vector4, Vector2 } 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 { 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, 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';
@@ -33,9 +34,9 @@ const UNIFORM_NAME_BONE_TEXTURE_SIZE = 'Z_UniformBoneTexSize';
 const UNIFORM_NAME_BONE_INV_BIND_MATRIX = 'Z_UniformBoneInvBindMatrix';
 const UNIFORM_NAME_MORPH_DATA = 'Z_UniformMorphData';
 const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
-/**
- * Helper shader functions for the builtin material system
- * @public
+/**
+ * Helper shader functions for the builtin material system
+ * @public
  */ class ShaderHelper {
     static BILLBOARD_SPHERICAL = 1;
     static BILLBOARD_SYLINDRAL = 2;
@@ -128,25 +129,25 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return bindGroupLayout;
     }
-    /**
-   * Prepares the fragment shader which is going to be used in our material system
-   *
-   * @remarks
-   * This function will setup all nessesary uniforms acoording to the drawing context
-   *
-   * @param pb - The program builder
-   * @param ctx - The drawing context
+    /**
+   * Prepares the fragment shader which is going to be used in our material system
+   *
+   * @remarks
+   * This function will setup all nessesary uniforms acoording to the drawing context
+   *
+   * @param pb - The program builder
+   * @param ctx - The drawing context
    */ static prepareFragmentShader(pb, ctx) {
         this.setupGlobalUniforms(pb, ctx);
     }
-    /**
-   * Prepares the vertex shader which is going to be used in our material system
-   *
-   * @remarks
-   * This function will setup all nessesary uniforms according to the drawing context
-   *
-   * @param pb - The program builder
-   * @param ctx - The drawing context
+    /**
+   * Prepares the vertex shader which is going to be used in our material system
+   *
+   * @remarks
+   * This function will setup all nessesary uniforms according to the drawing context
+   *
+   * @param pb - The program builder
+   * @param ctx - The drawing context
    */ static prepareVertexShader(pb, ctx) {
         this.setupGlobalUniforms(pb, ctx);
         this.prepareVertexShaderCommon(pb, ctx);
@@ -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) {
@@ -237,7 +239,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.camera = cameraStruct().uniform(0);
             scope.light = lightStruct().uniform(0);
             if (useClusteredLighting) {
-                scope[UNIFORM_NAME_LIGHT_BUFFER] = pb.vec4[(MAX_CLUSTERED_LIGHTS + 1) * 4]().uniformBuffer(0);
+                scope[UNIFORM_NAME_LIGHT_BUFFER] = pb.vec4[(this.getMaxClusterLights() + 1) * 4]().uniformBuffer(0);
                 // Non-WebGL1 devices fetch the light index texture with textureLoad
                 scope[UNIFORM_NAME_LIGHT_INDEX_TEXTURE] = (pb.getDevice().type === 'webgl' ? pb.tex2D() : pb.utex2D().noSampler()).uniform(0);
                 // Screen-space shadow mask array (rgba8unorm, 4 shadow lights per layer).
@@ -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,35 +288,35 @@ 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);
             }
         }
     }
-    /**
-   * This function checks if the shader needs to process skeletal animation.
-   *
-   * @param scope - Current shader scope
-   *
-   * @returns true if the shader needs to process skeletal animation, otherwise false.
+    /**
+   * This function checks if the shader needs to process skeletal animation.
+   *
+   * @param scope - Current shader scope
+   *
+   * @returns true if the shader needs to process skeletal animation, otherwise false.
    */ static hasSkinning(scope) {
         return !!scope[UNIFORM_NAME_BONE_MATRICES];
     }
-    /**
-   * This function checks if the shader needs to process morph target animation.
-   *
-   * @param scope - Current shader scope
-   *
-   * @returns true if the shader needs to process morph target animation, otherwise false.
+    /**
+   * This function checks if the shader needs to process morph target animation.
+   *
+   * @param scope - Current shader scope
+   *
+   * @returns true if the shader needs to process morph target animation, otherwise false.
    */ static hasMorphing(scope) {
         return !!scope[UNIFORM_NAME_MORPH_DATA];
     }
-    /**
-   * Calculate skinning matrix for current vertex
-   *
-   * @param scope - Current shader scope
-   *
-   * @returns Skinning matrix for current vertex, or null if there is not skeletal animation
+    /**
+   * Calculate skinning matrix for current vertex
+   *
+   * @param scope - Current shader scope
+   *
+   * @returns Skinning matrix for current vertex, or null if there is not skeletal animation
    */ static calculateSkinMatrix(scope) {
         if (!this.hasSkinning(scope)) {
             return null;
@@ -469,12 +471,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.$l[that.SKIN_PREV_MATRIX_NAME] = scope[funcNameGetSkinningMatrix](scope[that.SKIN_BONE_OFFSET].y);
         }
     }
-    /**
-   * Calculates the vertex position of type vec3 in object space
-   *
-   * @param scope - Current shader scope
-   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
-   * @returns The calculated vertex position in object space, or null if pos is null
+    /**
+   * Calculates the vertex position of type vec3 in object space
+   *
+   * @param scope - Current shader scope
+   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
+   * @returns The calculated vertex position in object space, or null if pos is null
    */ static resolveVertexPosition(scope) {
         const pb = scope.$builder;
         if (pb.shaderKind !== 'vertex') {
@@ -516,12 +518,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return scope[that.SKIN_MATRIX_NAME] && scope[that.SKIN_PREV_MATRIX_NAME] ? scope.Z_resolveVertexPosition(scope[that.SKIN_MATRIX_NAME], scope[that.SKIN_PREV_MATRIX_NAME]) : scope[that.SKIN_MATRIX_NAME] ? scope.Z_resolveVertexPosition(scope[that.SKIN_MATRIX_NAME]) : scope.Z_resolveVertexPosition();
     }
-    /**
-   * Resolve motion vector
-   *
-   * @param scope - Current shader scope
-   * @param worldPos - Current object position in world space
-   * @param prevWorldPos - Previous object position in world space
+    /**
+   * Resolve motion vector
+   *
+   * @param scope - Current shader scope
+   * @param worldPos - Current object position in world space
+   * @param prevWorldPos - Previous object position in world space
    */ static resolveMotionVector(scope, worldPos, prevWorldPos) {
         const that = this;
         const pb = scope.$builder;
@@ -532,13 +534,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.$outputs.zMotionVectorPosPrev = pb.mul(prevUnjitteredVPMatrix, pb.vec4(prevWorldPos.xyz, 1));
         }
     }
-    /**
-   * Calculates the normal vector of type vec3 in object space
-   *
-   * @param scope - Current shader scope
-   * @param normal - Vertex normal input, must be type of vec3, null if no vertex normal input
-   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
-   * @returns The calculated normal vector in object space, or null if normal is null
+    /**
+   * Calculates the normal vector of type vec3 in object space
+   *
+   * @param scope - Current shader scope
+   * @param normal - Vertex normal input, must be type of vec3, null if no vertex normal input
+   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
+   * @returns The calculated normal vector in object space, or null if normal is null
    */ static resolveVertexNormal(scope, normal) {
         const pb = scope.$builder;
         if (pb.shaderKind !== 'vertex') {
@@ -563,13 +565,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             return normal;
         }
     }
-    /**
-   * Calculates the tangent vector of type vec3 in object space
-   *
-   * @param scope - Current shader scope
-   * @param tangent - Vertex tangent input, must be type of vec4, null if no vertex tangent input
-   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
-   * @returns The calculated tangent vector of type vec4 in object space, or null if tangent is null
+    /**
+   * Calculates the tangent vector of type vec3 in object space
+   *
+   * @param scope - Current shader scope
+   * @param tangent - Vertex tangent input, must be type of vec4, null if no vertex tangent input
+   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
+   * @returns The calculated tangent vector of type vec4 in object space, or null if tangent is null
    */ static resolveVertexTangent(scope, tangent) {
         const pb = scope.$builder;
         if (pb.shaderKind !== 'vertex') {
@@ -594,18 +596,18 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             return tangent;
         }
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the world matrix of current object to be drawn
-   * @param scope - Current shader scope
-   * @returns The world matrix of current object to be drawn
+    /**
+   * Gets the uniform variable of type mat4 which holds the world matrix of current object to be drawn
+   * @param scope - Current shader scope
+   * @returns The world matrix of current object to be drawn
    */ static getWorldMatrix(scope) {
         const pb = scope.$builder;
         return scope[UNIFORM_NAME_WORLD_MATRIX] ?? pb.mat4(this.getInstancedUniform(scope, 0), this.getInstancedUniform(scope, 1), this.getInstancedUniform(scope, 2), this.getInstancedUniform(scope, 3));
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the world matrix at previous frame of current object to be drawn
-   * @param scope - Current shader scope
-   * @returns The world matrix at previous frame of current object to be drawn
+    /**
+   * Gets the uniform variable of type mat4 which holds the world matrix at previous frame of current object to be drawn
+   * @param scope - Current shader scope
+   * @returns The world matrix at previous frame of current object to be drawn
    */ static getPrevWorldMatrix(scope) {
         const pb = scope.$builder;
         const that = this;
@@ -636,28 +638,28 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             return scope.Z_getPrevWorldMatrix(framestamp);
         }
     }
-    /**
-   * Gets the instance uniform value of type vec4 by uniform index
-   * @param scope - Current shader scope
-   * @returns instance uniform value
+    /**
+   * Gets the instance uniform value of type vec4 by uniform index
+   * @param scope - Current shader scope
+   * @returns instance uniform value
    */ static getInstancedUniform(scope, uniformIndex) {
         const pb = scope.$builder;
         return scope[UNIFORM_NAME_INSTANCE_DATA].at(pb.add(pb.mul(scope[UNIFORM_NAME_INSTANCE_DATA_STRIDE], pb.uint(scope.$builtins.instanceIndex)), scope[UNIFORM_NAME_INSTANCE_DATA_OFFSET], pb.uint(uniformIndex)));
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the normal matrix of current object to be drawn
-   *
-   * @param scope - Current shader scope
-   * @returns The normal matrix of current object to be drawn
+    /**
+   * Gets the uniform variable of type mat4 which holds the normal matrix of current object to be drawn
+   *
+   * @param scope - Current shader scope
+   * @returns The normal matrix of current object to be drawn
    */ static getNormalMatrix(scope) {
         return this.getWorldMatrix(scope);
     }
-    /**
-   * Vertex shader drawable stuff
-   *
-   * @param scope - Current shader scope
-   * @param skinning - true if skinning is used, otherwise false.
-   * @param instanced - true if instancing is used, otherwise false.
+    /**
+   * Vertex shader drawable stuff
+   *
+   * @param scope - Current shader scope
+   * @param skinning - true if skinning is used, otherwise false.
+   * @param instanced - true if instancing is used, otherwise false.
    */ static vertexShaderDrawableStuff(scope, skinning, morphing, instanced) {
         const pb = scope.$builder;
         if (instanced) {
@@ -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,153 +853,183 @@ 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);
         }
     }
-    /**
-   * Gets the uniform variable of type float which holds the strength of the environment light
-   *
-   * @remarks
-   * This function can only be used in the fragment shader
-   *
-   * @param scope - Current shader scope
-   * @returns The uniform variable of which presents the strength of the environment light
+    /**
+   * Gets the uniform variable of type float which holds the strength of the environment light
+   *
+   * @remarks
+   * This function can only be used in the fragment shader
+   *
+   * @param scope - Current shader scope
+   * @returns The uniform variable of which presents the strength of the environment light
    */ static getEnvLightStrength(scope) {
         return scope.light.envLightStrength;
     }
-    /**
-   * Gets the uniform variable of type float which holds the specular strength of the environment light
-   *
-   * @remarks
-   * This function can only be used in the fragment shader
-   *
-   * @param scope - Current shader scope
-   * @returns The uniform variable which presents the specular strength of the environment light
+    /**
+   * Gets the uniform variable of type float which holds the specular strength of the environment light
+   *
+   * @remarks
+   * This function can only be used in the fragment shader
+   *
+   * @param scope - Current shader scope
+   * @returns The uniform variable which presents the specular strength of the environment light
    */ static getEnvLightSpecularStrength(scope) {
         return scope.light.envLightSpecularStrength ?? scope.$builder.float(1);
     }
-    /**
-   * Gets current scene color texture
-   * @param scope - Current shader scope
-   * @returns current scene color texture
+    /**
+   * Gets current scene color texture
+   * @param scope - Current shader scope
+   * @returns current scene color texture
    */ static getSceneColorTexture(scope) {
         return scope[UNIFORM_NAME_SCENE_COLOR_MAP];
     }
-    /**
-   * Gets the size of current scene color texture
-   * @param scope - Current shader scope
-   * @returns The size of current scene color texture
+    /**
+   * Gets the size of current scene color texture
+   * @param scope - Current shader scope
+   * @returns The size of current scene color texture
    */ static getSceneColorTextureSize(scope) {
         return scope[UNIFORM_NAME_SCENE_COLOR_MAP_SIZE];
     }
-    /**
-   * Gets current linear depth texture
-   * @param scope - Current shader scope
-   * @returns current linear depth texture
+    /**
+   * Gets current linear depth texture
+   * @param scope - Current shader scope
+   * @returns current linear depth texture
    */ static getLinearDepthTexture(scope) {
         return scope[UNIFORM_NAME_LINEAR_DEPTH_MAP];
     }
-    /**
-   * Gets the size of current linear depth texture
-   * @param scope - Current shader scope
-   * @returns The size of current linear depth texture
+    /**
+   * Gets the size of current linear depth texture
+   * @param scope - Current shader scope
+   * @returns The size of current linear depth texture
    */ static getLinearDepthTextureSize(scope) {
         return scope[UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE];
     }
-    /**
-   * Gets current HiZ depth texture
-   * @param scope - Current shader scope
-   * @returns current HiZ depth texture
+    /**
+   * Gets current HiZ depth texture
+   * @param scope - Current shader scope
+   * @returns current HiZ depth texture
    */ static getHiZDepthTexture(scope) {
         return scope[UNIFORM_NAME_HIZ_DEPTH_MAP];
     }
-    /**
-   * Gets the size of current HiZ depth texture
-   * @param scope - Current shader scope
-   * @returns The size of current HiZ depth texture
+    /**
+   * Gets the size of current HiZ depth texture
+   * @param scope - Current shader scope
+   * @returns The size of current HiZ depth texture
    */ static getHiZDepthTextureSize(scope) {
         return scope[UNIFORM_NAME_HIZ_DEPTH_MAP_INFO].xy;
     }
-    /**
-   * Gets the mipmap levels count of current HiZ depth texture
-   * @param scope - Current shader scope
-   * @returns The mipmap levels count of current HiZ depth texture
+    /**
+   * Gets the mipmap levels count of current HiZ depth texture
+   * @param scope - Current shader scope
+   * @returns The mipmap levels count of current HiZ depth texture
    */ static getHiZDepthTextureMipLevelCount(scope) {
         return scope[UNIFORM_NAME_HIZ_DEPTH_MAP_INFO].z;
     }
-    /**
-   * Gets current baked skybox texture
-   * @param scope - Current shader scope
-   * @returns current baked skybox texture
+    /**
+   * Gets current baked skybox texture
+   * @param scope - Current shader scope
+   * @returns current baked skybox texture
    */ static getBakedSkyTexture(scope) {
         return scope[UNIFORM_NAME_BAKED_SKY_MAP];
     }
-    /**
-   * Gets the elapsed time in seconds
-   * @param scope - Current shader scope
-   * @returns The elapsed time in seconds
+    /**
+   * 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
    */ static getElapsedTime(scope) {
         return scope.camera.elapsedTime;
     }
-    /**
-   * Gets the elapsed time since last frame in seconds
-   * @param scope - Current shader scope
-   * @returns The elapsed time since last frame in seconds
+    /**
+   * Gets the elapsed time since last frame in seconds
+   * @param scope - Current shader scope
+   * @returns The elapsed time since last frame in seconds
    */ static getElapsedTimeFrame(scope) {
         return scope.camera.frameDeltaTime;
     }
-    /**
-   * Gets the uniform variable of type vec3 which holds the camera position
-   * @param scope - Current shader scope
-   * @returns The camera position
+    /**
+   * Gets the uniform variable of type vec3 which holds the camera position
+   * @param scope - Current shader scope
+   * @returns The camera position
    */ static getCameraPosition(scope) {
         return scope.camera.position.xyz;
     }
-    /**
-   * Gets the uniform variable of type float which holds the roughness factor
-   * @param scope - Current shader scope
-   * @returns The roughness factor
+    /**
+   * Gets the uniform variable of type float which holds the roughness factor
+   * @param scope - Current shader scope
+   * @returns The roughness factor
    */ static getCameraRoughnessFactor(scope) {
         return scope.camera.roughnessFactor;
     }
-    /**
-   * Gets framebuffer size for rendering
-   * @param scope - Current shader scope
-   * @returns The roughness factor
+    /**
+   * Gets framebuffer size for rendering
+   * @param scope - Current shader scope
+   * @returns The roughness factor
    */ static getRenderSize(scope) {
         return scope.camera.renderSize;
     }
-    /**
-   * Gets the uniform variable of type uint which holds the framestamp
-   * @param scope - Current shader scope
-   * @returns The framestamp
+    /**
+   * Gets the uniform variable of type uint which holds the framestamp
+   * @param scope - Current shader scope
+   * @returns The framestamp
    */ static getFramestamp(scope) {
         return scope.camera.framestamp;
     }
-    /**
-   * Gets the clip plane flag
-   * @param scope - Current shader scope
-   * @returns A float value of 1 indices the clip plane presents, otherwise 0
+    /**
+   * Gets the clip plane flag
+   * @param scope - Current shader scope
+   * @returns A float value of 1 indices the clip plane presents, otherwise 0
    */ static getCameraClipPlaneFlag(scope) {
         return scope.camera.position.w;
     }
-    /**
-   * Gets the clip plane
-   * @param scope - Current shader scope
-   * @returns A vec4 presents the clip plane
+    /**
+   * Gets the clip plane
+   * @param scope - Current shader scope
+   * @returns A vec4 presents the clip plane
    */ static getCameraClipPlane(scope) {
         return scope.camera.clipPlane;
     }
-    /**
-   * Gets the uniform variable of type vec4 which holds the camera parameters
-   * @param scope - Current shader scope
-   * @returns The camera parameters
+    /**
+   * Gets the uniform variable of type vec4 which holds the camera parameters
+   * @param scope - Current shader scope
+   * @returns The camera parameters
    */ static getCameraParams(scope) {
         return scope.camera.params;
     }
@@ -946,36 +1039,36 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static getCountParams(scope) {
         return scope.light.countParams;
     }
-    /**
-   * Number of shadow-casting lights at the head of the clustered light buffer.
-   * Only defined on the screen-space shadow mask path (ctx.screenSpaceShadowMask);
-   * a clustered light whose buffer index is `<= N` samples the shadow mask.
-   * @internal
+    /**
+   * Number of shadow-casting lights at the head of the clustered light buffer.
+   * Only defined on the screen-space shadow mask path (ctx.screenSpaceShadowMask);
+   * a clustered light whose buffer index is `<= N` samples the shadow mask.
+   * @internal
    */ static getNumShadowLights(scope) {
         return scope.light.numShadowLights;
     }
-    /**
-   * Cluster shadow-mask mode for the current queue: 1 = sample the opaque shadow
-   * mask for shadow lights; 0 = skip shadow lights (they are lit inline by the
-   * additive passes, used for the transparent queue). Only defined on the
-   * screen-space shadow mask path.
-   * @internal
+    /**
+   * Cluster shadow-mask mode for the current queue: 1 = sample the opaque shadow
+   * mask for shadow lights; 0 = skip shadow lights (they are lit inline by the
+   * additive passes, used for the transparent queue). Only defined on the
+   * screen-space shadow mask path.
+   * @internal
    */ static getShadowMaskMode(scope) {
         return scope[UNIFORM_NAME_SHADOW_MASK_MODE];
     }
-    /**
-   * Bind the per-queue cluster shadow-mask mode. Call in the clustered light pass
-   * only when the screen-space shadow mask path is active.
-   * @internal
+    /**
+   * Bind the per-queue cluster shadow-mask mode. Call in the clustered light pass
+   * only when the screen-space shadow mask path is active.
+   * @internal
    */ static setShadowMaskMode(bindGroup, sampleMask) {
         bindGroup.setValue(UNIFORM_NAME_SHADOW_MASK_MODE, sampleMask ? 1 : 0);
     }
-    /**
-   * Lazily-created 1x1x1 rgba8unorm array texture used as the shadow-mask binding
-   * fallback when the screen-space shadow mask path is enabled but no mask was
-   * produced this frame (no shadow-casting lights). It is never sampled in that
-   * case, but the declared uniform still requires a valid binding.
-   * @internal
+    /**
+   * Lazily-created 1x1x1 rgba8unorm array texture used as the shadow-mask binding
+   * fallback when the screen-space shadow mask path is enabled but no mask was
+   * produced this frame (no shadow-casting lights). It is never sampled in that
+   * case, but the declared uniform still requires a valid binding.
+   * @internal
    */ static getDummyShadowMask(device) {
         let tex = this._dummyShadowMask;
         if (!tex || tex.disposed) {
@@ -990,22 +1083,22 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static getClusteredLightIndexTexture(scope) {
         return scope[UNIFORM_NAME_LIGHT_INDEX_TEXTURE];
     }
-    /**
-   * Clustered shadow factor for a light, in `[0,1]` (1 = fully lit).
-   *
-   * - Lights whose clustered buffer index is greater than `numShadowLights` are not
-   *   shadow-casters and return 1.0.
-   * - Shadow-casting lights on the opaque queue (shadow mask mode 1) return the
-   *   screen-space mask value. Layer/channel are derived from the zero-based light
-   *   ordinal `s = index-1`: `layer = s >> 2`, `channel = s & 3`, matching the
-   *   ShadowMaskPass packing.
-   * - Shadow-casting lights on a transparent queue (mode 0) return 0: their clustered
-   *   contribution is suppressed because they are lit inline by the additive passes,
-   *   where shadows are sampled at the true (transparent) surface depth rather than
-   *   from the opaque-depth mask.
-   *
-   * Only valid on the screen-space shadow mask path (ctx.screenSpaceShadowMask).
-   * @internal
+    /**
+   * Clustered shadow factor for a light, in `[0,1]` (1 = fully lit).
+   *
+   * - Lights whose clustered buffer index is greater than `numShadowLights` are not
+   *   shadow-casters and return 1.0.
+   * - Shadow-casting lights on the opaque queue (shadow mask mode 1) return the
+   *   screen-space mask value. Layer/channel are derived from the zero-based light
+   *   ordinal `s = index-1`: `layer = s >> 2`, `channel = s & 3`, matching the
+   *   ShadowMaskPass packing.
+   * - Shadow-casting lights on a transparent queue (mode 0) return 0: their clustered
+   *   contribution is suppressed because they are lit inline by the additive passes,
+   *   where shadows are sampled at the true (transparent) surface depth rather than
+   *   from the opaque-depth mask.
+   *
+   * Only valid on the screen-space shadow mask path (ctx.screenSpaceShadowMask).
+   * @internal
    */ static sampleShadowMask(scope, lightIndex) {
         const pb = scope.$builder;
         const that = this;
@@ -1032,87 +1125,87 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return pb.getGlobalScope()[funcName](lightIndex);
     }
-    /**
-   * Gets the uniform variable that contains atmosphere parameters
-   * @param scope - Current shader scope
-   * @returns The atmosphere parameters
+    /**
+   * Gets the uniform variable that contains atmosphere parameters
+   * @param scope - Current shader scope
+   * @returns The atmosphere parameters
    */ static getAtmosphereParams(scope) {
         return scope.fog.atmosphereParams;
     }
-    /**
-   * Gets the aerial perspective LUT
-   * @param scope - Current shader scope
-   * @returns The aerial perspective LUT texture
+    /**
+   * Gets the aerial perspective LUT
+   * @param scope - Current shader scope
+   * @returns The aerial perspective LUT texture
    */ static getAerialPerspectiveLUT(scope) {
         return scope[UNIFORM_NAME_AERIALPERSPECTIVE_LUT];
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the view projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The view projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the view projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The view projection matrix of current camera
    */ static getViewProjectionMatrix(scope) {
         return scope.camera.viewProjectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the inversed view projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The inversed view projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the inversed view projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The inversed view projection matrix of current camera
    */ static getInvViewProjectionMatrix(scope) {
         return scope.camera.invViewProjectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The projection matrix of current camera
    */ static getProjectionMatrix(scope) {
         return scope.camera.projectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the inversed projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The inversed projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the inversed projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The inversed projection matrix of current camera
    */ static getInvProjectionMatrix(scope) {
         return scope.camera.invProjectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the unjittered view projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The unjittered view projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the unjittered view projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The unjittered view projection matrix of current camera
    */ static getUnjitteredViewProjectionMatrix(scope) {
         return scope.camera.unjitteredVPMatrix;
     }
-    /**
-   * Gets the uniform variable of type vec2 which holds the jitter value of the projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The jitter value of projection matrix of current camera
+    /**
+   * Gets the uniform variable of type vec2 which holds the jitter value of the projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The jitter value of projection matrix of current camera
    */ static getProjectionMatrixJitterValue(scope) {
         return scope.camera.jitterValue;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the jittered inversed view-projection matrix
-   * @param scope - Current shader scope
-   * @returns The jittered inversed view-projection matrix
+    /**
+   * Gets the uniform variable of type mat4 which holds the jittered inversed view-projection matrix
+   * @param scope - Current shader scope
+   * @returns The jittered inversed view-projection matrix
    */ static getJitteredInvVPMatrix(scope) {
         return scope.camera.jitteredInvVPMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the unjittered view projection at previous frame matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The unjittered view projection matrix at previous frame of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the unjittered view projection at previous frame matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The unjittered view projection matrix at previous frame of current camera
    */ static getPrevUnjitteredViewProjectionMatrix(scope) {
         return scope.camera.prevUnjitteredVPMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the view matrix of current camera (world space to camera space)
-   * @param scope - Current shader scope
-   * @returns The view matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the view matrix of current camera (world space to camera space)
+   * @param scope - Current shader scope
+   * @returns The view matrix of current camera
    */ static getViewMatrix(scope) {
         return scope.camera.viewMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the inv-view matrix of current camera (camera space to world space)
-   * @param scope - Current shader scope
-   * @returns The inv-view matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the inv-view matrix of current camera (camera space to world space)
+   * @param scope - Current shader scope
+   * @returns The inv-view matrix of current camera
    */ static getInvViewMatrix(scope) {
         return scope.camera.worldMatrix;
     }
@@ -1166,20 +1259,20 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static getLightExtra(scope, lightIndex) {
         return scope[UNIFORM_NAME_LIGHT_BUFFER].at(scope.$builder.add(scope.$builder.mul(lightIndex, 4), 3));
     }
-    /**
-   * Sets the clip space position in vertex shader
-   *
-   * @remarks
-   * Use this function instead of using
-   * <pre>
-   * // Do not use this
-   * this.$builtins.position = some_value;
-   * // Use this
-   * ShaderFramework.setClipSpacePosition(some_value);
-   * </pre>,
-   *
-   * @param scope - Current shader scope
-   * @param pos - The clip space position to be set
+    /**
+   * Sets the clip space position in vertex shader
+   *
+   * @remarks
+   * Use this function instead of using
+   * <pre>
+   * // Do not use this
+   * this.$builtins.position = some_value;
+   * // Use this
+   * ShaderFramework.setClipSpacePosition(some_value);
+   * </pre>,
+   *
+   * @param scope - Current shader scope
+   * @param pos - The clip space position to be set
    */ static setClipSpacePosition(scope, pos) {
         const pb = scope.$builder;
         const cameraParams = this.getCameraParams(scope);
@@ -1189,20 +1282,20 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.$builtins.position = pos;
         }
     }
-    /**
-   * Get shadow map uniform value
-   *
-   * @param scope - Shader scope
-   * @returns The shadow map texture uniform
+    /**
+   * Get shadow map uniform value
+   *
+   * @param scope - Shader scope
+   * @returns The shadow map texture uniform
    */ static getShadowMap(scope) {
         return scope[UNIFORM_NAME_SHADOW_MAP];
     }
-    /**
-   * Calculates shadow of current fragment
-   *
-   * @param scope - Shader scope
-   * @param NoL - NdotL vector
-   * @returns Shadow of current fragment, 1 means no shadow and 0 means full shadowed.
+    /**
+   * Calculates shadow of current fragment
+   *
+   * @param scope - Shader scope
+   * @param NoL - NdotL vector
+   * @returns Shadow of current fragment, 1 means no shadow and 0 means full shadowed.
    */ static calculateShadow(scope, worldPos, NoL, ctx) {
         const pb = scope.$builder;
         const that = this;
@@ -1278,49 +1371,131 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope[funcName](worldPos, color);
         }
     }
-    /**
-   * Calculates the non-linear depth from linear depth
-   *
-   * @param scope - Current shader scope
-   * @param depth - The 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 calculated non-linear depth
+    /**
+   * Calculates the non-linear depth from linear depth
+   *
+   * @param scope - Current shader scope
+   * @param depth - The 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 calculated non-linear depth
    */ 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));
     }
-    /**
-   * Calculates the linear depth from non-linear depth
-   *
-   * @param scope - Current shader scope
-   * @param depth - The non-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 calculated linear depth
+    /**
+   * Calculates the linear depth from non-linear depth
+   *
+   * @param scope - Current shader scope
+   * @param depth - The non-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 calculated linear depth
    */ 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));
     }
-    /**
-   * Calculates the normalized linear depth from non-linear depth
-   *
-   * @param scope - Current shader scope
-   * @param depth - The non-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 calculated normalized linear depth
+    /**
+   * Calculates the normalized linear depth from non-linear depth
+   *
+   * @param scope - Current shader scope
+   * @param depth - The non-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 calculated normalized linear depth
    */ 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));
     }
-    /**
-   * Sample linear depth from linear depth texture
-   * @param scope - Current shader scope
-   * @param tex - The linear depth texture
-   * @param uv - The uv coordinates
-   * @param level - The mipmap level to sample
-   * @returns Linear depth value
+    /**
+   * 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
+   * @param uv - The uv coordinates
+   * @param level - The mipmap level to sample
+   * @returns Linear depth value
    */ static sampleLinearDepth(scope, tex, uv, level) {
         const pb = scope.$builder;
         const depth = pb.textureSampleLevel(tex, uv, level);
@@ -1335,30 +1510,30 @@ 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));
         });
         return scope.zSamplePositionFromDepth(uv, cameraNearFar, mat);
     }
-    /**
-   * Sample linear depth from linear depth texture with backface
-   * @param scope - Current shader scope
-   * @param tex - The linear depth texture
-   * @param uv - The uv coordinates
-   * @param level - The mipmap level to sample
-   * @returns Linear depth value
+    /**
+   * Sample linear depth from linear depth texture with backface
+   * @param scope - Current shader scope
+   * @param tex - The linear depth texture
+   * @param uv - The uv coordinates
+   * @param level - The mipmap level to sample
+   * @returns Linear depth value
    */ static sampleLinearDepthWithBackface(scope, tex, uv, level) {
         const pb = scope.$builder;
         return pb.textureSampleLevel(tex, uv, level).rg;
     }
-    /**
-   * Transform color to sRGB color space if nessesary
-   *
-   * @param scope - Current shader scope
-   * @param outputColor - The color to be transformed
-   * @returns The transformed color
+    /**
+   * Transform color to sRGB color space if nessesary
+   *
+   * @param scope - Current shader scope
+   * @param outputColor - The color to be transformed
+   * @returns The transformed color
    */ static encodeColorOutput(scope, outputColor) {
         const pb = scope.$builder;
         const that = this;
@@ -1375,6 +1550,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return pb.getGlobalScope()[funcName](outputColor);
     }
+    /** @internal */ static getMaxClusterLights() {
+        return getDevice().type === 'webgl' ? 64 : 255;
+    }
 }
 
 export { ShaderHelper };