@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/material/shader/helper.js

@@ -1,22 +1,51 @@
 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_SKIN_EXTRA_INFLUENCE_PAIRS, MORPH_WEIGHTS_VECTOR_COUNT, MORPH_TARGET_POSITION, MORPH_TARGET_NORMAL, MORPH_TARGET_TANGENT, MORPH_ATTRIBUTE_VECTOR_COUNT, LIGHT_TYPE_DIRECTIONAL } from '../../values.js';
+import { RENDER_PASS_TYPE_DEPTH, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_VOXELIZE, RENDER_PASS_TYPE_LIGHT, MaterialVaryingFlags, MORPH_WEIGHTS_VECTOR_COUNT, MAX_SKIN_EXTRA_INFLUENCE_PAIRS, MORPH_TARGET_POSITION, MORPH_TARGET_NORMAL, MORPH_TARGET_TANGENT, MORPH_ATTRIBUTE_VECTOR_COUNT, LIGHT_TYPE_DIRECTIONAL } from '../../values.js';
 import { ProgramBuilder } from '@zephyr3d/device';
-import { decodeNormalizedFloatFromRGBA, linearToGamma } from '../../shaders/misc.js';
+import { linearToGamma } from '../../shaders/misc.js';
+import { declareVoxelizeUniforms } from '../../shaders/gi.js';
 import { getSamplerOptions, fetchSampler } from '../../utility/misc.js';
-import { PHYSICAL_BAKE_EXPOSURE } from '../../utility/physical.js';
+import { getGICacheExposure, 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';
 import { getShadowReceiverNoL, getShadowReceiverBiasFactor } from '../../shadow/receiver_bias.js';
+import { declareGlobalSDFUniforms, declareDynamicSDFUniforms, GLOBAL_SDF_TEXTURE, sampleSceneSDF } from '../../shaders/sdf.js';
 
+/** Clipmap levels of the scene field declared in a program, by program builder. */ const sceneSDFLevels = new WeakMap();
 const UNIFORM_NAME_LIGHT_BUFFER = 'Z_UniformLightBuffer';
 const UNIFORM_NAME_LIGHT_INDEX_TEXTURE = 'Z_UniformLightIndexTex';
+const UNIFORM_NAME_CLUSTER_GRID = 'Z_ClusterGrid';
+const UNIFORM_NAME_CLUSTER_LIGHT_LIST = 'Z_ClusterLightList';
 const UNIFORM_NAME_BAKED_SKY_MAP = 'Z_UniformBakedSky';
 const UNIFORM_NAME_AERIALPERSPECTIVE_LUT = 'Z_UniformAerialPerspectiveLUT';
 const UNIFORM_NAME_SKYDISTANTLIGHT_LUT = 'Z_UniformSkyDistantLightLUT';
+const UNIFORM_NAME_FOG_SKYLIGHT_CUBEMAP = 'Z_UniformFogSkyLightCubemap';
 const UNIFORM_NAME_SHADOW_MAP = 'Z_UniformShadowMap';
 const UNIFORM_NAME_SHADOW_MASK = 'Z_UniformShadowMask';
 const UNIFORM_NAME_SHADOW_MASK_MODE = 'Z_UniformShadowMaskMode';
+const UNIFORM_NAME_TRANSMISSION_THICKNESS = 'Z_UniformTransmissionThickness';
+const UNIFORM_NAME_CAUSTIC_MAP = 'Z_UniformCausticMap';
+const UNIFORM_NAME_CAUSTIC_HEIGHT_MAP = 'Z_UniformCausticHeightMap';
+/**
+ * Offset added to a surface height before it is stored in the caustic height
+ * map, so that a cleared texel - no surface on that ray - is distinguishable
+ * from a surface at the rest level. A ray with no water on it must read as
+ * dry, not as submerged under a flat surface: on the down-sun side of a
+ * footprint edge, a receiver below the rest level but above a trough would
+ * otherwise be lit through water that is not there. Eight keeps troughs down
+ * to seven metres positive and leaves half floats millimetre precision.
+ * @internal
+ */ const CAUSTIC_HEIGHT_BIAS = 8;
+/**
+ * Water bodies that can cast caustics into one map.
+ *
+ * They share the map and the slice, so this is not a limit on how much water a
+ * scene may hold - only on how many separate surfaces the receiver will test
+ * itself against, which it does per fragment. Four covers a lake with a couple
+ * of pools beside it; beyond that the renderer keeps the largest four, which
+ * are the ones a viewer is most likely to be standing over.
+ */ const MAX_CAUSTIC_WATERS = 4;
+const UNIFORM_NAME_CAUSTIC_PARAMS = 'Z_UniformCausticParams';
 const UNIFORM_NAME_LINEAR_DEPTH_MAP = 'Z_UniformLinearDepth';
 const UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE = 'Z_UniformLinearDepthSize';
 const UNIFORM_NAME_SCENE_COLOR_MAP = 'Z_UniformSceneColor';
@@ -33,6 +62,7 @@ const UNIFORM_NAME_INSTANCE_DATA_OFFSET = 'Z_UniformInstanceDataOffset';
 const UNIFORM_NAME_BONE_MATRICES = 'Z_UniformBoneMatrices';
 const UNIFORM_NAME_BONE_TEXTURE_SIZE = 'Z_UniformBoneTexSize';
 const UNIFORM_NAME_BONE_INV_BIND_MATRIX = 'Z_UniformBoneInvBindMatrix';
+const UNIFORM_NAME_SKIN_PALETTE_BASE = 'Z_UniformSkinPaletteBase';
 const UNIFORM_NAME_SKIN_INFLUENCE_DATA = 'Z_UniformSkinInfluenceData';
 const UNIFORM_NAME_SKIN_INFLUENCE_INFO = 'Z_UniformSkinInfluenceInfo';
 const UNIFORM_NAME_MORPH_DATA = 'Z_UniformMorphData';
@@ -46,6 +76,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     static MATERIAL_INSTANCE_DATA_OFFSET = 9;
     /** @internal */ static defaultSunDir = Vector3.one().inplaceNormalize();
     /** @internal 1x1x1 fallback bound to the shadow-mask uniform when no mask exists this frame. */ static _dummyShadowMask = null;
+    static _dummyTransmissionThickness = null;
     /** @internal */ static SKIN_MATRIX_NAME = 'Z_SkinMatrix';
     static SKIN_PREV_MATRIX_NAME = 'Z_PrevSkinMatrix';
     static SKIN_BONE_OFFSET = 'Z_boneOffset';
@@ -105,6 +136,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     static getBoneInvBindMatrixUniformName() {
         return UNIFORM_NAME_BONE_INV_BIND_MATRIX;
     }
+    static getSkinPaletteBaseUniformName() {
+        return UNIFORM_NAME_SKIN_PALETTE_BASE;
+    }
     static getSkinInfluenceDataUniformName() {
         return UNIFORM_NAME_SKIN_INFLUENCE_DATA;
     }
@@ -209,8 +243,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             if (casterParams) {
                 casterParams.impl?.declareCasterUniforms(scope, casterParams);
             }
-        } else if (ctx.renderPass.type === RENDER_PASS_TYPE_DEPTH || ctx.renderPass.type === RENDER_PASS_TYPE_OBJECT_COLOR) {
+        } else if (ctx.renderPass.type === RENDER_PASS_TYPE_DEPTH || ctx.renderPass.type === RENDER_PASS_TYPE_OBJECT_COLOR || ctx.renderPass.type === RENDER_PASS_TYPE_VOXELIZE) {
             scope.camera = cameraStruct().uniform(0);
+            // Write-only storage textures are fragment-only in WebGPU
+            if (ctx.renderPass.type === RENDER_PASS_TYPE_VOXELIZE && pb.shaderKind === 'fragment') {
+                declareVoxelizeUniforms(scope, 0);
+            }
         } else if (ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT) {
             const useClusteredLighting = !ctx.currentShadowLight;
             if (ctx.materialFlags & MaterialVaryingFlags.APPLY_FOG) {
@@ -226,6 +264,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 // Static samplers: LUTs are rgba16f without mipmaps
                 scope[UNIFORM_NAME_AERIALPERSPECTIVE_LUT] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
                 scope[UNIFORM_NAME_SKYDISTANTLIGHT_LUT] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+                // Mipmapped radiance map, sampled at a roughness-selected LOD
+                scope[UNIFORM_NAME_FOG_SKYLIGHT_CUBEMAP] = pb.texCube().uniform(0).withSampler(getSamplerOptions('clamp_linear'));
             }
             const lightStruct = ctx.currentShadowLight ? pb.defineStruct([
                 pb.vec3('sunDir'),
@@ -249,7 +289,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 pb.float('envLightSpecularStrength'),
                 pb.vec4('clusterParams'),
                 pb.ivec4('countParams'),
+                // Buffer indices of the lights shaded outside the clusters, zero-terminated.
+                pb.ivec4('globalLights'),
                 pb.ivec2('lightIndexTexSize'),
+                // Nonzero when the clusters were sliced for an orthographic camera
+                // (linear depth slices instead of exponential).
+                pb.int('clusterOrtho'),
                 // Number of shadow-casting lights at the head of the clustered light
                 // buffer (indices 1..N). Only present on the screen-space shadow mask
                 // path (part of the global bind group hash), so the declared and bound
@@ -261,9 +306,17 @@ 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[(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);
+                if (this.usesClusterLightLists()) {
+                    // Storage buffers sized to the frame's lights: no cap on the lights in total or
+                    // per cluster. See ClusteredLight for the layout of the grid and the lists.
+                    scope[UNIFORM_NAME_LIGHT_BUFFER] = pb.vec4[0]().storageBufferReadonly(0);
+                    scope[UNIFORM_NAME_CLUSTER_GRID] = pb.uint[0]().storageBufferReadonly(0);
+                    scope[UNIFORM_NAME_CLUSTER_LIGHT_LIST] = pb.uint[0]().storageBufferReadonly(0);
+                } else {
+                    scope[UNIFORM_NAME_LIGHT_BUFFER] = pb.vec4[(this.getMaxClusterLights() + 1) * 4]().uniformBuffer(0);
+                    // The light index texture is fetched with textureLoad
+                    scope[UNIFORM_NAME_LIGHT_INDEX_TEXTURE] = pb.utex2D().noSampler().uniform(0);
+                }
                 // Screen-space shadow mask array (rgba8unorm, 4 shadow lights per layer).
                 // Sampled by clustered lights whose buffer index is <= numShadowLights.
                 // Presence is keyed into the global bind group hash, so declared and bound
@@ -276,6 +329,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                     // e.g. OIT hair, where the opaque-depth mask would be incorrect).
                     scope[UNIFORM_NAME_SHADOW_MASK_MODE] = pb.int().uniform(0);
                 }
+                // Light-space thickness for subsurface transmission, packed exactly like
+                // the shadow mask. Presence is keyed into the bind group hash through
+                // ctx.transmissionThickness, so declared and bound layouts always agree.
+                if (ctx.transmissionThickness) {
+                    scope[UNIFORM_NAME_TRANSMISSION_THICKNESS] = pb.tex2DArray().uniform(0);
+                }
             }
             // Baked sky cube: rgba16f without mipmaps
             scope[UNIFORM_NAME_BAKED_SKY_MAP] = pb.texCube().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
@@ -294,6 +353,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 }
                 scope[UNIFORM_NAME_SHADOW_MAP] = tex.uniform(0);
             }
+            if (this.usesWaterCaustics(ctx)) {
+                this.declareWaterCausticUniforms(pb);
+            }
             if (ctx.drawEnvLight) {
                 ctx.env.light.envLight.initShaderBindings(pb, ctx);
             }
@@ -304,8 +366,18 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 scope[UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.sceneColorTexture) {
-                // Scene color copy: single mip level
-                scope[UNIFORM_NAME_SCENE_COLOR_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+                // Mip-filtered, because the refraction background is read at a LOD and
+                // not only at mip 0: the water picks one from how deep and how turbid
+                // the column it is looking through is. A `nomip` sampler pins mip 0
+                // whatever LOD the shader passes, so this and the copy's level count
+                // have to change together - and each backend only honours one of them.
+                // WebGPU binds the sampler declared here as a static binding the runtime
+                // cannot overwrite; WebGL falls back to the texture's own sampler, whose
+                // mip filter follows its level count.
+                //
+                // Every other reader of this texture passes an explicit LOD 0 (SSR hits,
+                // the sky blend), so none of them changes behaviour.
+                scope[UNIFORM_NAME_SCENE_COLOR_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear'));
                 scope[UNIFORM_NAME_SCENE_COLOR_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.HiZTexture) {
@@ -343,75 +415,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         if (!this.hasSkinning(scope)) {
             return null;
         }
-        const pb = scope.$builder;
-        const isWebGL = pb.getDevice().type === 'webgl';
-        const supportsTextureLoad = !isWebGL;
-        const funcNameGetBoneMatrixFromTexture = 'Z_getBoneMatrixFromTexture';
-        pb.func(funcNameGetBoneMatrixFromTexture, [
-            pb.int('boneIndex')
-        ], function() {
-            const boneTexture = this[UNIFORM_NAME_BONE_MATRICES];
-            this.$l.uvOffsets = pb.textureSampleLevel(boneTexture, pb.div(pb.vec2(0.5), this[UNIFORM_NAME_BONE_TEXTURE_SIZE]), 0);
-            this.$l.currentOffset = pb.int(this.uvOffsets.x);
-            this.$l.w = this[UNIFORM_NAME_BONE_TEXTURE_SIZE].x;
-            this.$l.pixelIndex = pb.float(pb.mul(pb.add(this.boneIndex, this.currentOffset), 4));
-            this.$l.xIndex = pb.mod(this.pixelIndex, this.w);
-            this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.w));
-            this.$l.u1 = pb.div(pb.add(this.xIndex, 0.5), this.w);
-            this.$l.u2 = pb.div(pb.add(this.xIndex, 1.5), this.w);
-            this.$l.u3 = pb.div(pb.add(this.xIndex, 2.5), this.w);
-            this.$l.u4 = pb.div(pb.add(this.xIndex, 3.5), this.w);
-            this.$l.v = pb.div(pb.add(this.yIndex, 0.5), this.w);
-            this.$l.row1 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u1, this.v), 0);
-            this.$l.row2 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u2, this.v), 0);
-            this.$l.row3 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u3, this.v), 0);
-            this.$l.row4 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u4, this.v), 0);
-            this.$return(pb.mat4(this.row1, this.row2, this.row3, this.row4));
-        });
-        const funcNameGetSkinningMatrix = 'Z_getSkinningMatrix';
-        pb.func(funcNameGetSkinningMatrix, [], function() {
-            const invBindMatrix = this[UNIFORM_NAME_BONE_INV_BIND_MATRIX];
-            const blendIndices = scope.$getVertexAttrib('blendIndices');
-            const blendWeights = scope.$getVertexAttrib('blendWeights');
-            this.$l.m0 = scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(blendIndices[0]));
-            this.$l.m1 = scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(blendIndices[1]));
-            this.$l.m2 = scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(blendIndices[2]));
-            this.$l.m3 = scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(blendIndices[3]));
-            this.$l.m = pb.add(pb.mul(this.m0, blendWeights.x), pb.mul(this.m1, blendWeights.y), pb.mul(this.m2, blendWeights.z), pb.mul(this.m3, blendWeights.w));
-            this.$l.skinInfo = this[UNIFORM_NAME_SKIN_INFLUENCE_INFO];
-            this.$if(pb.greaterThan(this.skinInfo.z, 4), function() {
-                this.$l.vertexIndex = isWebGL ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
-                this.$l.texWidth = pb.int(this.skinInfo.x);
-                this.$l.pairCount = pb.int(this.skinInfo.w);
-                this.$for(pb.int('pairIndex'), 0, MAX_SKIN_EXTRA_INFLUENCE_PAIRS, function() {
-                    this.$if(pb.greaterThanEqual(this.pairIndex, this.pairCount), function() {
-                        this.$break();
-                    });
-                    this.$l.pixelIndex = pb.add(pb.mul(this.vertexIndex, this.pairCount), this.pairIndex);
-                    this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
-                    this.$l.yIndex = pb.div(this.pixelIndex, this.texWidth);
-                    if (supportsTextureLoad) {
-                        this.$l.extra = pb.textureLoad(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.ivec2(this.xIndex, this.yIndex), 0);
-                    } else {
-                        this.$l.u = pb.div(pb.add(pb.float(this.xIndex), 0.5), this.skinInfo.x);
-                        this.$l.v = pb.div(pb.add(pb.float(this.yIndex), 0.5), this.skinInfo.y);
-                        this.$l.extra = pb.textureSampleLevel(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.vec2(this.u, this.v), 0);
-                    }
-                    this.$if(pb.greaterThan(this.extra.y, 0), function() {
-                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(this.extra.x)), this.extra.y));
-                    });
-                    this.$if(pb.greaterThan(this.extra.w, 0), function() {
-                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(this.extra.z)), this.extra.w));
-                    });
-                });
-            });
-            this.$return(pb.mul(invBindMatrix, this.m));
-        });
-        return scope.$g[funcNameGetSkinningMatrix]();
+        if (!scope[this.SKIN_MATRIX_NAME]) {
+            this.prepareSkinAnimation(scope);
+        }
+        return scope[this.SKIN_MATRIX_NAME];
     }
     static calculateMorphDelta(scope, attrib) {
         const pb = scope.$builder;
-        const isWebGL1 = pb.getDevice().type === 'webgl';
         if (pb.shaderKind !== 'vertex') {
             throw new Error(`ShaderHelper.calculateMorphDelta(): must be called at vertex stage`);
         }
@@ -423,7 +433,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$if(pb.lessThan(this.offset, 0), function() {
                 this.$return(pb.vec4(0));
             });
-            this.$l.vertexIndex = isWebGL1 ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
+            this.$l.vertexIndex = pb.int(scope.$builtins.vertexIndex);
             const morphInfo = scope[that.getMorphInfoUniformName()];
             this.$l.metaData = pb.ivec4(morphInfo[0]);
             this.$l.texWidth = pb.float(this.metaData.x);
@@ -431,43 +441,21 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$l.numVertices = this.metaData.z;
             this.$l.numTargets = this.metaData.w;
             this.$l.value = pb.vec4(0);
-            if (isWebGL1) {
-                this.$for(pb.int('i'), 0, MORPH_WEIGHTS_VECTOR_COUNT, function() {
-                    this.$for(pb.int('j'), 0, 4, function() {
-                        this.$l.index = pb.add(pb.mul(this.i, 4), this.j);
-                        this.$if(pb.greaterThanEqual(this.index, this.numTargets), function() {
-                            this.$return(this.value);
-                        });
-                        this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
-                        this.$if(pb.notEqual(this.weight, 0), function() {
-                            this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
-                            this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.targetIndex, this.numVertices), this.vertexIndex));
-                            this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
-                            this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.texWidth));
-                            this.$l.u = pb.div(pb.add(this.xIndex, 0.5), this.texWidth);
-                            this.$l.v = pb.div(pb.add(this.yIndex, 0.5), this.texHeight);
-                            this.$l.morphValue = pb.textureSampleLevel(this[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0);
-                            this.value = pb.add(this.value, pb.mul(this.morphValue, this.weight));
-                        });
-                    });
-                });
-            } else {
-                this.$for(pb.int('t'), 0, this.numTargets, function() {
-                    this.$l.i = pb.sar(this.t, 2);
-                    this.$l.j = pb.compAnd(this.t, 3);
-                    this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
-                    this.$if(pb.notEqual(this.weight, 0), function() {
-                        this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
-                        this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.targetIndex, this.numVertices), this.vertexIndex));
-                        this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
-                        this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.texWidth));
-                        this.$l.u = pb.div(pb.add(this.xIndex, 0.5), this.texWidth);
-                        this.$l.v = pb.div(pb.add(this.yIndex, 0.5), this.texHeight);
-                        this.$l.morphValue = pb.textureSampleLevel(this[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0);
-                        this.value = pb.add(this.value, pb.mul(this.morphValue, this.weight));
-                    });
+            this.$for(pb.int('t'), 0, this.numTargets, function() {
+                this.$l.i = pb.sar(this.t, 2);
+                this.$l.j = pb.compAnd(this.t, 3);
+                this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
+                this.$if(pb.notEqual(this.weight, 0), function() {
+                    this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
+                    this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.targetIndex, this.numVertices), this.vertexIndex));
+                    this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
+                    this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.texWidth));
+                    this.$l.u = pb.div(pb.add(this.xIndex, 0.5), this.texWidth);
+                    this.$l.v = pb.div(pb.add(this.yIndex, 0.5), this.texHeight);
+                    this.$l.morphValue = pb.textureSampleLevel(this[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0);
+                    this.value = pb.add(this.value, pb.mul(this.morphValue, this.weight));
                 });
-            }
+            });
             this.$return(this.value);
         });
         const pos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (attrib >> 2);
@@ -514,7 +502,6 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    * @internal
    */ static calculateMorphDirectionByDisplacement(scope, base, attrib) {
         const pb = scope.$builder;
-        const isWebGL1 = pb.getDevice().type === 'webgl';
         if (pb.shaderKind !== 'vertex') {
             throw new Error(`ShaderHelper.calculateMorphDirectionByDisplacement(): must be called at vertex stage`);
         }
@@ -526,7 +513,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             pb.int('directionOffset'),
             pb.int('positionOffset')
         ], function() {
-            this.$l.vertexIndex = isWebGL1 ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
+            this.$l.vertexIndex = pb.int(scope.$builtins.vertexIndex);
             const morphInfo = scope[that.getMorphInfoUniformName()];
             this.$l.metaData = pb.ivec4(morphInfo[0]);
             this.$l.texWidth = pb.float(this.metaData.x);
@@ -564,27 +551,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                     this.weightSum = pb.add(this.weightSum, this.displacementWeight);
                 });
             };
-            if (isWebGL1) {
-                this.$for(pb.int('i'), 0, MORPH_WEIGHTS_VECTOR_COUNT, function() {
-                    this.$for(pb.int('j'), 0, 4, function() {
-                        this.$l.index = pb.add(pb.mul(this.i, 4), this.j);
-                        this.$if(pb.greaterThanEqual(this.index, this.numTargets), function() {
-                            this.$break();
-                        });
-                        this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
-                        this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
-                        accumulateTarget(this);
-                    });
-                });
-            } else {
-                this.$for(pb.int('t'), 0, this.numTargets, function() {
-                    this.$l.i = pb.sar(this.t, 2);
-                    this.$l.j = pb.compAnd(this.t, 3);
-                    this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
-                    this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
-                    accumulateTarget(this);
-                });
-            }
+            this.$for(pb.int('t'), 0, this.numTargets, function() {
+                this.$l.i = pb.sar(this.t, 2);
+                this.$l.j = pb.compAnd(this.t, 3);
+                this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
+                this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
+                accumulateTarget(this);
+            });
             this.$l.fallback = scope.$g[normalizeName](this.base, this.directionDelta);
             this.$if(pb.lessThan(this.weightSum, 1e-6), function() {
                 this.$return(this.fallback);
@@ -628,8 +601,6 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         const that = this;
         const pb = scope.$builder;
-        const isWebGL = pb.getDevice().type === 'webgl';
-        const supportsTextureLoad = !isWebGL;
         const funcNameGetBoneMatrixFromTexture = 'Z_getBoneMatrixFromTexture';
         pb.func(funcNameGetBoneMatrixFromTexture, [
             pb.float('boneIndex'),
@@ -637,6 +608,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         ], function() {
             const boneTexture = this[UNIFORM_NAME_BONE_MATRICES];
             this.$l.w = this[UNIFORM_NAME_BONE_TEXTURE_SIZE].x;
+            this.$l.h = this[UNIFORM_NAME_BONE_TEXTURE_SIZE].y;
             this.$l.pixelIndex = pb.mul(pb.add(this.boneIndex, this.boneOffset), 4);
             this.$l.xIndex = pb.mod(this.pixelIndex, this.w);
             this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.w));
@@ -644,7 +616,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$l.u2 = pb.div(pb.add(this.xIndex, 1.5), this.w);
             this.$l.u3 = pb.div(pb.add(this.xIndex, 2.5), this.w);
             this.$l.u4 = pb.div(pb.add(this.xIndex, 3.5), this.w);
-            this.$l.v = pb.div(pb.add(this.yIndex, 0.5), this.w);
+            this.$l.v = pb.div(pb.add(this.yIndex, 0.5), this.h);
             this.$l.row1 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u1, this.v), 0);
             this.$l.row2 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u2, this.v), 0);
             this.$l.row3 = pb.textureSampleLevel(boneTexture, pb.vec2(this.u3, this.v), 0);
@@ -665,7 +637,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$l.m = pb.add(pb.mul(this.m0, blendWeights.x), pb.mul(this.m1, blendWeights.y), pb.mul(this.m2, blendWeights.z), pb.mul(this.m3, blendWeights.w));
             this.$l.skinInfo = this[UNIFORM_NAME_SKIN_INFLUENCE_INFO];
             this.$if(pb.greaterThan(this.skinInfo.z, 4), function() {
-                this.$l.vertexIndex = isWebGL ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
+                this.$l.vertexIndex = pb.int(scope.$builtins.vertexIndex);
                 this.$l.texWidth = pb.int(this.skinInfo.x);
                 this.$l.pairCount = pb.int(this.skinInfo.w);
                 this.$for(pb.int('pairIndex'), 0, MAX_SKIN_EXTRA_INFLUENCE_PAIRS, function() {
@@ -675,13 +647,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                     this.$l.pixelIndex = pb.add(pb.mul(this.vertexIndex, this.pairCount), this.pairIndex);
                     this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
                     this.$l.yIndex = pb.div(this.pixelIndex, this.texWidth);
-                    if (supportsTextureLoad) {
-                        this.$l.extra = pb.textureLoad(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.ivec2(this.xIndex, this.yIndex), 0);
-                    } else {
-                        this.$l.u = pb.div(pb.add(pb.float(this.xIndex), 0.5), this.skinInfo.x);
-                        this.$l.v = pb.div(pb.add(pb.float(this.yIndex), 0.5), this.skinInfo.y);
-                        this.$l.extra = pb.textureSampleLevel(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.vec2(this.u, this.v), 0);
-                    }
+                    this.$l.extra = pb.textureLoad(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.ivec2(this.xIndex, this.yIndex), 0);
                     this.$if(pb.greaterThan(this.extra.y, 0), function() {
                         this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](this.extra.x, this.boneOffset), this.extra.y));
                     });
@@ -693,8 +659,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$return(pb.mul(invBindMatrix, this.m));
         });
         const motionVector = !!this.getUnjitteredViewProjectionMatrix(scope);
+        // The palette header slot holds the slot indices of the current and previous matrix sets
         const boneTexture = scope[UNIFORM_NAME_BONE_MATRICES];
-        scope.$l[that.SKIN_BONE_OFFSET] = pb.textureSampleLevel(boneTexture, pb.div(pb.vec2(0.5), scope[UNIFORM_NAME_BONE_TEXTURE_SIZE]), 0).xy;
+        const paletteBase = scope[UNIFORM_NAME_SKIN_PALETTE_BASE] ?? this.getInstancedUniform(scope, 4).z;
+        const boneTextureSize = scope[UNIFORM_NAME_BONE_TEXTURE_SIZE];
+        scope.$l.Z_skinHeaderTexel = pb.mul(paletteBase, 4);
+        scope.$l[that.SKIN_BONE_OFFSET] = pb.textureSampleLevel(boneTexture, pb.div(pb.add(pb.vec2(pb.mod(scope.Z_skinHeaderTexel, boneTextureSize.x), pb.floor(pb.div(scope.Z_skinHeaderTexel, boneTextureSize.x))), pb.vec2(0.5)), boneTextureSize), 0).xy;
         scope.$l[that.SKIN_MATRIX_NAME] = scope[funcNameGetSkinningMatrix](scope[that.SKIN_BONE_OFFSET].x);
         if (motionVector) {
             scope.$l[that.SKIN_PREV_MATRIX_NAME] = scope[funcNameGetSkinningMatrix](scope[that.SKIN_BONE_OFFSET].y);
@@ -929,6 +899,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope[UNIFORM_NAME_BONE_MATRICES] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
             scope[UNIFORM_NAME_BONE_INV_BIND_MATRIX] = pb.mat4().uniform(1);
             scope[UNIFORM_NAME_BONE_TEXTURE_SIZE] = pb.vec2().uniform(1);
+            if (!instanced) {
+                scope[UNIFORM_NAME_SKIN_PALETTE_BASE] = pb.float().uniform(1);
+            }
             scope[UNIFORM_NAME_SKIN_INFLUENCE_DATA] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
             scope[UNIFORM_NAME_SKIN_INFLUENCE_INFO] = pb.vec4().uniform(1);
         }
@@ -942,7 +915,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     }
     /** @internal */ static setCameraUniforms(bindGroup, ctx, camera, linear) {
         const pos = camera.getWorldPosition();
-        const useJitter = ctx.motionVectors && ctx.renderPass.type !== RENDER_PASS_TYPE_SHADOWMAP && ctx.renderPass.type !== RENDER_PASS_TYPE_OBJECT_COLOR;
+        const useJitter = ctx.motionVectors && ctx.renderPass.type !== RENDER_PASS_TYPE_SHADOWMAP && ctx.renderPass.type !== RENDER_PASS_TYPE_OBJECT_COLOR && ctx.renderPass.type !== RENDER_PASS_TYPE_VOXELIZE;
         const cameraStruct = {
             position: new Vector4(pos.x, pos.y, pos.z, 0),
             renderSize: new Vector2(ctx.renderWidth, ctx.renderHeight),
@@ -991,12 +964,14 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 viewMatrix: light.viewMatrix,
                 depthBias: shadowMapParams.depthBiasValues[0],
                 implParams: shadowMapParams.impl.getParams(this._lightUniformShadow.implParams),
-                lightType: light.lightType
+                // The shadow projection, not the light's own type: a rect light renders a point light's
+                // cube, so its casters must write the point light's radial depth.
+                lightType: shadowMapParams.lightType
             });
             shadowMapParams.impl?.applyCasterUniforms(bindGroup, shadowMapParams);
         }
     }
-    /** @internal */ static setFogUniforms(bindGroup, withAerialPerspective, fogType, additive, atmosphereParams, heightFogParams, aerialPerspectiveLUT, skyDistantLightLUT) {
+    /** @internal */ static setFogUniforms(bindGroup, withAerialPerspective, fogType, additive, atmosphereParams, heightFogParams, aerialPerspectiveLUT, skyDistantLightLUT, skyLightCubemap) {
         this._fogUniforms.withAerialPerspective = withAerialPerspective;
         this._fogUniforms.fogType = fogType;
         this._fogUniforms.additive = additive;
@@ -1005,6 +980,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         bindGroup.setValue('fog', this._fogUniforms);
         bindGroup.setTexture(UNIFORM_NAME_AERIALPERSPECTIVE_LUT, aerialPerspectiveLUT);
         bindGroup.setTexture(UNIFORM_NAME_SKYDISTANTLIGHT_LUT, skyDistantLightLUT);
+        bindGroup.setTexture(UNIFORM_NAME_FOG_SKYLIGHT_CUBEMAP, skyLightCubemap);
     }
     /**
    * @internal
@@ -1018,6 +994,10 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    * 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) {
+        // The voxelize pass writes the global illumination's caches, kept at a fixed exposure
+        if (ctx.renderPass?.type === RENDER_PASS_TYPE_VOXELIZE) {
+            return getGICacheExposure(ctx.scene.lightingMode);
+        }
         return ctx.scene.lightingMode === 'physical' ? ctx.camera.exposure : 1;
     }
     /**
@@ -1065,24 +1045,29 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         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) {
+    /** @internal */ static setLightUniforms(bindGroup, ctx, clusteredLight) {
         const envLightStrength = this.getEnvLightLuminance(ctx);
+        const lightIndexTexture = clusteredLight.lightIndexTexture;
         bindGroup.setValue('light', {
             sunDir: ctx.sunLight ? ctx.sunLight.directionAndCutoff.xyz().scaleBy(-1) : this.defaultSunDir,
-            clusterParams: clusterParams,
-            countParams: countParams,
+            clusterParams: clusteredLight.clusterParam,
+            countParams: clusteredLight.countParam,
+            globalLights: clusteredLight.globalLights,
             envLightStrength,
             envLightSpecularStrength: ctx.env.light.specularStrength ?? 1,
-            lightIndexTexSize: new Int32Array([
-                lightIndexTexture.width,
-                lightIndexTexture.height
-            ]),
+            lightIndexTexSize: clusteredLight.lightIndexTexSize,
+            clusterOrtho: clusteredLight.orthographic ? 1 : 0,
             ...ctx.screenSpaceShadowMask ? {
-                numShadowLights: ctx.clusteredLight?.numShadowLights ?? 0
+                numShadowLights: clusteredLight.numShadowLights
             } : {}
         });
-        bindGroup.setBuffer(UNIFORM_NAME_LIGHT_BUFFER, lightBuffer);
-        bindGroup.setTexture(UNIFORM_NAME_LIGHT_INDEX_TEXTURE, lightIndexTexture);
+        bindGroup.setBuffer(UNIFORM_NAME_LIGHT_BUFFER, clusteredLight.lightBuffer);
+        if (this.usesClusterLightLists()) {
+            bindGroup.setBuffer(UNIFORM_NAME_CLUSTER_GRID, clusteredLight.clusterGridBuffer);
+            bindGroup.setBuffer(UNIFORM_NAME_CLUSTER_LIGHT_LIST, clusteredLight.lightListBuffer);
+        } else {
+            bindGroup.setTexture(UNIFORM_NAME_LIGHT_INDEX_TEXTURE, lightIndexTexture);
+        }
         if (ctx.screenSpaceShadowMask) {
             // The mask array is declared for the clustered light pass whenever the flag is
             // on (keyed into the global bind group hash). When there are no shadow lights
@@ -1090,11 +1075,396 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             // be bound: fall back to a 1x1 dummy.
             bindGroup.setTexture(UNIFORM_NAME_SHADOW_MASK, ctx.shadowMaskTexture ?? this.getDummyShadowMask(ctx.device), fetchSampler('clamp_nearest'));
         }
+        if (ctx.transmissionThickness) {
+            // Falls back to a white dummy, not the shadow mask's zero one: 0 encodes
+            // maximum optical depth here, which would read as full transmission.
+            bindGroup.setTexture(UNIFORM_NAME_TRANSMISSION_THICKNESS, ctx.transmissionThicknessTexture ?? this.getDummyTransmissionThickness(ctx.device), fetchSampler('clamp_nearest'));
+        }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
+        if (this.usesWaterCaustics(ctx)) {
+            this.setWaterCausticUniforms(bindGroup, ctx);
+        }
         if (ctx.drawEnvLight) {
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
         }
     }
+    /**
+   * Whether the pass being built modulates its light with the water caustic map.
+   *
+   * True for every light pass of a frame that produced a map; which light the
+   * caustics actually attach to is decided per-fragment by
+   * {@link ShaderHelper.calculateWaterCaustic}. Both the shader variant hash and
+   * the global bind group hash fold this in, so a program that declares the
+   * caustic uniforms is always paired with a bind group that supplies them.
+   *
+   * Deliberately a function of the draw context alone, with no material input.
+   * The caustic uniforms sit in the global bind group, whose layout is built
+   * once per {@link DrawContext.renderPassHash} and shared by every material in
+   * the pass, so the declarations have to be uniform across the pass. A material
+   * that must not receive caustics - water itself - opts out of the sampling
+   * instead, through `receivesWaterCaustics()`; the uniforms stay declared and
+   * simply go unread.
+   *
+   * @param ctx - Current draw context.
+   * @returns True when the caustic uniforms take part in this pass.
+   * @internal
+   */ /**
+   * The scene's signed distance field as light-pass materials see it, or null
+   * when it is off or cannot be built (WebGL2). Part of the light pass's global
+   * bind group and shader variant hashes.
+   * @internal
+   */ static getSceneSDF(ctx) {
+        if (ctx.renderPass?.type !== RENDER_PASS_TYPE_LIGHT || !ctx.scene?.sdf.enabled) {
+            return null;
+        }
+        return ctx.scene.sdf.global;
+    }
+    /**
+   * Declares the scene signed distance field in a material's bind group, when
+   * the scene has one for this draw ({@link ShaderHelper.getSceneSDF}).
+   * Opt-in per material, so the textures it binds only count against the
+   * shaders that read them. Bind it with {@link ShaderHelper.applySceneSDF}.
+   *
+   * @returns Whether it was declared; without it, fall back to something else.
+   */ static declareSceneSDF(scope, ctx, group) {
+        const sdf = this.getSceneSDF(ctx);
+        if (!sdf) {
+            return false;
+        }
+        declareGlobalSDFUniforms(scope, group, sdf.levels);
+        declareDynamicSDFUniforms(scope, group);
+        sceneSDFLevels.set(scope.$builder, sdf.levels);
+        return true;
+    }
+    /**
+   * Binds what {@link ShaderHelper.declareSceneSDF} declared. The values change
+   * every frame (the clipmap follows the camera, dynamic meshes move), so call
+   * it from `applyUniforms` on every draw, not from `applyUniformValues`, which
+   * only runs when the material itself changed.
+   */ static applySceneSDF(bindGroup, ctx) {
+        this.getSceneSDF(ctx)?.applyBindGroup(bindGroup);
+    }
+    /** Whether {@link ShaderHelper.declareSceneSDF} declared the field in this program. */ static hasSceneSDF(scope) {
+        return !!scope[GLOBAL_SDF_TEXTURE];
+    }
+    /**
+   * Signed distance in world units from a world position to the scene's
+   * geometry: static meshes and terrain from the global clipmap, merged with
+   * the nearest dynamic meshes at their current transforms. Negative inside.
+   * Only valid when {@link ShaderHelper.hasSceneSDF} is true.
+   *
+   * Near surfaces the value is accurate to a fraction of the finest voxel
+   * (0.25 m by default); farther away it is a lower bound clamped to a few
+   * voxels of the level covering the point, safe for sphere tracing.
+   */ static sampleSceneSDF(scope, worldPos) {
+        const levels = sceneSDFLevels.get(scope.$builder);
+        if (!levels) {
+            throw new Error('ShaderHelper.sampleSceneSDF(): the scene SDF is not bound in this program');
+        }
+        return sampleSceneSDF(scope, worldPos, levels);
+    }
+    static usesWaterCaustics(ctx) {
+        return !!ctx.waterCaustics && !!ctx.waterCausticLight && ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT;
+    }
+    /**
+   * Declares the global uniforms {@link ShaderHelper.calculateWaterCaustic} reads.
+   *
+   * Split out of the global uniform setup so a test can build a program that
+   * exercises the sampling code without standing up a whole light pass.
+   *
+   * @param pb - Program builder whose global scope receives the uniforms.
+   * @internal
+   */ /**
+   * Warps a linear caustic-map coordinate so texels concentrate near the centre.
+   *
+   * The map covers a fixed footprint, so its world texel size is the range
+   * divided by the resolution and a range large enough to light the scene is
+   * already too coarse to resolve a caustic cell. This trades the edge of the
+   * map, which is far from the camera, for the middle, which is not:
+   *
+   * ```
+   * warp(u)   = u (1 + k) / (1 + k |u|)
+   * unwarp(w) = w / ((1 + k) - k |w|)
+   * ```
+   *
+   * Texel density is `1 + k` times uniform at the centre and `1 / (1 + k)` times
+   * it at the border, and `k = 0` is exactly the identity, so the pass can apply
+   * this unconditionally. Both ends of `[-1, 1]` are fixed points, which is what
+   * lets the warp sit inside the existing parameterisation without moving the
+   * footprint the receiver gates on. The first derivative is continuous at the
+   * centre; the second flips sign there, which is not visible in a pattern this
+   * noisy.
+   *
+   * Applied per axis rather than radially: the photon grid, the map and the blur
+   * are all axis-aligned, so a separable warp keeps photon `(i,j)` on texel
+   * `(i,j)` for calm water and leaves the map's normalisation to 1.0 intact.
+   *
+   * @param scope - Current shader scope.
+   * @param ndc - Linear map coordinate in `[-1, 1]`.
+   * @param strength - Warp strength `k`; 0 is the identity.
+   * @returns The warped coordinate, also in `[-1, 1]`.
+   * @internal
+   */ static warpCausticNDC(scope, ndc, strength) {
+        const pb = scope.$builder;
+        const funcName = 'Z_warpCausticNDC';
+        pb.func(funcName, [
+            pb.vec2('ndc'),
+            pb.float('k')
+        ], function() {
+            this.$return(pb.div(pb.mul(this.ndc, pb.add(this.k, 1)), pb.add(pb.vec2(1), pb.mul(pb.abs(this.ndc), this.k))));
+        });
+        return pb.getGlobalScope()[funcName](ndc, strength);
+    }
+    /**
+   * Inverse of {@link ShaderHelper.warpCausticNDC}.
+   *
+   * The denominator is `1` at the border and `1 + k` at the centre, so it stays
+   * positive for any input the passes feed it - all of which come from `[-1, 1]`.
+   *
+   * @param scope - Current shader scope.
+   * @param warped - Warped map coordinate in `[-1, 1]`.
+   * @param strength - Warp strength `k`; 0 is the identity.
+   * @returns The linear coordinate the warp came from.
+   * @internal
+   */ static unwarpCausticNDC(scope, warped, strength) {
+        const pb = scope.$builder;
+        const funcName = 'Z_unwarpCausticNDC';
+        pb.func(funcName, [
+            pb.vec2('warped'),
+            pb.float('k')
+        ], function() {
+            this.$return(pb.div(this.warped, pb.sub(pb.vec2(pb.add(this.k, 1)), pb.mul(pb.abs(this.warped), this.k))));
+        });
+        return pb.getGlobalScope()[funcName](warped, strength);
+    }
+    /** @internal */ static declareWaterCausticUniforms(pb) {
+        const scope = pb.getGlobalScope();
+        const causticStruct = pb.defineStruct([
+            pb.vec4('frameX'),
+            pb.vec4('frameY'),
+            pb.vec4('center'),
+            pb.vec4('lightDir'),
+            pb.vec4('params'),
+            pb.vec4('extinction'),
+            // Per water body, because the slice is shared but the water is not: each
+            // has its own surface height, footprint and medium, and none of the three
+            // means anything until a receiver has resolved which water is above it.
+            pb.int('waterCount'),
+            pb.vec4[MAX_CAUSTIC_WATERS]('waterRegions'),
+            // (sigma_t.xyz, surface height)
+            pb.vec4[MAX_CAUSTIC_WATERS]('waterMedia')
+        ]);
+        scope[UNIFORM_NAME_CAUSTIC_PARAMS] = causticStruct().uniform(0);
+        // The map is single mip and read bilinearly; clamping keeps receivers
+        // outside the covered area reading the border rather than wrapping.
+        scope[UNIFORM_NAME_CAUSTIC_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+        // Displaced surface height per water slot, on the same slice as the map.
+        // Read with the map's uv, so it shares the map's sampling.
+        scope[UNIFORM_NAME_CAUSTIC_HEIGHT_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+    }
+    /**
+   * Attenuation the water caustics apply to one light at a world position.
+   *
+   * Returns the product of two effects: the caustic pattern focused by the waves,
+   * and the Beer-Lambert transmittance of the water column the light travelled
+   * through to reach the point. The result is 1 for any light that is not the
+   * caustic light, above the surface, and outside the water region, so the caller
+   * can multiply unconditionally.
+   *
+   * The caustic light is identified at runtime by comparing directions rather
+   * than by which pass is running. Shadow-casting lights reach the opaque queue
+   * through the clustered path when the screen-space shadow mask is on (the
+   * default) and through a per-light additive pass when it is off; only a runtime
+   * test covers both. Two directional lights pointing the same way would both
+   * pick up the caustics, but they are physically the same light.
+   *
+   * @param scope - Current shader scope.
+   * @param worldPos - World position of the shaded fragment.
+   * @param lightType - The light's type constant.
+   * @param lightDirection - Direction the light travels, i.e. `directionAndCutoff.xyz`.
+   * @param ctx - Current draw context.
+   * @returns A `vec3` multiplier, or null when this pass has no caustics.
+   */ static calculateWaterCaustic(scope, worldPos, lightType, lightDirection, ctx) {
+        if (!this.usesWaterCaustics(ctx)) {
+            return null;
+        }
+        return this.sampleWaterCaustic(scope, worldPos, lightType, lightDirection);
+    }
+    /**
+   * {@link ShaderHelper.calculateWaterCaustic} without the pass gate.
+   *
+   * The gate asks whether the *light pass* has caustics, which is the right
+   * question for a material and the wrong one for a standalone full-screen pass
+   * that declared the same uniforms itself. Such a pass has already decided it
+   * has a map; this is the sampling half on its own.
+   *
+   * @param scope - Current shader scope.
+   * @param worldPos - World position of the shaded fragment.
+   * @param lightType - The light's type constant.
+   * @param lightDirection - Direction the light travels, i.e. `directionAndCutoff.xyz`.
+   * @param defocus - Whether to fade the pattern's contrast by how far the point
+   * is from the map's focal depth. True for a receiver surface, which is what
+   * that fade describes. False for a point inside the water column: see the
+   * comment on the term itself.
+   * @returns A `vec3` multiplier.
+   * @internal
+   */ static sampleWaterCaustic(scope, worldPos, lightType, lightDirection, defocus = true) {
+        const pb = scope.$builder;
+        const funcName = defocus ? 'Z_calculateWaterCaustic' : 'Z_calculateWaterCausticVolume';
+        pb.func(funcName, [
+            pb.vec3('worldPos'),
+            pb.int('lightType'),
+            pb.vec3('lightDirection')
+        ], function() {
+            this.$l.cu = this[UNIFORM_NAME_CAUSTIC_PARAMS];
+            // Only the one light the map was built for casts caustics.
+            this.$if(pb.or(pb.notEqual(this.lightType, LIGHT_TYPE_DIRECTIONAL), pb.lessThan(pb.dot(this.lightDirection, this.cu.lightDir.xyz), 0.999)), function() {
+                this.$return(pb.vec3(1));
+            });
+            // Project into the map: frameX/frameY are orthonormal and perpendicular to
+            // the light, so the same two dot products the splat pass used invert it.
+            this.$l.rel = pb.sub(this.worldPos, this.cu.center.xyz);
+            // Per-axis inverse extents: the slice is fitted to the water, so it is
+            // only square in texels, not in meters.
+            this.$l.mapNDC = pb.mul(pb.vec2(pb.dot(this.rel, this.cu.frameX.xyz), pb.dot(this.rel, this.cu.frameY.xyz)), pb.vec2(this.cu.frameX.w, this.cu.frameY.w));
+            // Texels are concentrated towards the middle of the map, so the lookup
+            // goes through the same warp the splat laid the photons out under.
+            this.$l.warpedNDC = ShaderHelper.warpCausticNDC(this, this.mapNDC, this.cu.extinction.w);
+            this.$l.uv = pb.add(pb.mul(this.warpedNDC, 0.5), pb.vec2(0.5));
+            // The displaced surface height of each water slot on this fragment's own
+            // sun ray, biased by CAUSTIC_HEIGHT_BIAS. The height map rasterises the
+            // displaced surface into the same light-space slice as the pattern, so
+            // the texel under this uv holds the surface the ray through this fragment
+            // passed through - no entry point has to be estimated. Beyond the map the
+            // sampler would repeat its border, which is some other ray's wave; the
+            // surface is taken as flat there.
+            this.$l.insideMap = pb.all(pb.lessThanEqual(pb.abs(this.mapNDC), pb.vec2(1)));
+            // How far this fragment is towards the map border, and how much the map is
+            // therefore trusted. Hoisted above the water loop because the wave height
+            // is faded by it too, not just the pattern.
+            //
+            // Measured on the linear coordinate, not the warped one. The warp fixes
+            // both ends of [-1, 1], so the border is in the same world place either
+            // way, but the band between them is not: warping it would make its world
+            // width depend on the warp strength, and the CPU sized it in meters.
+            //
+            // Distance is measured under an L4 norm rather than per-axis. A per-axis
+            // fade is a rectangle in light space, and the sun tilts that rectangle, so
+            // its border lands on the sea bed as straight lines - which the eye picks
+            // out of a caustic pattern however wide the gradient is. An L2 circle has
+            // no straight part anywhere but discards the 21% of the map outside its
+            // inscribed disc; L4 gives up 7% instead and still curves everywhere.
+            this.$l.ndcSq = pb.mul(this.mapNDC, this.mapNDC);
+            this.$l.edgeDist = pb.sqrt(pb.sqrt(pb.dot(this.ndcSq, this.ndcSq)));
+            this.$l.edge = pb.sub(1, pb.smoothStep(this.cu.params.w, 1, this.edgeDist));
+            this.$l.waveHeights = pb.textureSampleLevel(this[UNIFORM_NAME_CAUSTIC_HEIGHT_MAP], this.uv, 0);
+            // Find the water above this point. Several can qualify - a pool inside a
+            // lake, water on terraces - and the one that matters is the lowest of
+            // them, because that is the last surface the sun crossed on its way here.
+            this.$l.depth = pb.float(-1);
+            this.$l.medium = pb.vec3(0);
+            this.$for(pb.int('i'), 0, MAX_CAUSTIC_WATERS, function() {
+                this.$if(pb.greaterThanEqual(this.i, this.cu.waterCount), function() {
+                    this.$break();
+                });
+                this.$l.slotMedium = this.cu.waterMedia.at(this.i);
+                // Where the sun ray that lights this point crossed that water's rest
+                // plane, for the footprint test. The splat pass clips photons by that
+                // same crossing, so the receiver must ask the same question: a point
+                // under the footprint that the sun reaches from outside it saw no water
+                // at all, and a point beyond the footprint that the sun reaches through
+                // it did. Testing the point's own xz gets both wrong by the offset
+                // depth / tan(elevation). Only the footprint is decided here; the depth
+                // itself comes from the height map, which needs no crossing point.
+                this.$l.slotFlat = pb.sub(this.slotMedium.w, this.worldPos.y);
+                this.$l.slotPath = pb.mul(this.slotFlat, this.cu.lightDir.w);
+                this.$l.slotEntry = pb.sub(this.worldPos.xz, pb.mul(this.cu.lightDir.xz, this.slotPath));
+                this.$l.slotRegion = this.cu.waterRegions.at(this.i);
+                this.$if(pb.and(pb.all(pb.greaterThanEqual(this.slotEntry, this.slotRegion.xy)), pb.all(pb.lessThanEqual(this.slotEntry, this.slotRegion.zw))), function() {
+                    // Depth under the *displaced* surface on this ray, which is what
+                    // the splat refracted the photons through. Gating on the rest plane
+                    // instead cut the caustics off at a flat line across any receiver
+                    // that pokes above it under a crest. Slot i lives in channel i.
+                    this.$l.slotMask = pb.vec4(pb.float(pb.equal(this.i, 0)), pb.float(pb.equal(this.i, 1)), pb.float(pb.equal(this.i, 2)), pb.float(pb.equal(this.i, 3)));
+                    this.$l.slotSample = pb.dot(this.waveHeights, this.slotMask);
+                    // A cleared texel inside the map means this ray never meets that
+                    // body's surface - it crosses the rest plane beyond the footprint,
+                    // or the surface is on the far side of the receiver - and the
+                    // receiver is dry as far as this body is concerned. Outside the map
+                    // nothing is known and the surface is taken as flat.
+                    this.$l.slotCovered = pb.or(pb.not(this.insideMap), pb.greaterThan(this.slotSample, 0.5));
+                    this.$if(this.slotCovered, function() {
+                        // Faded into the rest plane over the same band the pattern fades
+                        // on, rather than switched off at the border. Beyond the map the
+                        // surface is taken as flat, and exp(-sigma * depth) is convex, so
+                        // a hard switch makes the wavy side systematically brighter than
+                        // the flat side - E[exp(-sigma*w)] > 1 - and the step lands as a
+                        // mean brightness seam that grows with both the swell and the
+                        // turbidity. Ramping the wave to zero puts the two sides on the
+                        // same value at the border.
+                        this.$l.slotWave = pb.mul(pb.sub(this.slotSample, CAUSTIC_HEIGHT_BIAS), pb.float(this.insideMap), this.edge);
+                        this.$l.slotDepth = pb.sub(pb.add(this.slotMedium.w, this.slotWave), this.worldPos.y);
+                        this.$if(pb.greaterThan(this.slotDepth, 0), function() {
+                            this.$if(pb.or(pb.lessThan(this.depth, 0), pb.lessThan(this.slotDepth, this.depth)), function() {
+                                this.depth = this.slotDepth;
+                                this.medium = this.slotMedium.xyz;
+                            });
+                        });
+                    });
+                });
+            });
+            this.$if(pb.lessThanEqual(this.depth, 0), function() {
+                this.$return(pb.vec3(1));
+            });
+            this.$l.pathLength = pb.mul(this.depth, this.cu.lightDir.w);
+            this.$l.transmittance = pb.exp(pb.neg(pb.mul(this.medium, this.pathLength)));
+            this.$l.pattern = pb.textureSampleLevel(this[UNIFORM_NAME_CAUSTIC_MAP], this.uv, 0).x;
+            if (defocus) {
+                // Receivers away from the focal plane see a defocused, lower-contrast
+                // pattern rather than a displaced one.
+                this.$l.defocus = pb.div(1, pb.add(1, pb.mul(pb.abs(pb.sub(this.depth, this.cu.params.y)), this.cu.params.z)));
+            } else {
+                // A point inside the water column is not a receiver, and has no depth of
+                // its own to be out of focus at - the volumetric march visits every
+                // depth along the ray. Charging it the receiver's fade makes the light
+                // shafts fade according to where the *sea bed* was told to be sharpest:
+                // the open-ocean preset focuses the map at 26m for its bed, which at the
+                // default defocus leaves a point 2m down at 26% contrast, and the shafts
+                // dissolve into grain. The shafts instead take the pattern as the map
+                // holds it and fade with the edge and the transmittance like everything
+                // else in the column.
+                this.$l.defocus = pb.float(1);
+            }
+            // None in water shallower than the minimum depth, faded in across it:
+            // where the water thins out on a beach the surface is too coarse to
+            // say where the water ends, and the pattern there would come from
+            // photons that never reached it
+            this.$l.minDepth = this.cu.extinction.x;
+            this.$l.shallow = pb.smoothStep(pb.mul(this.minDepth, 0.5), pb.add(pb.mul(this.minDepth, 1.5), 1e-4), this.depth);
+            this.$l.weight = pb.mul(this.cu.params.x, this.defocus, this.edge, this.shallow);
+            this.$l.caustic = pb.add(1, pb.mul(pb.sub(this.pattern, 1), this.weight));
+            // Soften the waterline so the transmittance does not switch on abruptly.
+            this.$l.submerged = pb.smoothStep(0, 0.05, this.depth);
+            this.$return(pb.mix(pb.vec3(1), pb.mul(pb.vec3(this.caustic), this.transmittance), this.submerged));
+        });
+        return pb.getGlobalScope()[funcName](worldPos, lightType, lightDirection);
+    }
+    /** @internal */ static setWaterCausticUniforms(bindGroup, ctx) {
+        const uniforms = ctx.waterCausticUniforms;
+        bindGroup.setValue(UNIFORM_NAME_CAUSTIC_PARAMS, {
+            frameX: uniforms.frameX,
+            frameY: uniforms.frameY,
+            center: uniforms.center,
+            lightDir: uniforms.lightDir,
+            params: uniforms.params,
+            extinction: uniforms.extinction,
+            waterCount: uniforms.waterCount,
+            waterRegions: uniforms.waterRegions,
+            waterMedia: uniforms.waterMedia
+        });
+        bindGroup.setTexture(UNIFORM_NAME_CAUSTIC_MAP, ctx.waterCausticTexture, fetchSampler('clamp_linear_nomip'));
+        bindGroup.setTexture(UNIFORM_NAME_CAUSTIC_HEIGHT_MAP, ctx.waterCausticHeightTexture, fetchSampler('clamp_linear_nomip'));
+    }
     /** @internal */ static setLightUniformsShadow(bindGroup, ctx, light) {
         const shadowMapParams = ctx.shadowMapInfo.get(light);
         this._lightUniformShadow.sunDir = ctx.sunLight ? ctx.sunLight.directionAndCutoff.xyz().scaleBy(-1) : this.defaultSunDir;
@@ -1114,6 +1484,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         this._lightUniformShadow.envLightSpecularStrength = ctx.env?.light.specularStrength ?? 1;
         bindGroup.setValue('light', this._lightUniformShadow);
         bindGroup.setTexture(UNIFORM_NAME_SHADOW_MAP, shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
+        if (this.usesWaterCaustics(ctx)) {
+            this.setWaterCausticUniforms(bindGroup, ctx);
+        }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
         if (ctx.drawEnvLight) {
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
@@ -1235,6 +1608,51 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope.camera.elapsedTime;
     }
     /**
+   * Declares the one camera field {@link ShaderHelper.getElapsedTime} reads.
+   *
+   * Wave generators animate off `camera.elapsedTime`, which the light and depth
+   * passes provide as part of the full camera struct. A standalone program that
+   * drives a wave generator - the caustics splat pass - has no such struct, so it
+   * declares that single field under the same name. Any generator that starts
+   * reading a second camera field will need it added here.
+   *
+   * The three padding floats round the struct up to 16 bytes. std140 aligns a
+   * struct to a vec4 boundary, so a lone float leaves the GLSL block larger than
+   * the buffer the engine sizes from the struct's own members - WebGL2 then
+   * rejects every draw with "uniform buffer that is too small" and rasterises
+   * nothing, while WebGPU is unaffected.
+   *
+   * @param scope - Global scope of the standalone program.
+   * @param uniformGroup - Bind group the uniform belongs to.
+   * @internal
+   */ static declareStandaloneCameraTime(scope, uniformGroup) {
+        const pb = scope.$builder;
+        scope.camera = pb.defineStruct([
+            pb.float('elapsedTime'),
+            pb.float('_pad0'),
+            pb.float('_pad1'),
+            pb.float('_pad2')
+        ])().uniform(uniformGroup);
+    }
+    /**
+   * Uploads the value declared by {@link ShaderHelper.declareStandaloneCameraTime}.
+   *
+   * Must be the same clock the light pass uses, or a wave generator's caustics
+   * would animate out of step with the surface they are refracted through.
+   *
+   * @param bindGroup - Bind group of the standalone program.
+   * @param ctx - Current draw context; the current device when omitted, for
+   *   a program run outside drawing.
+   * @internal
+   */ static setStandaloneCameraTime(bindGroup, ctx) {
+        bindGroup.setValue('camera', {
+            elapsedTime: (ctx?.device ?? getDevice()).frameInfo.elapsedOverall * 0.001,
+            _pad0: 0,
+            _pad1: 0,
+            _pad2: 0
+        });
+    }
+    /**
    * Gets the elapsed time since last frame in seconds
    * @param scope - Current shader scope
    * @returns The elapsed time since last frame in seconds
@@ -1297,6 +1715,20 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope.light.countParams;
     }
     /**
+   * Buffer indices of the clustered lights every fragment shades regardless of its
+   * cluster, zero-terminated.
+   * @internal
+   */ static getGlobalLights(scope) {
+        return scope.light.globalLights;
+    }
+    /**
+   * Nonzero when the clusters were sliced for an orthographic camera: depth slices
+   * are then linear in view depth rather than exponential.
+   * @internal
+   */ static getClusterOrthographic(scope) {
+        return scope.light.clusterOrtho;
+    }
+    /**
    * 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.
@@ -1337,10 +1769,65 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return tex;
     }
+    /**
+   * Lazily-created 1x1x1 rgba8unorm array texture used as the transmission
+   * thickness binding fallback.
+   *
+   * @remarks
+   * Filled with 1, not left at the zero-initialised default. The thickness
+   * channel encodes `1 - opticalDepth / 5`, so 0 is *maximum* optical depth —
+   * the worst possible value to fall back to, and the opposite of what the real
+   * pass clears its unused channels to. {@link ShaderHelper.getDummyShadowMask}
+   * gets away with zeroes because 0 reads as "fully shadowed" there.
+   *
+   * On the default pipeline this is never sampled: `ctx.transmissionThickness`
+   * and the thickness module's `enabled` are computed from the same condition.
+   * A custom `camera.renderPipeline` that omits the module can break that tie,
+   * and this fallback is what keeps that from turning into full-strength
+   * transmission across the whole screen.
+   * @internal
+   */ static getDummyTransmissionThickness(device) {
+        let tex = this._dummyTransmissionThickness;
+        if (!tex || tex.disposed) {
+            tex = device.createTexture2DArray('rgba8unorm', 1, 1, 1, {
+                mipmapping: false
+            });
+            tex.name = 'DummyTransmissionThickness';
+            tex.update(new Uint8Array([
+                255,
+                255,
+                255,
+                255
+            ]), 0, 0, 0, 1, 1, 1);
+            this._dummyTransmissionThickness = tex;
+        }
+        return tex;
+    }
     /** @internal */ static getClusteredLightIndexTexture(scope) {
         return scope[UNIFORM_NAME_LIGHT_INDEX_TEXTURE];
     }
     /**
+   * Whether clusters hold variable-length light lists in storage buffers (WebGPU),
+   * rather than 16 byte-sized slots in a texture.
+   * @internal
+   */ static usesClusterLightLists() {
+        return getDevice().type === 'webgpu';
+    }
+    /**
+   * Per cluster, the offset of its light list and the number of lights in it, two
+   * uints each. Only on {@link ShaderHelper.usesClusterLightLists}.
+   * @internal
+   */ static getClusterGrid(scope) {
+        return scope[UNIFORM_NAME_CLUSTER_GRID];
+    }
+    /**
+   * Light buffer indices of every cluster's lights, one list after another. Only on
+   * {@link ShaderHelper.usesClusterLightLists}.
+   * @internal
+   */ static getClusterLightList(scope) {
+        return scope[UNIFORM_NAME_CLUSTER_LIGHT_LIST];
+    }
+    /**
    * Clustered shadow factor for a light, in `[0,1]` (1 = fully lit).
    *
    * - Lights whose clustered buffer index is greater than `numShadowLights` are not
@@ -1383,6 +1870,30 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return pb.getGlobalScope()[funcName](lightIndex);
     }
     /**
+   * Encoded light-space thickness for a light.
+   *
+   * @internal
+   */ static sampleTransmissionThickness(scope, lightIndex) {
+        const pb = scope.$builder;
+        const that = this;
+        const funcName = 'Z_sampleTransmissionThickness';
+        pb.func(funcName, [
+            pb.int('lightIndex')
+        ], function() {
+            this.$if(pb.greaterThan(this.lightIndex, that.getNumShadowLights(this)), function() {
+                this.$return(pb.float(1));
+            });
+            this.$l.ordinal = pb.sub(this.lightIndex, 1);
+            this.$l.layer = pb.div(this.ordinal, 4);
+            this.$l.channel = pb.sub(this.ordinal, pb.mul(this.layer, 4));
+            this.$l.uv = pb.div(pb.vec2(this.$builtins.fragCoord.xy), that.getRenderSize(this));
+            this.$l.texel = pb.textureArraySampleLevel(this[UNIFORM_NAME_TRANSMISSION_THICKNESS], this.uv, this.layer, 0);
+            this.$l.selector = pb.vec4(pb.float(pb.equal(this.channel, 0)), pb.float(pb.equal(this.channel, 1)), pb.float(pb.equal(this.channel, 2)), pb.float(pb.equal(this.channel, 3)));
+            this.$return(pb.dot(this.texel, this.selector));
+        });
+        return pb.getGlobalScope()[funcName](lightIndex);
+    }
+    /**
    * Gets the uniform variable that contains atmosphere parameters
    * @param scope - Current shader scope
    * @returns The atmosphere parameters
@@ -1505,16 +2016,21 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
     }
     /** @internal */ static getLightPositionAndRange(scope, lightIndex) {
-        return scope[UNIFORM_NAME_LIGHT_BUFFER].at(scope.$builder.mul(lightIndex, 4));
+        return this.getLightVector(scope, lightIndex, 0);
     }
     /** @internal */ static getLightDirectionAndCutoff(scope, lightIndex) {
-        return scope[UNIFORM_NAME_LIGHT_BUFFER].at(scope.$builder.add(scope.$builder.mul(lightIndex, 4), 1));
+        return this.getLightVector(scope, lightIndex, 1);
     }
     /** @internal */ static getLightColorAndIntensity(scope, lightIndex) {
-        return scope[UNIFORM_NAME_LIGHT_BUFFER].at(scope.$builder.add(scope.$builder.mul(lightIndex, 4), 2));
+        return this.getLightVector(scope, lightIndex, 2);
     }
     /** @internal */ static getLightExtra(scope, lightIndex) {
-        return scope[UNIFORM_NAME_LIGHT_BUFFER].at(scope.$builder.add(scope.$builder.mul(lightIndex, 4), 3));
+        return this.getLightVector(scope, lightIndex, 3);
+    }
+    /** Vector `k` of the 4 of a clustered light, read from the light buffer. */ static getLightVector(scope, lightIndex, k) {
+        const pb = scope.$builder;
+        const buffer = scope[UNIFORM_NAME_LIGHT_BUFFER];
+        return buffer.at(pb.add(pb.mul(lightIndex, 4), k));
     }
     /**
    * Sets the clip space position in vertex shader
@@ -1596,6 +2112,36 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return pb.add(worldPos, pb.mul(unitNormal, offset));
     }
     /**
+   * How far a rect light's shadow lookup can be trusted at a receiver, as a
+   * weight for `mix(1, shadow, weight)`.
+   *
+   * @remarks
+   * A rect light's shadow is a cube map rendered from its centre, but its
+   * lighting integrates the whole panel. Where the surface turns away from the
+   * centre the panel's far edge still lights it, while the centre already sees
+   * the receiver occlude itself - so the centre's shadow cuts a hard, texel
+   * stepped terminator through lit surface. The weight fades that lookup out as
+   * the centre sinks to the receiver's horizon.
+   *
+   * The band is a fixed, narrow cosine range rather than one scaled by the
+   * panel's size: the stepped edge only lives where the centre grazes the
+   * surface, and its width is set by shadow bias and texel footprint, not by
+   * the panel. A band as wide as the panel's angular radius also caught flat
+   * receivers - a floor seen low from a large upright panel - and faded their
+   * cast shadows, which have no terminator to hide.
+   *
+   * @param worldNormal - Geometric normal; the terminator follows the surface,
+   * not its normal map.
+   * @param posRange - Light position (xyz).
+   * @internal
+   */ static getRectLightShadowWeight(scope, worldPos, worldNormal, posRange) {
+        const pb = scope.$builder;
+        const toCenter = pb.sub(posRange.xyz, worldPos);
+        const unitNormal = pb.mul(worldNormal, pb.div(1, pb.max(pb.length(worldNormal), 1e-6)));
+        const cosCenter = pb.div(pb.dot(unitNormal, toCenter), pb.max(pb.length(toCenter), 1e-6));
+        return pb.smoothStep(0, 0.01, cosCenter);
+    }
+    /**
    * Calculates shadow of current fragment
    *
    * @param scope - Shader scope
@@ -1623,17 +2169,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 // would self-occlude it before projecting into shadow space. Scaled per
                 // cascade, because each cascade has its own texel world size.
                 this.$l.biasedPos = that.applyShadowNormalOffset(shadowMapParams.lightType, this, this.worldPos, this.worldNormal, this.NoL, that.getShadowCascadeBiasScale(this, this.split));
-                if (ctx.device.type === 'webgl') {
-                    this.$l.shadowVertex = pb.vec4();
-                    this.$for(pb.int('cascade'), 0, 4, function() {
-                        this.$if(pb.equal(this.cascade, this.split), function() {
-                            this.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.cascade);
-                            this.$break();
-                        });
-                    });
-                } else {
-                    this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.split);
-                }
+                this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.split);
                 this.$l.shadow = shadowMapParams.impl.computeShadowCSM(shadowMapParams, this, this.shadowVertex, this.NoL, this.split);
                 this.shadow = pb.clamp(this.shadow, 0, 1);
                 this.$l.shadowDistance = that.getShadowCameraParams(scope).w;
@@ -1648,7 +2184,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 // Normal offset bias - see the cascaded branch above.
                 this.$l.biasedPos = that.applyShadowNormalOffset(shadowMapParams.lightType, this, this.worldPos, this.worldNormal, this.NoL);
                 this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1));
-                this.$l.shadow = shadowMapParams.impl.computeShadow(shadowMapParams, this, this.shadowVertex, this.NoL);
+                this.$l.shadow = shadowMapParams.impl.computeShadow(shadowMapParams, this, this.shadowVertex, this.NoL, this.worldNormal);
                 this.shadow = pb.clamp(this.shadow, 0, 1);
                 this.$l.shadowDistance = that.getShadowCameraParams(scope).w;
                 this.shadow = pb.mix(this.shadow, 1, pb.smoothStep(pb.mul(this.shadowDistance, 0.8), this.shadowDistance, pb.distance(that.getCameraPosition(this), this.worldPos)));
@@ -1659,24 +2195,22 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return pb.getGlobalScope()[funcName](worldPos, worldNormal, NoL);
     }
-    static applyFog(scope, worldPos, color, ctx) {
+    static applyFog(scope, worldPos, color, ctx, premultiplied = true) {
         const pb = scope.$builder;
         const that = this;
         if (ctx.materialFlags & MaterialVaryingFlags.APPLY_FOG) {
-            const funcName = 'Z_applyFog';
+            const funcName = premultiplied ? 'Z_applyFog' : 'Z_applyFogStraight';
             pb.func(funcName, [
                 pb.vec3('worldPos'),
                 pb.vec4('color').inout()
             ], function() {
-                this.$if(pb.notEqual(this.fog.additive, 0), function() {
-                    this.$return();
-                });
                 this.$l.uv = pb.div(pb.vec2(this.$builtins.fragCoord.xy), that.getRenderSize(this));
-                this.$l.fogging = calculateFog(this, this.fog.withAerialPerspective, this.fog.fogType, this.fog.atmosphereParams, this.fog.heightFogParams, this.uv, false, that.getCameraPosition(this).xyz, this.worldPos, this.fog.additive, this[UNIFORM_NAME_AERIALPERSPECTIVE_LUT], this[UNIFORM_NAME_SKYDISTANTLIGHT_LUT]);
-                this.$l.foggingAlpha = pb.sub(1, pb.mul(pb.sub(1, this.fogging.a), this.color.a));
-                this.$l.foggingRGB = pb.mul(this.fogging.rgb, this.color.a);
-                this.color = pb.vec4(pb.add(pb.mul(this.color.rgb, this.foggingAlpha), this.foggingRGB), this.color.a);
-            //this.color = pb.vec4(pb.vec3(pb.mix(this.u0, this.u1, this.factor)), this.color.a);
+                this.$l.fogging = calculateFog(this, this.fog.withAerialPerspective, this.fog.fogType, this.fog.atmosphereParams, this.fog.heightFogParams, this.uv, false, that.getCameraPosition(this).xyz, this.worldPos, this.fog.additive, this[UNIFORM_NAME_AERIALPERSPECTIVE_LUT], this[UNIFORM_NAME_SKYDISTANTLIGHT_LUT], this[UNIFORM_NAME_FOG_SKYLIGHT_CUBEMAP]);
+                // Premultiplied color: attenuate by the fog transmittance and add the in-scattering weighted
+                // by coverage. Additive light passes and additive blending (alpha 0) get attenuation only --
+                // calculateFog already zeroes the in-scattering for the former. Straight (non-premultiplied)
+                // color is scaled by coverage later, so the in-scattering is added unweighted.
+                this.color = pb.vec4(pb.add(pb.mul(this.color.rgb, this.fogging.a), premultiplied ? pb.mul(this.fogging.rgb, this.color.a) : this.fogging.rgb), this.color.a);
             });
             scope[funcName](worldPos, color);
         }
@@ -1809,7 +2343,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    */ static sampleLinearDepth(scope, tex, uv, level) {
         const pb = scope.$builder;
         const depth = pb.textureSampleLevel(tex, uv, level);
-        return pb.getDevice().type === 'webgl' ? decodeNormalizedFloatFromRGBA(scope, depth) : depth.r;
+        return depth.r;
     }
     static samplePositionFromDepth(scope, depthTex, uv, mat, cameraNearFar) {
         const pb = scope.$builder;
@@ -1860,10 +2394,19 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return pb.getGlobalScope()[funcName](outputColor);
     }
-    /** @internal */ static getMaxClusterLights() {
-        return getDevice().type === 'webgl' ? 64 : 255;
+    /**
+   * Capacity of the clustered light buffer, excluding the unused slot 0.
+   *
+   * @remarks
+   * On WebGPU the buffers are storage buffers grown to fit and light indices are 32
+   * bits, so this only bounds the CPU-side work. On WebGL2 the buffer is 4 vec4 per
+   * light in a uniform block, and 255 is the most a byte-sized cluster slot can address.
+   * @internal
+   */ static getMaxClusterLights() {
+        const device = getDevice();
+        return device.type === 'webgpu' ? 65535 : 255;
     }
 }
 
-export { ShaderHelper };
+export { CAUSTIC_HEIGHT_BIAS, MAX_CAUSTIC_WATERS, ShaderHelper };
 //# sourceMappingURL=helper.js.map