@zephyr3d/scene 0.9.24 → 0.9.26

package/dist/shadow/shadowmapper.js

@@ -5,8 +5,8 @@ import { ESM } from './esm.js';
 import { VSM } from './vsm.js';
 import { PCFOPT } from './pcf_opt.js';
 import { PCSS } from './pcss.js';
-import { LIGHT_TYPE_NONE, LIGHT_TYPE_DIRECTIONAL, LIGHT_TYPE_POINT } from '../values.js';
-import { ShaderHelper } from '../material/shader/helper.js';
+import { DOM } from './dom.js';
+import { LIGHT_TYPE_NONE, LIGHT_TYPE_POINT, LIGHT_TYPE_DIRECTIONAL } from '../values.js';
 import { getDevice } from '../app/api.js';
 import { ShadowRegion } from './shadow_region.js';
 
@@ -38,6 +38,9 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
     /** @internal */ _pcssFilterSampleCount;
     /** @internal */ _pcssMaxFilterRadius;
     /** @internal */ _pcssTemporalJitter;
+    /** @internal */ _domLayerDistance;
+    /** @internal */ _domDensity;
+    /** @internal */ _domFilterSize;
     /** @internal */ _vsmBlurKernelSize;
     /** @internal */ _vsmBlurRadius;
     /** @internal */ _vsmDarkness;
@@ -59,7 +62,7 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
             numCascades: 1,
             splitLambda: 0.5,
             depthBias: 0.003,
-            normalBias: 0.2,
+            normalBias: 1.5,
             nearClip: 1
         };
         this._resourceDirty = true;
@@ -74,6 +77,9 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
         this._pcssFilterSampleCount = 32;
         this._pcssMaxFilterRadius = 32;
         this._pcssTemporalJitter = true;
+        this._domLayerDistance = 0.25;
+        this._domDensity = 1;
+        this._domFilterSize = 5;
         this._vsmBlurKernelSize = 5;
         this._vsmBlurRadius = 4;
         this._vsmDarkness = 0.3;
@@ -174,7 +180,20 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
     set depthBias(val) {
         this._config.depthBias = val;
     }
-    /** Normal bias for the shadow map */ get normalBias() {
+    /**
+   * Normal offset bias, in shadow map texels.
+   *
+   * @remarks
+   * Before sampling, the receiver is moved along its normal by this many texel
+   * widths, scaled by `sin(theta)` between the normal and the light so the
+   * offset is zero facing the light and largest at grazing incidence. This is
+   * what removes grazing-angle self-shadowing acne; {@link depthBias} alone
+   * cannot, because the depth error over one texel grows without bound as the
+   * surface turns away from the light.
+   *
+   * Useful values are roughly 1 to 4. Too little leaves acne on curved surfaces
+   * near the terminator; too much detaches contact shadows from thin geometry.
+   */ get normalBias() {
         return this._config.normalBias;
     }
     set normalBias(val) {
@@ -215,7 +234,7 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
             this.shadowDistance = 120;
             this.splitLambda = 0.75;
             this.depthBias = 0.005;
-            this.normalBias = 0.3;
+            this.normalBias = 2;
             this.nearClip = 0.2;
             this.pcfKernelSize = 5;
             this.numShadowCascades = this._light.isDirectionLight() ? 3 : 1;
@@ -226,7 +245,7 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
         this.shadowDistance = 800;
         this.splitLambda = 0.6;
         this.depthBias = 0.0035;
-        this.normalBias = 0.22;
+        this.normalBias = 1.5;
         this.nearClip = 1;
         this.pcfKernelSize = 3;
         this.numShadowCascades = this._light.isDirectionLight() ? 4 : 1;
@@ -283,6 +302,69 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
             }
         }
     }
+    /**
+   * Depth spanned by the deep opacity map's layers, in world units along the
+   * light direction. Only meaningful when the shadow mode is `dom`.
+   *
+   * @remarks
+   * Set it to roughly the thickness of the hair. Too small and everything past
+   * the outer strands saturates the last layer, which is a hard shadow again;
+   * too large and all three layers fall inside the first strand, leaving the
+   * interior unshadowed.
+   */ get domLayerDistance() {
+        return this._domLayerDistance;
+    }
+    set domLayerDistance(val) {
+        val = Math.max(0.0001, Number(val) || 0);
+        if (val !== this._domLayerDistance) {
+            this._domLayerDistance = val;
+            const dom = this.asDOM();
+            if (dom) {
+                dom.layerDistance = this._domLayerDistance;
+            }
+        }
+    }
+    /**
+   * How strongly accumulated hair coverage attenuates light. Only meaningful when
+   * the shadow mode is `dom`.
+   *
+   * @remarks
+   * Raise it to darken the interior of a groom without moving the layers.
+   */ get domDensity() {
+        return this._domDensity;
+    }
+    set domDensity(val) {
+        val = Math.max(0, Number(val) || 0);
+        if (val !== this._domDensity) {
+            this._domDensity = val;
+            const dom = this.asDOM();
+            if (dom) {
+                dom.density = this._domDensity;
+            }
+        }
+    }
+    /**
+   * Width of the deep opacity map's sampling kernel in texels: 1, 3, 5 or 7. Only
+   * meaningful when the shadow mode is `dom`.
+   *
+   * @remarks
+   * The technique's own gradation runs along the light rather than across the
+   * map, so without a kernel the silhouette of a groom is as hard an edge as an
+   * unfiltered shadow map gives. This is what softens it, at one layer lookup per
+   * tap. Defaults to 5.
+   */ get domFilterSize() {
+        return this._domFilterSize;
+    }
+    set domFilterSize(val) {
+        val = val !== 1 && val !== 3 && val !== 5 && val !== 7 ? 5 : val;
+        if (val !== this._domFilterSize) {
+            this._domFilterSize = val;
+            const dom = this.asDOM();
+            if (dom) {
+                dom.filterSize = this._domFilterSize;
+            }
+        }
+    }
     /** Blocker search sample count for PCSS shadow */ get pcssBlockerSampleCount() {
         return this._pcssBlockerSampleCount;
     }
@@ -456,25 +538,6 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
             ctx.shadowMapInfo = null;
         }
     }
-    /** @internal */ static computeShadowBias(shadowMapParams, scope, z, NdotL, linear) {
-        const pb = scope.$builder;
-        const depthBiasParam = ShaderHelper.getDepthBiasValues(scope);
-        if (shadowMapParams.lightType === LIGHT_TYPE_DIRECTIONAL) {
-            return pb.dot(pb.mul(depthBiasParam.xy, pb.vec2(1, pb.sub(1, NdotL))), pb.vec2(1, 1));
-        } else {
-            const nearFar = ShaderHelper.getShadowCameraParams(scope).xy;
-            const linearDepth = linear ? z : ShaderHelper.nonLinearDepthToLinearNormalized(scope, z, nearFar);
-            const biasScaleFactor = pb.mix(1, depthBiasParam.w, linearDepth);
-            return pb.dot(pb.mul(depthBiasParam.xy, pb.vec2(1, pb.sub(1, NdotL)), biasScaleFactor), pb.vec2(1, 1));
-        }
-    }
-    /** @internal */ static computeShadowBiasCSM(shadowMapParams, scope, NdotL, split) {
-        const pb = scope.$builder;
-        const depthBiasParam = ShaderHelper.getDepthBiasValues(scope);
-        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)));
-        const depthBiasScale = pb.dot(ShaderHelper.getDepthBiasScales(scope), splitFlags);
-        return pb.dot(pb.mul(depthBiasParam.xy, pb.vec2(1, pb.sub(1, NdotL)), depthBiasScale), pb.vec2(1, 1));
-    }
     /** @internal */ isTextureInvalid(texture, target, format, width, height) {
         return texture && (texture.target !== target || texture.format !== format || texture.width !== width || texture.height !== height || texture.depth !== this.numShadowCascades);
     }
@@ -766,8 +829,15 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
     /** @internal */ calcDepthBiasParams(camera, shadowMapSize, depthBias, normalBias, depthScale, result) {
         const sizeNear = Math.min(camera.getProjectionMatrix().getNearPlaneWidth(), camera.getProjectionMatrix().getNearPlaneHeight());
         const sizeFar = Math.min(camera.getProjectionMatrix().getFarPlaneWidth(), camera.getProjectionMatrix().getFarPlaneHeight());
-        const scaleFactor = sizeNear / shadowMapSize * 2;
-        result.setXYZW(depthBias * scaleFactor, normalBias * 0.0001, depthScale, sizeFar / sizeNear);
+        // World-space size of one shadow map texel at the near plane. Both bias
+        // terms are expressed in multiples of it, so a tighter cascade automatically
+        // gets a proportionally smaller offset.
+        const texelWorldSize = sizeNear / shadowMapSize;
+        result.setXYZW(depthBias * texelWorldSize * 2, // Normal offset distance in world units. Unlike a depth bias this moves
+        // the receiver sideways out of the texel that produces grazing-angle
+        // acne, which no amount of depth bias can fix (the required depth offset
+        // diverges as NdotL approaches zero).
+        normalBias * texelWorldSize, depthScale, sizeFar / sizeNear);
     }
     /** @internal */ postRenderShadowMap(shadowMapParams) {
         this._impl.postRenderShadowMap(shadowMapParams);
@@ -779,7 +849,7 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
         const shadowMapParams = ShadowMapper.fetchShadowMapParams();
         shadowMapParams.impl = this._impl;
         shadowMapParams.lightType = this.light.lightType;
-        shadowMapParams.numShadowCascades = shadowMapParams.lightType === LIGHT_TYPE_DIRECTIONAL ? this._config.numCascades ?? 1 : 1;
+        shadowMapParams.numShadowCascades = shadowMapParams.lightType === LIGHT_TYPE_DIRECTIONAL && this._impl.supportsCascades() ? this._config.numCascades ?? 1 : 1;
         ctx.shadowMapInfo.set(this.light, shadowMapParams);
         const scene = ctx.scene;
         const camera = ctx.camera;
@@ -791,6 +861,32 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
         shadowMapParams.depthClampEnabled = false;
         renderPass.clearColor = this._impl.getShadowMapClearColor(shadowMapParams);
         const depthScale = this._impl.getDepthScale();
+        const geometryPassCount = Math.max(1, this._impl.getGeometryPassCount(shadowMapParams) >> 0);
+        // Repeats the caster draw for implementations that need more than one look at
+        // the geometry (deep opacity maps). Single-pass implementations - every one
+        // but DOM - take the `pass === 0` path once and behave exactly as before.
+        const renderGeometry = (renderCamera, cullCamera)=>{
+            if (geometryPassCount === 1) {
+                renderPass.render(ctx, renderCamera, cullCamera);
+                return;
+            }
+            // Culling depends only on the camera, so the extra passes reuse the first
+            // pass's queue rather than walking the scene graph again per pass.
+            const renderQueue = renderPass.cullScene(ctx, cullCamera ?? renderCamera);
+            try {
+                for(let pass = 0; pass < geometryPassCount; pass++){
+                    this._impl.beginGeometryPass(shadowMapParams, pass);
+                    // The emitted caster shader differs between passes, and the shadow pass
+                    // keys its programs on this hash, so it has to be refreshed per pass
+                    // rather than computed once up front.
+                    shadowMapParams.shaderHash = this.getShaderHash(shadowMapParams);
+                    renderPass.clearColor = this._impl.getShadowMapClearColor(shadowMapParams);
+                    renderPass.render(ctx, renderCamera, cullCamera, renderQueue);
+                }
+            } finally{
+                renderQueue.dispose();
+            }
+        };
         const directionalShadowRegion = this._shadowRegion.region;
         const shadowRegion = this._light.isDirectionLight() && directionalShadowRegion?.isValid() ? directionalShadowRegion : scene.boundingBox;
         if (this._light.isPointLight()) {
@@ -811,20 +907,24 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
                 shadowMapRenderCamera.lookAtCubeFace(face);
                 fb.setColorAttachmentCubeFace(0, face);
                 fb.setDepthAttachmentCubeFace(face);
-                renderPass.render(ctx, shadowMapRenderCamera);
+                renderGeometry(shadowMapRenderCamera);
             }
             shadowMapParams.shadowMatrices.set(Matrix4x4.identity());
             ShadowMapper.releaseCamera(shadowMapRenderCamera);
         } else {
-            if (this._config.numCascades > 1) {
-                const distances = this.calcSplitDistances(camera.getNearPlane(), Math.min(this._shadowDistance, camera.getFarPlane()), this._config.numCascades);
+            // Reads the resolved count, not the configured one: an implementation that
+            // cannot store cascades has already collapsed it to a single split, and the
+            // cascade path would index array layers its shadow map does not have.
+            const numCascades = shadowMapParams.numShadowCascades;
+            if (numCascades > 1) {
+                const distances = this.calcSplitDistances(camera.getNearPlane(), Math.min(this._shadowDistance, camera.getFarPlane()), numCascades);
                 const cascadeCamera = ShadowMapper.fetchCameraForScene(scene);
                 const shadowMapRenderCamera = ShadowMapper.fetchCameraForScene(scene);
                 const shadowMapCullCamera = ShadowMapper.fetchCameraForScene(scene);
                 shadowMapCullCamera.clipMask = AABB.ClipLeft | AABB.ClipRight | AABB.ClipBottom | AABB.ClipTop;
                 cascadeCamera.parent = camera;
                 shadowMapParams.depthClampEnabled = getDevice().getDeviceCaps().shaderCaps.supportFragmentDepth;
-                for(let split = 0; split < this._config.numCascades; split++){
+                for(let split = 0; split < numCascades; split++){
                     cascadeCamera.setPerspective(camera.getFOV(), camera.getAspect(), distances[split], distances[split + 1]);
                     const snapMatrix = ShadowMapper._snapMatrix;
                     const border = shadowMapParams.impl.getShadowMapBorder(shadowMapParams); //20 / this._config.shadowMapSize;
@@ -839,8 +939,8 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
                         fb.setColorAttachmentLayer(0, split);
                         fb.setDepthAttachmentLayer(split);
                     } else {
-                        const numRows = this._config.numCascades > 2 ? 2 : 1;
-                        const numCols = this._config.numCascades > 1 ? 2 : 1;
+                        const numRows = numCascades > 2 ? 2 : 1;
+                        const numCols = numCascades > 1 ? 2 : 1;
                         const adjMatrix = new Matrix4x4();
                         const col = split % 2;
                         const row = split >> 1;
@@ -867,7 +967,7 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
                     }
                     device.setFramebuffer(fb);
                     device.setScissor(scissor);
-                    renderPass.render(ctx, shadowMapRenderCamera, shadowMapCullCamera);
+                    renderGeometry(shadowMapRenderCamera, shadowMapCullCamera);
                     shadowMapParams.shadowMatrices.set(Matrix4x4.transpose(shadowMapRenderCamera.viewProjectionMatrix), split * 16);
                     shadowMapParams.cascadeDistances[split] = distances[split + 1];
                 }
@@ -890,7 +990,7 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
                 shadowMapParams.cameraParams.setXYZW(shadowMapRenderCamera.getNearPlane(), shadowMapRenderCamera.getFarPlane(), this._config.shadowMapSize, this._shadowDistance);
                 device.setFramebuffer(fb);
                 shadowMapRenderCamera.setProjectionMatrix(Matrix4x4.multiply(snapMatrix, shadowMapRenderCamera.getProjectionMatrix()));
-                renderPass.render(ctx, shadowMapRenderCamera);
+                renderGeometry(shadowMapRenderCamera);
                 shadowMapParams.shadowMatrices.set(Matrix4x4.transpose(shadowMapRenderCamera.viewProjectionMatrix));
                 ShadowMapper.releaseCamera(shadowMapRenderCamera);
             }
@@ -898,10 +998,18 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
         this.postRenderShadowMap(shadowMapParams);
     }
     /** @internal */ applyMode(mode) {
-        if (mode !== 'hard' && mode !== 'vsm' && mode !== 'esm' && mode !== 'pcf' && mode !== 'pcf-pd' && mode !== 'pcf-opt' && mode !== 'pcss') {
+        if (mode !== 'hard' && mode !== 'vsm' && mode !== 'esm' && mode !== 'pcf' && mode !== 'pcf-pd' && mode !== 'pcf-opt' && mode !== 'pcss' && mode !== 'dom') {
             console.error(`ShadowMapper.setShadowMode() failed: invalid mode: ${mode}`);
             return;
         }
+        if (mode === 'dom' && getDevice().type !== 'webgpu') {
+            // The strand geometry this mode exists to shadow is WebGPU only, so the
+            // WebGL paths were never built. Falling back keeps a scene authored with it
+            // renderable rather than failing to produce a shadow map at all.
+            console.warn(`ShadowMapper.setShadowMode(): 'dom' requires WebGPU, falling back to 'pcf'`);
+            this.applyMode('pcf');
+            return;
+        }
         this._impl = null;
         if (mode === 'hard') {
             this._impl = new SSM();
@@ -914,6 +1022,8 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
             esm.logSpace = this._esmLogSpace;
         } else if (mode === 'pcf' || mode === 'pcf-opt' || mode === 'pcf-pd') {
             this._impl = new PCFOPT(this._pcfKernelSize);
+        } else if (mode === 'dom') {
+            this._impl = new DOM(this._domLayerDistance, this._domDensity, this._domFilterSize);
         } else if (mode === 'pcss') {
             this._impl = new PCSS(this._pcssLightRadius, this._pcssBlockerSampleCount, this._pcssFilterSampleCount, this._pcssMaxFilterRadius, this._pcssTemporalJitter);
         }
@@ -921,6 +1031,9 @@ const tmpFrustum = new Frustum(Matrix4x4.identity());
     /** @internal */ asVSM() {
         return this._impl?.getType() === 'vsm' ? this._impl : null;
     }
+    /** @internal */ asDOM() {
+        return this._impl?.getType() === 'dom' ? this._impl : null;
+    }
     /** @internal */ asESM() {
         return this._impl?.getType() === 'esm' ? this._impl : null;
     }