@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/material/shader/helper.js

@@ -1,22 +1,29 @@
 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';
 /**
@@ -55,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';
@@ -68,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';
@@ -127,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;
     }
@@ -231,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) {
@@ -248,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'),
@@ -271,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
@@ -283,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
@@ -298,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'));
@@ -378,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`);
         }
@@ -458,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);
@@ -466,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);
@@ -549,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`);
         }
@@ -561,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);
@@ -599,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);
@@ -663,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'),
@@ -672,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));
@@ -679,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);
@@ -700,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() {
@@ -710,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));
                     });
@@ -728,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);
@@ -964,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);
         }
@@ -977,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),
@@ -1026,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;
@@ -1040,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
@@ -1053,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;
     }
     /**
@@ -1100,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
@@ -1125,6 +1075,11 @@ 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);
@@ -1153,7 +1108,62 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    * @param ctx - Current draw context.
    * @returns True when the caustic uniforms take part in this pass.
    * @internal
-   */ static usesWaterCaustics(ctx) {
+   */ /**
+   * 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;
     }
     /**
@@ -1425,7 +1435,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 // else in the column.
                 this.$l.defocus = pb.float(1);
             }
-            this.$l.weight = pb.mul(this.cu.params.x, this.defocus, this.edge);
+            // 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);
@@ -1625,11 +1641,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
    * 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.
+   * @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.frameInfo.elapsedOverall * 0.001,
+            elapsedTime: (ctx?.device ?? getDevice()).frameInfo.elapsedOverall * 0.001,
             _pad0: 0,
             _pad1: 0,
             _pad2: 0
@@ -1698,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.
@@ -1738,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
@@ -1784,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
@@ -1906,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
@@ -1997,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
@@ -2024,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;
@@ -2049,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)));
@@ -2060,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);
         }
@@ -2210,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;
@@ -2261,8 +2394,17 @@ 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;
     }
 }