@zephyr3d/scene 0.9.21 → 0.9.23

package/dist/posteffect/sss.js

@@ -1,4 +1,4 @@
-import { Vector2, Vector4, Matrix4x4 } from '@zephyr3d/base';
+import { Vector2, Vector4, Matrix4x4, DEPTH_COMPARE_FARTHER, DEPTH_FARTHEST } from '@zephyr3d/base';
 import { ShaderHelper } from '../material/shader/helper.js';
 import '../material/lambert.js';
 import '../material/blinn.js';
@@ -79,9 +79,32 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
         }
         return null;
     }
+    /**
+   * Whether the combine pass should read the screen-space shadow mask for the
+   * combine light instead of recomputing its shadow. Enabled when the camera
+   * renders the mask and the combine light was actually written into it: the
+   * mask already holds the identical shadow — same shadow impl (PCSS/VSM/…),
+   * distance fade and shadowStrength — so this skips a full redundant per-pixel
+   * shadow evaluation. Shadow mode is irrelevant: the mask is rendered with the
+   * light's own impl. Falls back to the inline path when the light is not in the
+   * mask (e.g. it overflows {@link MAX_SHADOW_MASK_LIGHTS}).
+   *
+   * Only valid at execute time, after the ShadowMaps and ShadowMask passes have
+   * populated shadowMapInfo / maskOrdinal.
+   */ useCombineShadowMask(ctx, shadowLight) {
+        if (!shadowLight || !ctx.screenSpaceShadowMask) {
+            return false;
+        }
+        const shadowMapParams = ctx.shadowMapInfo?.get(shadowLight);
+        return !!(shadowMapParams?.shadowMap && shadowMapParams.impl && shadowMapParams.maskOrdinal != null);
+    }
     getCombineProgramKey(ctx, shadowLight) {
         const shadowMapParams = shadowLight ? ctx.shadowMapInfo?.get(shadowLight) : null;
-        return shadowMapParams?.shaderHash ? `shadow:${shadowMapParams.shaderHash}` : 'default';
+        if (!shadowMapParams?.shaderHash) {
+            return 'default';
+        }
+        // The mask-sampling shader is independent of the PCSS impl hash.
+        return this.useCombineShadowMask(ctx, shadowLight) ? 'shadowMask' : `shadow:${shadowMapParams.shaderHash}`;
     }
     requireLinearDepthTexture() {
         return true;
@@ -89,6 +112,17 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
     requireDepthAttachment() {
         return true;
     }
+    requireSceneNormalTexture() {
+        return true;
+    }
+    requireShadowMask(ctx) {
+        // Runs at graph-build time, before shadowMapInfo is populated (that happens
+        // during the ShadowMaps pass execute), so it cannot inspect the combine
+        // light. Keep the mask alive whenever the camera renders it; combine()
+        // decides at execute time whether to sample it, and _setupFromApply only
+        // reads the handle when the mask was actually produced this frame.
+        return !!ctx.screenSpaceShadowMask;
+    }
     apply(ctx, inputColorTexture, sceneDepthTexture, srgbOutput) {
         const device = ctx.device;
         const outputFramebuffer = device.getFramebuffer();
@@ -130,8 +164,8 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
     }
     blur(ctx, inputColorTexture, sceneDepthTexture, profileLUT, targetWidth, targetHeight, kernelRadius, horizontal, sssSettings) {
         const device = ctx.device;
-        const sssNormalTexture = ctx.SSRNormalTexture ?? ctx.SSSParamTexture;
-        const hasNormalTexture = !!ctx.SSRNormalTexture;
+        const sssNormalTexture = ctx.SceneNormalTexture ?? ctx.SSSParamTexture;
+        const hasNormalTexture = !!ctx.SceneNormalTexture;
         const key = `${horizontal ? 'h' : 'v'}:${kernelRadius}`;
         let program = SSS._blurPrograms[key];
         if (!program) {
@@ -164,10 +198,10 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
     }
     combine(ctx, inputColorTexture, blurredTexture, sceneDepthTexture, profileLUT, srgbOutput) {
         const device = ctx.device;
-        const sssRoughnessTexture = ctx.SSRRoughnessTexture ?? ctx.SSSParamTexture;
-        const sssNormalTexture = ctx.SSRNormalTexture ?? ctx.SSSParamTexture;
-        const hasRoughnessTexture = !!ctx.SSRRoughnessTexture;
-        const hasNormalTexture = !!ctx.SSRNormalTexture;
+        const sssRoughnessTexture = ctx.SceneRoughnessTexture ?? ctx.SSSParamTexture;
+        const sssNormalTexture = ctx.SceneNormalTexture ?? ctx.SSSParamTexture;
+        const hasRoughnessTexture = !!ctx.SceneRoughnessTexture;
+        const hasNormalTexture = !!ctx.SceneNormalTexture;
         const shadowLight = this.getCombineShadowLight(ctx);
         const programKey = this.getCombineProgramKey(ctx, shadowLight);
         let program = SSS._combinePrograms[programKey];
@@ -187,7 +221,7 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
             y: 0,
             z: 1
         };
-        const sunColorIntensity = mainTransmissionLight ? mainTransmissionLight.diffuseAndIntensity : {
+        const sunColorIntensity = mainTransmissionLight ? ShaderHelper.getPreExposedColorIntensity(mainTransmissionLight, ctx) : {
             x: 1,
             y: 1,
             z: 1,
@@ -257,37 +291,56 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
         bindGroup.setValue('srgbOut', srgbOutput ? 1 : 0);
         if (shadowLight) {
             const shadowMapParams = ctx.shadowMapInfo.get(shadowLight);
-            const cameraPos = ctx.camera.getWorldPosition();
-            bindGroup.setValue('camera', {
-                position: new Vector4(cameraPos.x, cameraPos.y, cameraPos.z, 0),
-                params: new Vector4(ctx.camera.getNearPlane(), ctx.camera.getFarPlane(), 1, 1),
-                shadowDebugCascades: ctx.camera.shadowDebugCascades ? 1 : 0
-            });
-            bindGroup.setValue('light', {
-                sunDir: new Float32Array([
-                    sunDir.x,
-                    sunDir.y,
-                    sunDir.z
-                ]),
-                envLightStrength: ctx.env?.light.strength ?? 0,
-                envLightSpecularStrength: ctx.env?.light.specularStrength ?? 1,
-                shadowStrength: shadowLight.shadow.shadowStrength,
-                shadowCascades: shadowMapParams.numShadowCascades,
-                positionAndRange: shadowLight.positionAndRange,
-                directionAndCutoff: shadowLight.directionAndCutoff,
-                diffuseAndIntensity: shadowLight.diffuseAndIntensity,
-                extraParams: shadowLight.extraParams,
-                cascadeDistances: shadowMapParams.cascadeDistances,
-                depthBiasValues: shadowMapParams.depthBiasValues[0],
-                shadowCameraParams: shadowMapParams.cameraParams,
-                depthBiasScales: shadowMapParams.depthBiasScales,
-                shadowMatrices: new Float32Array(shadowMapParams.shadowMatrices)
-            });
-            bindGroup.setTexture('Z_UniformShadowMap', shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
+            if (this.useCombineShadowMask(ctx, shadowLight)) {
+                // Screen-space shadow mask path: bind the mask array and select this
+                // light's layer/channel from its recorded ordinal (layer = s>>2,
+                // channel = s&3). A missing mask falls back to the fully-lit dummy.
+                const ordinal = shadowMapParams.maskOrdinal ?? 0;
+                const layer = ordinal >> 2;
+                const channel = ordinal & 3;
+                bindGroup.setValue('shadowMaskLayer', layer);
+                bindGroup.setValue('shadowMaskChannel', new Float32Array([
+                    channel === 0 ? 1 : 0,
+                    channel === 1 ? 1 : 0,
+                    channel === 2 ? 1 : 0,
+                    channel === 3 ? 1 : 0
+                ]));
+                bindGroup.setTexture('Z_UniformShadowMask', ctx.shadowMaskTexture ?? ShaderHelper.getDummyShadowMask(device), fetchSampler('clamp_nearest'));
+            } else {
+                const cameraPos = ctx.camera.getWorldPosition();
+                bindGroup.setValue('camera', {
+                    position: new Vector4(cameraPos.x, cameraPos.y, cameraPos.z, 0),
+                    params: new Vector4(ctx.camera.getNearPlane(), ctx.camera.getFarPlane(), 1, 1),
+                    shadowDebugCascades: ctx.camera.shadowDebugCascades ? 1 : 0,
+                    framestamp: ctx.device.frameInfo.frameCounter
+                });
+                bindGroup.setValue('light', {
+                    sunDir: new Float32Array([
+                        sunDir.x,
+                        sunDir.y,
+                        sunDir.z
+                    ]),
+                    envLightStrength: ShaderHelper.getEnvLightLuminance(ctx),
+                    envLightSpecularStrength: ctx.env?.light.specularStrength ?? 1,
+                    shadowStrength: shadowLight.shadow.shadowStrength,
+                    shadowCascades: shadowMapParams.numShadowCascades,
+                    positionAndRange: shadowLight.positionAndRange,
+                    directionAndCutoff: shadowLight.directionAndCutoff,
+                    diffuseAndIntensity: ShaderHelper.getPreExposedColorIntensity(shadowLight, ctx),
+                    extraParams: shadowLight.extraParams,
+                    implParams: shadowMapParams.impl.getParams(),
+                    cascadeDistances: shadowMapParams.cascadeDistances,
+                    depthBiasValues: shadowMapParams.depthBiasValues[0],
+                    shadowCameraParams: shadowMapParams.cameraParams,
+                    depthBiasScales: shadowMapParams.depthBiasScales,
+                    shadowMatrices: new Float32Array(shadowMapParams.shadowMatrices)
+                });
+                bindGroup.setTexture('Z_UniformShadowMap', shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
+            }
         }
         device.setProgram(program);
         device.setBindGroup(0, bindGroup);
-        this.drawFullscreenQuad(AbstractPostEffect.getDefaultRenderState(ctx, 'gt'));
+        this.drawFullscreenQuad(AbstractPostEffect.getDefaultRenderState(ctx, DEPTH_COMPARE_FARTHER));
     }
     createBlurProgram(ctx, kernelRadius, horizontal) {
         const sampleCount = Math.max(1, Math.ceil(kernelRadius / 2));
@@ -297,7 +350,7 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                 this.$inputs.pos = pb.vec2().attrib('position');
                 this.$outputs.uv = pb.vec2();
                 pb.main(function() {
-                    this.$builtins.position = pb.vec4(this.$inputs.pos, 1, 1);
+                    this.$builtins.position = pb.vec4(this.$inputs.pos, DEPTH_FARTHEST, 1);
                     this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos.xy, 0.5), pb.vec2(0.5));
                     this.$if(pb.notEqual(this.flip, 0), function() {
                         this.$builtins.position.y = pb.neg(this.$builtins.position.y);
@@ -490,13 +543,18 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
     createCombineProgram(ctx, shadowLight) {
         const shadowMapParams = shadowLight ? ctx.shadowMapInfo?.get(shadowLight) : null;
         const shadowEnabled = !!(shadowLight && shadowMapParams?.shadowMap && shadowMapParams.impl);
+        // When the screen-space shadow mask is available for the combine light,
+        // sample it instead of recomputing PCSS (which also avoids the dpdx-in-
+        // non-uniform-control-flow constraint entirely on this path).
+        const useShadowMask = this.useCombineShadowMask(ctx, shadowLight);
+        const pcssEnabled = shadowEnabled && !useShadowMask;
         const program = ctx.device.buildRenderProgram({
             vertex (pb) {
                 this.flip = pb.int().uniform(0);
                 this.$inputs.pos = pb.vec2().attrib('position');
                 this.$outputs.uv = pb.vec2();
                 pb.main(function() {
-                    this.$builtins.position = pb.vec4(this.$inputs.pos, 1, 1);
+                    this.$builtins.position = pb.vec4(this.$inputs.pos, DEPTH_FARTHEST, 1);
                     this.$outputs.uv = pb.add(pb.mul(this.$inputs.pos.xy, 0.5), pb.vec2(0.5));
                     this.$if(pb.notEqual(this.flip, 0), function() {
                         this.$builtins.position.y = pb.neg(this.$builtins.position.y);
@@ -504,11 +562,12 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                 });
             },
             fragment (pb) {
-                if (shadowEnabled) {
+                if (pcssEnabled) {
                     const cameraStruct = pb.defineStruct([
                         pb.vec4('position'),
                         pb.vec4('params'),
-                        pb.float('shadowDebugCascades')
+                        pb.float('shadowDebugCascades'),
+                        pb.int('framestamp')
                     ]);
                     const lightStruct = pb.defineStruct([
                         pb.vec3('sunDir'),
@@ -522,6 +581,7 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                         pb.vec4('extraParams'),
                         pb.vec4('cascadeDistances'),
                         pb.vec4('depthBiasValues'),
+                        pb.vec4('implParams'),
                         pb.vec4('shadowCameraParams'),
                         pb.vec4('depthBiasScales'),
                         pb.vec4[16]('shadowMatrices')
@@ -535,6 +595,14 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                     }
                     this.Z_UniformShadowMap = shadowTex.uniform(0);
                 }
+                if (useShadowMask) {
+                    // Screen-space shadow mask: one RGBA8 array layer per 4 lights. The
+                    // combine light's visibility is one channel of one layer, selected via
+                    // the layer index and a one-hot channel selector bound at draw time.
+                    this.Z_UniformShadowMask = pb.tex2DArray().uniform(0);
+                    this.shadowMaskLayer = pb.int().uniform(0);
+                    this.shadowMaskChannel = pb.vec4().uniform(0);
+                }
                 this.colorTex = pb.tex2D().uniform(0);
                 this.diffuseTex = pb.tex2D().uniform(0);
                 this.blurTex = pb.tex2D().uniform(0);
@@ -676,8 +744,8 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                     pb.float('linearDepth')
                 ], function() {
                     this.$l.viewDepth = pb.max(pb.mul(this.linearDepth, this.cameraNearFar.y), 1e-5);
-                    this.$l.nonLinearDepth = pb.div(pb.sub(pb.div(pb.mul(this.cameraNearFar.x, this.cameraNearFar.y), this.viewDepth), this.cameraNearFar.y), pb.sub(this.cameraNearFar.x, this.cameraNearFar.y));
-                    this.$l.clipPos = pb.vec4(pb.sub(pb.mul(this.uv, 2), pb.vec2(1)), pb.sub(pb.mul(pb.clamp(this.nonLinearDepth, 0, 1), 2), 1), 1);
+                    this.$l.nonLinearDepth = ShaderHelper.linearDepthToNonLinear(this, this.viewDepth, this.cameraNearFar);
+                    this.$l.clipPos = pb.vec4(pb.sub(pb.mul(this.uv, 2), pb.vec2(1)), ShaderHelper.deviceDepthToClipZ(this, pb.clamp(this.nonLinearDepth, 0, 1)), 1);
                     this.$l.viewPos = pb.mul(this.invProjMatrix, this.clipPos);
                     this.$return(pb.div(this.viewPos.xyz, pb.max(this.viewPos.w, 1e-5)));
                 });
@@ -708,7 +776,7 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                     this.spotFactor = pb.smoothStep(this.dirCutoff.w, pb.mix(this.dirCutoff.w, 1, 0.5), this.spotFactor);
                     this.$return(pb.mul(this.spotFactor, this.falloff, this.falloff));
                 });
-                if (shadowEnabled) {
+                if (pcssEnabled) {
                     pb.func('calculateTransmissionShadow', [
                         pb.vec3('worldPos'),
                         pb.float('depth01'),
@@ -776,6 +844,28 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                     this.$l.profilePreset = this.readProfilePreset(this.param);
                     this.$l.depth01 = this.readDepth01(this.uv);
                     this.$l.result = this.baseColor.rgb;
+                    // Transmission shadow. On the PCSS path the shadow uses implicit
+                    // derivatives (dpdx) inside the impl; WGSL requires those in uniform
+                    // control flow, so it is computed here rather than inside the
+                    // profile-active branch below (a per-pixel, non-uniform branch). On the
+                    // shadow-mask path the value is a single texture fetch (no PCSS).
+                    this.$l.transmissionShadowRaw = pb.float(1);
+                    this.$l.transmissionShadow = pb.float(1);
+                    if (pcssEnabled) {
+                        this.$l.shadowNormalWS = this.decodeNormal(this.uv);
+                        this.$l.shadowViewPos = this.reconstructViewPos(this.uv, this.depth01);
+                        this.$l.shadowWorldPos = pb.mul(this.invViewMatrix, pb.vec4(this.shadowViewPos, 1)).xyz;
+                        this.$l.shadowSunDirWS = this.calculateMainLightDirection(this.shadowWorldPos, this.mainLightType, this.mainLightPosRange, this.mainLightDirCutoff, this.sunDir);
+                        this.transmissionShadowRaw = this.calculateTransmissionShadow(this.shadowWorldPos, this.depth01, pb.clamp(pb.abs(pb.dot(this.shadowNormalWS, this.shadowSunDirWS)), 0, 1));
+                        this.transmissionShadow = this.transmissionShadowRaw;
+                    } else if (useShadowMask) {
+                        // The mask already holds the identical shadow (same PCSS + distance
+                        // fade + shadowStrength) rendered by the ShadowMaskPass; read the
+                        // combine light's channel. Sample by screen UV, matching how the
+                        // other screen-space inputs (color/depth) are sampled above.
+                        this.transmissionShadowRaw = pb.dot(pb.textureArraySampleLevel(this.Z_UniformShadowMask, this.uv, this.shadowMaskLayer, 0), this.shadowMaskChannel);
+                        this.transmissionShadow = this.transmissionShadowRaw;
+                    }
                     this.$if(pb.and(pb.and(pb.and(pb.greaterThan(this.profileStrength, 1e-4), pb.greaterThan(this.profileSlot, 0)), this.profileActive), pb.lessThan(this.depth01, 1)), function() {
                         this.$l.widthStrength = pb.clamp(this.param.g, 0, 0.999);
                         this.$l.profileSettingsA = this.readProfileSettingsA(this.profileSlot);
@@ -819,11 +909,9 @@ import { AbstractPostEffect, PostEffectLayer } from './posteffect.js';
                         this.$l.sunDirWS = this.calculateMainLightDirection(this.worldPos, this.mainLightType, this.mainLightPosRange, this.mainLightDirCutoff, this.sunDir);
                         this.$l.mainLightAttenuation = this.calculateMainLightAttenuation(this.worldPos, this.mainLightType, this.mainLightPosRange, this.mainLightDirCutoff);
                         this.$l.frontLit = pb.mul(pb.dot(this.normalWS, this.sunDirWS), this.mainLightAttenuation);
-                        this.$l.transmissionShadowRaw = pb.float(1);
-                        this.$l.transmissionShadow = pb.float(1);
-                        if (shadowEnabled) {
-                            this.transmissionShadowRaw = this.calculateTransmissionShadow(this.worldPos, this.depth01, pb.clamp(pb.abs(pb.dot(this.normalWS, this.sunDirWS)), 0, 1));
-                        }
+                        // transmissionShadowRaw/transmissionShadow were computed in uniform
+                        // control flow at the top of main (PCSS sampling uses dpdx, which
+                        // WGSL forbids inside this non-uniform branch); reuse them here.
                         this.transmissionShadow = this.transmissionShadowRaw;
                         this.$l.transmissionLightAttenuation = pb.mul(this.mainLightAttenuation, this.transmissionShadow);
                         this.$l.thinnessComponents = this.estimateScreenThinnessComponents(this.uv, this.depth01, this.normalWS, this.radiusResponse);