@zephyr3d/scene 0.9.25 → 0.9.26

package/dist/material/shader/helper.js

@@ -1,5 +1,5 @@
 import { Vector3, Vector4, Vector2, REVERSE_Z, DEPTH_FARTHEST, DEPTH_REDUCE_CLOSER, DEPTH_REDUCE_FARTHER } from '@zephyr3d/base';
-import { RENDER_PASS_TYPE_DEPTH, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_LIGHT, MaterialVaryingFlags, MORPH_WEIGHTS_VECTOR_COUNT, MORPH_TARGET_POSITION, MORPH_TARGET_NORMAL, MORPH_TARGET_TANGENT, MORPH_ATTRIBUTE_VECTOR_COUNT } from '../../values.js';
+import { 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 { ProgramBuilder } from '@zephyr3d/device';
 import { decodeNormalizedFloatFromRGBA, linearToGamma } from '../../shaders/misc.js';
 import { getSamplerOptions, fetchSampler } from '../../utility/misc.js';
@@ -7,6 +7,7 @@ import { PHYSICAL_BAKE_EXPOSURE } from '../../utility/physical.js';
 import { getDevice } from '../../app/api.js';
 import { getDefaultAtmosphereParams, getAtmosphereParamsStruct } from '../../shaders/atmosphere.js';
 import { getDefaultHeightFogParams, getHeightFogParamsStruct, calculateFog } from '../../shaders/fog.js';
+import { getShadowReceiverNoL, getShadowReceiverBiasFactor } from '../../shadow/receiver_bias.js';
 
 const UNIFORM_NAME_LIGHT_BUFFER = 'Z_UniformLightBuffer';
 const UNIFORM_NAME_LIGHT_INDEX_TEXTURE = 'Z_UniformLightIndexTex';
@@ -32,6 +33,8 @@ 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_INFLUENCE_DATA = 'Z_UniformSkinInfluenceData';
+const UNIFORM_NAME_SKIN_INFLUENCE_INFO = 'Z_UniformSkinInfluenceInfo';
 const UNIFORM_NAME_MORPH_DATA = 'Z_UniformMorphData';
 const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
 /**
@@ -46,6 +49,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static SKIN_MATRIX_NAME = 'Z_SkinMatrix';
     static SKIN_PREV_MATRIX_NAME = 'Z_PrevSkinMatrix';
     static SKIN_BONE_OFFSET = 'Z_boneOffset';
+    static RESOLVED_VERTEX_NORMAL_NAME = 'Z_ResolvedVertexNormal';
     /** @internal */ static _drawableBindGroupLayouts = {};
     /** @internal */ static _lightUniformShadow = {
         sunDir: new Vector3(),
@@ -101,6 +105,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     static getBoneInvBindMatrixUniformName() {
         return UNIFORM_NAME_BONE_INV_BIND_MATRIX;
     }
+    static getSkinInfluenceDataUniformName() {
+        return UNIFORM_NAME_SKIN_INFLUENCE_DATA;
+    }
+    static getSkinInfluenceInfoUniformName() {
+        return UNIFORM_NAME_SKIN_INFLUENCE_INFO;
+    }
     static getMorphDataUniformName() {
         return UNIFORM_NAME_MORPH_DATA;
     }
@@ -183,10 +193,22 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 pb.vec4('directionCutoff'),
                 pb.mat4('viewMatrix'),
                 pb.vec4('depthBias'),
+                // Same slot the lighting pass exposes through getShadowImplParams. A
+                // caster normally has no use for it, but one that encodes something
+                // beyond depth - deep opacity map layers - needs the same parameters the
+                // receiver will decode with.
+                pb.vec4('implParams'),
                 pb.int('lightType')
             ]);
             scope.camera = cameraStruct().uniform(0);
             scope.light = lightStruct().uniform(0);
+            // Lets the shadow implementation add its own caster inputs. Only deep
+            // opacity maps use this, to read the frontmost depth its first pass wrote.
+            const shadowLight = ctx.renderPass.light;
+            const casterParams = shadowLight ? ctx.shadowMapInfo?.get(shadowLight) : null;
+            if (casterParams) {
+                casterParams.impl?.declareCasterUniforms(scope, casterParams);
+            }
         } else if (ctx.renderPass.type === RENDER_PASS_TYPE_DEPTH || ctx.renderPass.type === RENDER_PASS_TYPE_OBJECT_COLOR) {
             scope.camera = cameraStruct().uniform(0);
         } else if (ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT) {
@@ -322,6 +344,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             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')
@@ -354,6 +378,33 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             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]();
@@ -389,7 +440,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                         });
                         this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
                         this.$if(pb.notEqual(this.weight, 0), function() {
-                            this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.index, this.numVertices), this.vertexIndex));
+                            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);
@@ -405,7 +457,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                     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.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.t, this.numVertices), this.vertexIndex));
+                        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);
@@ -417,17 +470,166 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             }
             this.$return(this.value);
         });
-        const pos = 1 + MORPH_WEIGHTS_VECTOR_COUNT + (attrib >> 2);
+        const pos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (attrib >> 2);
         const comp = attrib & 3;
         const offset = scope[this.getMorphInfoUniformName()][pos][comp];
         return scope[funcName](pb.int(offset));
     }
+    /**
+   * Normalize a morphed direction without allowing cancellation between
+   * multiple morph targets to turn a valid base direction into NaN/noise.
+   *
+   * Morph normal/tangent data is additive. When two targets cancel the base
+   * direction, the zero-length result is not a meaningful direction, so the
+   * authored vertex direction is the least surprising fallback.
+   * @internal
+   */ static defineNormalizeMorphedDirection(scope) {
+        const pb = scope.$builder;
+        const funcName = 'Z_normalizeMorphedDirection';
+        pb.func(funcName, [
+            pb.vec3('base'),
+            pb.vec3('delta')
+        ], function() {
+            this.$l.morphed = pb.add(this.base, this.delta);
+            this.$l.lengthSquared = pb.dot(this.morphed, this.morphed);
+            this.$if(pb.greaterThan(this.lengthSquared, 1e-6), function() {
+                this.$return(pb.mul(this.morphed, pb.inverseSqrt(this.lengthSquared)));
+            });
+            this.$l.baseLengthSquared = pb.dot(this.base, this.base);
+            this.$if(pb.greaterThan(this.baseLengthSquared, 1e-6), function() {
+                this.$return(pb.mul(this.base, pb.inverseSqrt(this.baseLengthSquared)));
+            });
+            this.$return(pb.vec3(0, 0, 1));
+        });
+        return funcName;
+    }
+    /**
+   * Mixes morph directions according to the amount of positional deformation
+   * contributed by each active target. This avoids letting a target with a
+   * large authored normal delta dominate a target that actually moves the
+   * surface much farther at the current vertex.
+   *
+   * The additive result remains the fallback for assets without position
+   * morph data, and for vertices whose position deltas are all zero.
+   * @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`);
+        }
+        const that = this;
+        const funcName = 'Z_calculateMorphDirectionByDisplacement';
+        const normalizeName = this.defineNormalizeMorphedDirection(scope);
+        pb.func(funcName, [
+            pb.vec3('base'),
+            pb.int('directionOffset'),
+            pb.int('positionOffset')
+        ], function() {
+            this.$l.vertexIndex = isWebGL1 ? pb.int(scope.$inputs.zFakeVertexID) : 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);
+            this.$l.texHeight = pb.float(this.metaData.y);
+            this.$l.numVertices = this.metaData.z;
+            this.$l.numTargets = this.metaData.w;
+            this.$l.directionDelta = pb.vec3(0);
+            this.$l.weightedDirection = pb.vec3(0);
+            this.$l.weightSum = pb.float(0);
+            const accumulateTarget = (targetScope)=>{
+                targetScope.$if(pb.notEqual(targetScope.weight, 0), function() {
+                    this.$l.targetIndex = pb.int(targetScope['targetIndex']);
+                    this.$l.positionValue = pb.vec3(0);
+                    this.$l.directionValue = pb.vec3(0);
+                    this.$if(pb.greaterThanEqual(targetScope['directionOffset'], 0), function() {
+                        this.$l.pixelIndex = pb.float(pb.add(targetScope['directionOffset'], pb.mul(this.targetIndex, targetScope['numVertices']), targetScope['vertexIndex']));
+                        this.$l.xIndex = pb.mod(this.pixelIndex, targetScope['texWidth']);
+                        this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, targetScope['texWidth']));
+                        this.$l.u = pb.div(pb.add(this.xIndex, 0.5), targetScope['texWidth']);
+                        this.$l.v = pb.div(pb.add(this.yIndex, 0.5), targetScope['texHeight']);
+                        this.directionValue = pb.textureSampleLevel(scope[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0).xyz;
+                    });
+                    this.$if(pb.greaterThanEqual(targetScope['positionOffset'], 0), function() {
+                        this.$l.pixelIndex = pb.float(pb.add(targetScope['positionOffset'], pb.mul(this.targetIndex, targetScope['numVertices']), targetScope['vertexIndex']));
+                        this.$l.xIndex = pb.mod(this.pixelIndex, targetScope['texWidth']);
+                        this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, targetScope['texWidth']));
+                        this.$l.u = pb.div(pb.add(this.xIndex, 0.5), targetScope['texWidth']);
+                        this.$l.v = pb.div(pb.add(this.yIndex, 0.5), targetScope['texHeight']);
+                        this.positionValue = pb.textureSampleLevel(scope[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0).xyz;
+                    });
+                    this.directionDelta = pb.add(this.directionDelta, pb.mul(this.directionValue, targetScope.weight));
+                    this.$l.targetDirection = scope.$g[normalizeName](this.base, pb.mul(this.directionValue, targetScope.weight));
+                    this.$l.displacementWeight = pb.mul(pb.abs(targetScope.weight), pb.sqrt(pb.dot(this.positionValue, this.positionValue)));
+                    this.weightedDirection = pb.add(this.weightedDirection, pb.mul(this.targetDirection, this.displacementWeight));
+                    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.$l.fallback = scope.$g[normalizeName](this.base, this.directionDelta);
+            this.$if(pb.lessThan(this.weightSum, 1e-6), function() {
+                this.$return(this.fallback);
+            });
+            this.$l.weightedLengthSquared = pb.dot(this.weightedDirection, this.weightedDirection);
+            this.$if(pb.greaterThan(this.weightedLengthSquared, 1e-6), function() {
+                this.$return(pb.mul(this.weightedDirection, pb.inverseSqrt(this.weightedLengthSquared)));
+            });
+            this.$return(this.fallback);
+        });
+        const directionPos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (attrib >> 2);
+        const directionComp = attrib & 3;
+        const positionPos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (MORPH_TARGET_POSITION >> 2);
+        const positionComp = MORPH_TARGET_POSITION & 3;
+        const morphInfo = scope[this.getMorphInfoUniformName()];
+        return scope.$g[funcName](base.xyz, pb.int(morphInfo[directionPos][directionComp]), pb.int(morphInfo[positionPos][positionComp]));
+    }
+    /** @internal */ static orthogonalizeMorphedTangent(scope, normal, tangent) {
+        const pb = scope.$builder;
+        const funcName = 'Z_orthogonalizeMorphedTangent';
+        pb.func(funcName, [
+            pb.vec3('normal'),
+            pb.vec3('tangent')
+        ], function() {
+            this.$l.normalLengthSquared = pb.dot(this.normal, this.normal);
+            this.$if(pb.greaterThan(this.normalLengthSquared, 1e-6), function() {
+                this.$l.n = pb.mul(this.normal, pb.inverseSqrt(this.normalLengthSquared));
+                this.$l.projected = pb.sub(this.tangent, pb.mul(this.n, pb.dot(this.n, this.tangent)));
+                this.$l.tangentLengthSquared = pb.dot(this.projected, this.projected);
+                this.$if(pb.greaterThan(this.tangentLengthSquared, 1e-6), function() {
+                    this.$return(pb.mul(this.projected, pb.inverseSqrt(this.tangentLengthSquared)));
+                });
+            });
+            this.$return(this.tangent);
+        });
+        return scope.$g[funcName](normal.xyz, tangent.xyz);
+    }
     /** @internal */ static prepareSkinAnimation(scope) {
         if (!this.hasSkinning(scope)) {
             return;
         }
         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'),
@@ -461,6 +663,33 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$l.m2 = scope.$g[funcNameGetBoneMatrixFromTexture](blendIndices[2], this.boneOffset);
             this.$l.m3 = scope.$g[funcNameGetBoneMatrixFromTexture](blendIndices[3], this.boneOffset);
             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](this.extra.x, this.boneOffset), this.extra.y));
+                    });
+                    this.$if(pb.greaterThan(this.extra.w, 0), function() {
+                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](this.extra.z, this.boneOffset), this.extra.w));
+                    });
+                });
+            });
             this.$return(pb.mul(invBindMatrix, this.m));
         });
         const motionVector = !!this.getUnjitteredViewProjectionMatrix(scope);
@@ -535,6 +764,19 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
     }
     /**
+   * Gets the skinning matrix in the vertex shader, if the mesh being drawn is skinned.
+   *
+   * @remarks
+   * Lets a material apply the same skinning transform to its own uniform-supplied
+   * object-space vectors that {@link ShaderHelper.resolveVertexNormal} applies to
+   * the normal attribute, so such vectors stay attached to the deforming mesh.
+   *
+   * @param scope - Current shader scope, must be vertex stage
+   * @returns The skinning matrix of type mat4, or null when the mesh is not skinned
+   */ static getSkinMatrix(scope) {
+        return scope[this.SKIN_MATRIX_NAME] ?? null;
+    }
+    /**
    * Calculates the normal vector of type vec3 in object space
    *
    * @param scope - Current shader scope
@@ -550,6 +792,10 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         if (!funcScope || !funcScope.$isMain()) {
             throw new Error(`ShaderHelper.resolveVertexNormal(): must be called at entry function`);
         }
+        const useVertexAttrib = !normal;
+        if (useVertexAttrib && scope[this.RESOLVED_VERTEX_NORMAL_NAME]) {
+            return scope[this.RESOLVED_VERTEX_NORMAL_NAME];
+        }
         if (!normal) {
             if (!scope.$getVertexAttrib('normal')) {
                 scope.$inputs.Z_normal = pb.vec3().attrib('normal');
@@ -557,13 +803,17 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             normal = scope.$getVertexAttrib('normal');
         }
         if (this.hasMorphing(scope)) {
-            normal = pb.normalize(pb.add(normal, this.calculateMorphDelta(scope, MORPH_TARGET_NORMAL).xyz));
+            normal = this.calculateMorphDirectionByDisplacement(scope, normal, MORPH_TARGET_NORMAL);
         }
+        let resolvedNormal = normal;
         if (scope[this.SKIN_MATRIX_NAME]) {
-            return pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(normal, 0)).xyz;
-        } else {
-            return normal;
+            resolvedNormal = pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(normal, 0)).xyz;
+        }
+        if (useVertexAttrib) {
+            scope.$l[this.RESOLVED_VERTEX_NORMAL_NAME] = resolvedNormal;
+            resolvedNormal = scope[this.RESOLVED_VERTEX_NORMAL_NAME];
         }
+        return resolvedNormal;
     }
     /**
    * Calculates the tangent vector of type vec3 in object space
@@ -588,13 +838,16 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             tangent = scope.$getVertexAttrib('tangent');
         }
         if (this.hasMorphing(scope)) {
-            tangent = pb.normalize(pb.add(tangent, pb.vec4(this.calculateMorphDelta(scope, MORPH_TARGET_TANGENT).xyz, 0)));
+            tangent = pb.vec4(this.calculateMorphDirectionByDisplacement(scope, tangent.xyz, MORPH_TARGET_TANGENT), tangent.w);
         }
         if (scope[this.SKIN_MATRIX_NAME]) {
-            return pb.vec4(pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(tangent.xyz, 0)).xyz, tangent.w);
-        } else {
-            return tangent;
+            tangent = pb.vec4(pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(tangent.xyz, 0)).xyz, tangent.w);
         }
+        if (this.hasMorphing(scope) && scope.$getVertexAttrib('normal')) {
+            const resolvedNormal = scope[this.RESOLVED_VERTEX_NORMAL_NAME] ?? this.resolveVertexNormal(scope);
+            tangent = pb.vec4(this.orthogonalizeMorphedTangent(scope, resolvedNormal, tangent.xyz), tangent.w);
+        }
+        return tangent;
     }
     /**
    * Gets the uniform variable of type mat4 which holds the world matrix of current object to be drawn
@@ -676,10 +929,12 @@ 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);
+            scope[UNIFORM_NAME_SKIN_INFLUENCE_DATA] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
+            scope[UNIFORM_NAME_SKIN_INFLUENCE_INFO] = pb.vec4().uniform(1);
         }
         if (morphing) {
             scope[UNIFORM_NAME_MORPH_DATA] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
-            scope[UNIFORM_NAME_MORPH_INFO] = pb.vec4[1 + MORPH_WEIGHTS_VECTOR_COUNT + MORPH_ATTRIBUTE_VECTOR_COUNT]().uniformBuffer(1);
+            scope[UNIFORM_NAME_MORPH_INFO] = pb.vec4[1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + MORPH_ATTRIBUTE_VECTOR_COUNT]().uniformBuffer(1);
         }
     }
     /** @internal */ static prepareVertexShaderCommon(pb, ctx) {
@@ -735,8 +990,10 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 directionCutoff: light.directionAndCutoff,
                 viewMatrix: light.viewMatrix,
                 depthBias: shadowMapParams.depthBiasValues[0],
+                implParams: shadowMapParams.impl.getParams(this._lightUniformShadow.implParams),
                 lightType: light.lightType
             });
+            shadowMapParams.impl?.applyCasterUniforms(bindGroup, shadowMapParams);
         }
     }
     /** @internal */ static setFogUniforms(bindGroup, withAerialPerspective, fogType, additive, atmosphereParams, heightFogParams, aerialPerspectiveLUT, skyDistantLightLUT) {
@@ -1291,18 +1548,67 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope[UNIFORM_NAME_SHADOW_MAP];
     }
     /**
+   * Per-cascade scale for both bias terms.
+   *
+   * @remarks
+   * Only `depthBiasValues[0]` is uploaded; every cascade's value is recovered by
+   * multiplying with this ratio. It is derived from the `.x` components, but
+   * since `.x` and the normal offset `.y` are both proportional to the cascade's
+   * texel world size, the same ratio applies to either.
+   * @internal
+   */ static getShadowCascadeBiasScale(scope, split) {
+        const pb = scope.$builder;
+        const splitFlags = pb.vec4(pb.float(pb.equal(split, 0)), pb.float(pb.equal(split, 1)), pb.float(pb.equal(split, 2)), pb.float(pb.equal(split, 3)));
+        return pb.dot(this.getDepthBiasScales(scope), splitFlags);
+    }
+    /**
+   * Moves the receiver along its normal before the shadow lookup.
+   *
+   * @remarks
+   * Grazing-angle self-shadowing cannot be fixed with a depth bias: the depth
+   * spanned by one shadow texel is `texelWorldSize * tan(theta)`, which diverges
+   * as NdotL approaches zero. Offsetting the sample position sideways moves it
+   * out of the offending texel instead, and the required distance is bounded.
+   *
+   * `depthBiasValues.y` carries the world-space distance of one `normalBias`
+   * unit (see `ShadowMapper.calcDepthBiasParams`).
+   * @internal
+   */ static applyShadowNormalOffset(lightType, scope, worldPos, worldNormal, NdotL, cascadeScale) {
+        const pb = scope.$builder;
+        const depthBiasParam = this.getDepthBiasValues(scope);
+        const receiverNoL = getShadowReceiverNoL(scope, NdotL, lightType);
+        // sin(theta): 0 when facing the light, 1 at grazing incidence.
+        const sinTheta = pb.sqrt(pb.clamp(pb.sub(1, pb.mul(receiverNoL, receiverNoL)), 0, 1));
+        let offset = pb.mul(depthBiasParam.y, getShadowReceiverBiasFactor(scope), sinTheta);
+        if (cascadeScale) {
+            offset = pb.mul(offset, cascadeScale);
+        }
+        if (lightType !== LIGHT_TYPE_DIRECTIONAL) {
+            // Perspective shadow cameras: one texel covers more world space further
+            // from the light. depthBiasValues.w is the far/near footprint ratio.
+            const posRange = this.getLightPositionAndRangeForShadow(scope);
+            const linearDepth = pb.clamp(pb.div(pb.distance(worldPos, posRange.xyz), pb.max(posRange.w, 1e-6)), 0, 1);
+            offset = pb.mul(offset, pb.mix(1, depthBiasParam.w, linearDepth));
+        }
+        // Guard against a degenerate interpolated normal rather than normalize()ing
+        // a possibly-zero vector into NaN.
+        const unitNormal = pb.mul(worldNormal, pb.div(1, pb.max(pb.length(worldNormal), 1e-6)));
+        return pb.add(worldPos, pb.mul(unitNormal, offset));
+    }
+    /**
    * Calculates shadow of current fragment
    *
    * @param scope - Shader scope
    * @param NoL - NdotL vector
    * @returns Shadow of current fragment, 1 means no shadow and 0 means full shadowed.
-   */ static calculateShadow(scope, worldPos, NoL, ctx) {
+   */ static calculateShadow(scope, worldPos, worldNormal, NoL, ctx) {
         const pb = scope.$builder;
         const that = this;
         const shadowMapParams = ctx.shadowMapInfo.get(ctx.currentShadowLight);
         const funcName = 'Z_calculateShadow';
         pb.func(funcName, [
             pb.vec3('worldPos'),
+            pb.vec3('worldNormal'),
             pb.float('NoL')
         ], function() {
             if (shadowMapParams.numShadowCascades > 1) {
@@ -1313,18 +1619,21 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 this.$l.comparison = pb.vec4(pb.greaterThan(pb.vec4(this.linearDepth), this.splitDistances));
                 this.$l.cascadeFlags = pb.vec4(pb.float(pb.greaterThan(this.shadowCascades, 0)), pb.float(pb.greaterThan(this.shadowCascades, 1)), pb.float(pb.greaterThan(this.shadowCascades, 2)), pb.float(pb.greaterThan(this.shadowCascades, 3)));
                 this.$l.split = pb.int(pb.dot(this.comparison, this.cascadeFlags));
+                // Normal offset bias: move the receiver out of the shadow texel that
+                // 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.worldPos, 1), this.cascade);
+                            this.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.cascade);
                             this.$break();
                         });
                     });
                 } else {
-                    this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1), this.split);
+                    this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.split);
                 }
-                const shadowMapParams = ctx.shadowMapInfo.get(ctx.currentShadowLight);
                 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;
@@ -1336,8 +1645,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 });
                 this.$return(this.shadow);
             } else {
-                this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1));
-                const shadowMapParams = ctx.shadowMapInfo.get(ctx.currentShadowLight);
+                // 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.shadow = pb.clamp(this.shadow, 0, 1);
                 this.$l.shadowDistance = that.getShadowCameraParams(scope).w;
@@ -1347,7 +1657,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 this.$return(this.shadow);
             }
         });
-        return pb.getGlobalScope()[funcName](worldPos, NoL);
+        return pb.getGlobalScope()[funcName](worldPos, worldNormal, NoL);
     }
     static applyFog(scope, worldPos, color, ctx) {
         const pb = scope.$builder;