@zephyr3d/scene 0.9.5 → 0.9.7

package/dist/material/meshmaterial.js

@@ -1,5 +1,5 @@
 import { ProgramBuilder } from '@zephyr3d/device';
-import { RENDER_PASS_TYPE_OBJECT_COLOR, QUEUE_OPAQUE, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_LIGHT, MaterialVaryingFlags, RENDER_PASS_TYPE_DEPTH, QUEUE_TRANSPARENT } from '../values.js';
+import { RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_LIGHT, QUEUE_OPAQUE, MaterialVaryingFlags, RENDER_PASS_TYPE_DEPTH, QUEUE_TRANSPARENT } from '../values.js';
 import { Material } from './material.js';
 import { encodeNormalizedFloatToRGBA } from '../shaders/misc.js';
 import { ShaderHelper } from './shader/helper.js';
@@ -67,6 +67,7 @@ let FEATURE_DISABLE_TAA = 0;
  *
  * @public
  */ class MeshMaterial extends Material {
+    static SHADER_VERSION = 3;
     /**
    * Registered instance uniforms for this material class.
    *
@@ -89,6 +90,8 @@ let FEATURE_DISABLE_TAA = 0;
     /** @internal Alpha test cutoff in [0, 1]. */ _alphaCutoff;
     /** @internal Whether alpha-test uses temporal dither coverage. */ _alphaDither;
     /** @internal Blending mode. */ _blendMode;
+    /** @internal Whether transparent materials cast shadow through a masked shadow-only path. */ _transparentShadowCaster;
+    /** @internal Alpha cutoff used by the shadow-only masked caster path. */ _shadowAlphaCutoff;
     /** @internal Face culling mode. */ _cullMode;
     /** @internal Opacity in [0, 1]. */ _opacity;
     /**
@@ -113,6 +116,8 @@ let FEATURE_DISABLE_TAA = 0;
         this._alphaCutoff = 0;
         this._alphaDither = false;
         this._blendMode = 'none';
+        this._transparentShadowCaster = false;
+        this._shadowAlphaCutoff = 0.5;
         this._cullMode = 'back';
         this._opacity = 1;
         this._taaStrength = 1 - 1 / 16;
@@ -141,11 +146,27 @@ let FEATURE_DISABLE_TAA = 0;
         this.alphaCutoff = other.alphaCutoff;
         this.alphaDither = other.alphaDither;
         this.blendMode = other.blendMode;
+        this.transparentShadowCaster = other.transparentShadowCaster;
+        this.shadowAlphaCutoff = other.shadowAlphaCutoff;
         this.cullMode = other.cullMode;
         this.opacity = other.opacity;
         this.objectColor = other.objectColor;
     }
     /**
+   * Capture the active draw context for both cached and freshly-built program paths.
+   *
+   * The shader-building hooks access `this.drawContext`, but uniform application may also
+   * consult it on subsequent frames when the GPU program is reused from cache. Updating it
+   * here keeps material mixins in sync even when `createProgram()` is skipped.
+   *
+   * @param ctx - Current draw context.
+   * @returns Whether material preparation succeeded.
+   */ apply(ctx) {
+        this._ctx = ctx;
+        this._materialPass = -1;
+        return super.apply(ctx);
+    }
+    /**
    * Mark uniform-only changes so uniforms are re-uploaded on next apply, without
    * rebuilding shader programs.
    */ uniformChanged() {
@@ -480,6 +501,31 @@ let FEATURE_DISABLE_TAA = 0;
         }
     }
     /**
+   * Whether transparent visible materials cast shadow through a masked shadow-only path.
+   * - Visible rendering stays blended.
+   * - Shadow-map rendering is treated like a cutout material using `shadowAlphaCutoff`.
+   */ get transparentShadowCaster() {
+        return this._transparentShadowCaster;
+    }
+    set transparentShadowCaster(val) {
+        if (this._transparentShadowCaster !== !!val) {
+            this._transparentShadowCaster = !!val;
+            this.optionChanged(true);
+        }
+    }
+    /**
+   * Alpha cutoff used by the shadow-only masked caster path.
+   */ get shadowAlphaCutoff() {
+        return this._shadowAlphaCutoff;
+    }
+    set shadowAlphaCutoff(val) {
+        val = val > 1 ? 1 : val < 0 ? 0 : val;
+        if (this._shadowAlphaCutoff !== val) {
+            this._shadowAlphaCutoff = val;
+            this.uniformChanged();
+        }
+    }
+    /**
    * Face culling mode: 'none' | 'front' | 'back'.
    * - Does not force shader rebuild; affects rasterizer state.
    */ get cullMode() {
@@ -525,6 +571,43 @@ let FEATURE_DISABLE_TAA = 0;
         return false;
     }
     /**
+   * Returns the effective blend mode for the current pass.
+   * Transparent-shadow-caster materials stay blended in visible passes, but become masked in shadow passes.
+   */ getEffectiveBlendMode(pass, ctx) {
+        if (ctx && this.useTransparentShadowCasterForPass(ctx.renderPass?.type) && this.featureUsed(FEATURE_ALPHABLEND) !== 'none') {
+            return 'none';
+        }
+        return this.featureUsed(FEATURE_ALPHABLEND);
+    }
+    /**
+   * Returns the alpha cutoff that should be used for the current pass.
+   */ getActiveAlphaCutoff(ctx, pass = this.pass) {
+        return ctx && this.useTransparentShadowCaster(ctx, pass) ? this._shadowAlphaCutoff : this._alphaCutoff;
+    }
+    /**
+   * Whether the current pass should use the shadow-only masked caster path.
+   */ useTransparentShadowCaster(ctx, _pass = this.pass) {
+        return !!ctx && this.useTransparentShadowCasterForPass(ctx.renderPass?.type);
+    }
+    /**
+   * Whether the specified render pass type should reinterpret this transparent material as a masked shadow caster.
+   */ useTransparentShadowCasterForPass(renderPassType) {
+        return !!this._transparentShadowCaster && renderPassType === RENDER_PASS_TYPE_SHADOWMAP && this.featureUsed(FEATURE_ALPHABLEND) !== 'none';
+    }
+    /**
+   * Whether this pass needs an alpha-cutoff uniform bound.
+   */ usesAlphaCutoff(ctx, pass = this.pass) {
+        return this._alphaCutoff > 0 || !!ctx && this.useTransparentShadowCaster(ctx, pass);
+    }
+    /**
+   * Whether this pass needs fragment color inputs.
+   * This stays aligned with the historical meaning of `needFragmentColor`,
+   * but also allows shadow-only transparent casters to fetch alpha sources.
+   */ needFragmentColorInput(ctx) {
+        const drawContext = ctx ?? this.drawContext;
+        return this.needFragmentColor(drawContext) || this.useTransparentShadowCaster(drawContext, this.pass);
+    }
+    /**
    * Update render states per pass and draw context.
    * Sets blending, alpha-to-coverage, depth test/write, cull mode, color mask, and cooperates with OIT.
    *
@@ -534,16 +617,17 @@ let FEATURE_DISABLE_TAA = 0;
    * @returns void
    */ updateRenderStates(pass, stateSet, ctx) {
         const isObjectColorPass = ctx.renderPass.type === RENDER_PASS_TYPE_OBJECT_COLOR;
-        const blending = !isObjectColorPass && (this.featureUsed(FEATURE_ALPHABLEND) !== 'none' || ctx.lightBlending);
-        const a2c = !isObjectColorPass && this.featureUsed(FEATURE_ALPHATOCOVERAGE);
-        const ztestEq = ctx.queue === QUEUE_OPAQUE && !!ctx.depthTexture && !ctx.sceneColorTexture;
+        const blendMode = this.getEffectiveBlendMode(pass, ctx);
+        const blending = !isObjectColorPass && (blendMode !== 'none' || ctx.lightBlending);
+        const a2c = !isObjectColorPass && this.featureUsed(FEATURE_ALPHATOCOVERAGE) && !this.useTransparentShadowCaster(ctx, pass);
+        const ztestEq = ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT && ctx.queue === QUEUE_OPAQUE && !!ctx.depthPrepassAttachment && !ctx.sceneColorTexture;
         if (blending || a2c) {
             const blendingState = stateSet.useBlendingState();
             if (blending) {
                 blendingState.enable(true);
                 blendingState.setBlendFuncAlpha('zero', 'one');
                 blendingState.setBlendEquation('add', 'add');
-                if (this._blendMode === 'additive' || ctx.lightBlending) {
+                if (blendMode === 'additive' || ctx.lightBlending) {
                     blendingState.setBlendFuncRGB('one', 'one');
                 } else {
                     blendingState.setBlendFuncRGB('one', 'inv-src-alpha');
@@ -593,10 +677,10 @@ let FEATURE_DISABLE_TAA = 0;
    * @param pass - Current material pass index.
    * @returns void
    */ applyUniformValues(bindGroup, ctx, pass) {
-        if (this.featureUsed(FEATURE_ALPHATEST)) {
-            bindGroup.setValue('zAlphaCutoff', this._alphaCutoff);
+        if (this.usesAlphaCutoff(ctx, pass)) {
+            bindGroup.setValue('zAlphaCutoff', this.getActiveAlphaCutoff(ctx, pass));
         }
-        if (this.isTransparentPass(pass) && ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT && !(ctx.materialFlags & MaterialVaryingFlags.INSTANCING)) {
+        if (this.isTransparentPass(pass, ctx) && ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT && !(ctx.materialFlags & MaterialVaryingFlags.INSTANCING)) {
             bindGroup.setValue('zOpacity', this._opacity);
         }
         if (ctx.oit) {
@@ -620,8 +704,8 @@ let FEATURE_DISABLE_TAA = 0;
    *
    * @param pass - Material pass index.
    * @returns True if the pass is transparent; otherwise false.
-   */ isTransparentPass(_pass) {
-        return this.featureUsed(FEATURE_ALPHABLEND) !== 'none';
+   */ isTransparentPass(pass, ctx) {
+        return this.getEffectiveBlendMode(pass, ctx) !== 'none';
     }
     /**
    * Create the GPU program for a given pass and draw context.
@@ -668,7 +752,7 @@ let FEATURE_DISABLE_TAA = 0;
    * @returns The hash fragment string.
    * @internal
    */ _createHash() {
-        return this._featureStates.map((val)=>val === undefined ? '' : val).join('|');
+        return `${MeshMaterial.SHADER_VERSION}|${this._featureStates.map((val)=>val === undefined ? '' : val).join('|')}|${Number(this._transparentShadowCaster)}`;
     }
     /**
    * Apply material uniforms to the bind group (set 2).
@@ -690,7 +774,11 @@ let FEATURE_DISABLE_TAA = 0;
    * @param ctx - Optional draw context; defaults to the last captured `drawContext`.
    * @returns True if fragment color computation is needed; otherwise false.
    */ needFragmentColor(ctx) {
-        return (ctx ?? this.drawContext).renderPass.type === RENDER_PASS_TYPE_LIGHT || this._alphaCutoff > 0 || this.alphaToCoverage;
+        const drawContext = ctx ?? this.drawContext;
+        if (!drawContext?.renderPass) {
+            return this._alphaCutoff > 0 || this.alphaToCoverage;
+        }
+        return drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT || this._alphaCutoff > 0 || this.alphaToCoverage;
     }
     /**
    * Vertex shader hook.
@@ -714,7 +802,7 @@ let FEATURE_DISABLE_TAA = 0;
             if (this.drawContext.renderPass.type === RENDER_PASS_TYPE_OBJECT_COLOR) {
                 scope.$outputs.zObjectColor = this.getInstancedUniform(scope, MeshMaterial.OBJECT_COLOR_UNIFORM);
             }
-            if (this.isTransparentPass(this.pass)) {
+            if (this.isTransparentPass(this.pass, this.drawContext)) {
                 scope.$outputs.zOpacity = this.getInstancedUniform(scope, MeshMaterial.OPACITY_UNIFORM);
             }
         } else {
@@ -733,11 +821,11 @@ let FEATURE_DISABLE_TAA = 0;
    */ fragmentShader(scope) {
         const pb = scope.$builder;
         ShaderHelper.prepareFragmentShader(pb, this.drawContext);
-        if (this._alphaCutoff > 0) {
+        if (this.usesAlphaCutoff(this.drawContext, this.pass)) {
             scope.zAlphaCutoff = pb.float().uniform(2);
         }
         if (this.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT) {
-            if (this.isTransparentPass(this.pass) && !(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING)) {
+            if (this.isTransparentPass(this.pass, this.drawContext) && !(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING)) {
                 scope.zOpacity = pb.float().uniform(2);
             }
         }
@@ -768,8 +856,20 @@ let FEATURE_DISABLE_TAA = 0;
                     this.$outputs.zFragmentOutput = pb.vec4();
                     if (ctx.materialFlags & MaterialVaryingFlags.SSR_STORE_ROUGHNESS) {
                         this.$outputs.zSSRRoughness = pb.vec4();
+                    }
+                    if (ctx.materialFlags & (MaterialVaryingFlags.SSR_STORE_ROUGHNESS | MaterialVaryingFlags.SSS_STORE_NORMAL)) {
                         this.$outputs.zSSRNormal = pb.vec4();
                     }
+                    if (ctx.materialFlags & MaterialVaryingFlags.SSS_STORE_PROFILE) {
+                        this.$outputs.zSSSProfile = pb.vec4();
+                        this.$outputs.zSSSParams = pb.vec4();
+                    }
+                    if (ctx.materialFlags & MaterialVaryingFlags.SSS_STORE_DIFFUSE) {
+                        this.$outputs.zSSSDiffuse = pb.vec4();
+                    }
+                    if (ctx.materialFlags & MaterialVaryingFlags.SSS_STORE_TRANSMISSION) {
+                        this.$outputs.zSSSTransmission = pb.vec4();
+                    }
                     if (ctx.renderPass.type === RENDER_PASS_TYPE_DEPTH && ctx.motionVectors) {
                         this.$outputs.zMotionVector = pb.vec4();
                         this.zTAAStrength = pb.float().uniform(2);
@@ -801,8 +901,13 @@ let FEATURE_DISABLE_TAA = 0;
    * @param color - Lit fragment color expression; may be undefined for depth-only paths.
    * @param ssrRoughness - Optional SSR roughness output expression.
    * @param ssrNormal - Optional SSR normal output expression.
+   * @param sssProfile - Optional SSS profile output expression.
+   * @param sssParams - Optional SSS packed params output expression.
+   * @param sssProfileEnabled - True only when this material should write SSS profile data.
+   * @param sssDiffuse - Optional diffuse-only lighting color for SSS composition.
+   * @param sssTransmission - Optional thin-shell transmission lighting color for SSS composition.
    * @returns void
-   */ outputFragmentColor(scope, worldPos, color, ssrRoughness, ssrNormal) {
+   */ outputFragmentColor(scope, worldPos, color, ssrRoughness, ssrNormal, sssProfile, sssParams, sssDiffuse, sssTransmission, sssProfileEnabled = false) {
         const pb = scope.$builder;
         const that = this;
         const funcName = 'Z_outputFragmentColor';
@@ -811,7 +916,40 @@ let FEATURE_DISABLE_TAA = 0;
             pb.float('alpha'),
             pb.float('cutoff')
         ], function() {
-            if (that.featureUsed(FEATURE_ALPHADITHER) && !that.isTransparentPass(that.pass)) {
+            const shadowMaskedCaster = that.useTransparentShadowCaster(that.drawContext, that.pass);
+            const shadowAlphaClip = pb.getDevice().type !== 'webgl' && that.drawContext.renderPass.type === RENDER_PASS_TYPE_SHADOWMAP && (shadowMaskedCaster || !that.isTransparentPass(that.pass, that.drawContext));
+            if (shadowAlphaClip) {
+                if (!pb.getGlobalScope().Z_shadowDither4x4) {
+                    pb.getGlobalScope().Z_shadowDither4x4 = [
+                        pb.float(0 / 16),
+                        pb.float(8 / 16),
+                        pb.float(2 / 16),
+                        pb.float(10 / 16),
+                        pb.float(12 / 16),
+                        pb.float(4 / 16),
+                        pb.float(14 / 16),
+                        pb.float(6 / 16),
+                        pb.float(3 / 16),
+                        pb.float(11 / 16),
+                        pb.float(1 / 16),
+                        pb.float(9 / 16),
+                        pb.float(15 / 16),
+                        pb.float(7 / 16),
+                        pb.float(13 / 16),
+                        pb.float(5 / 16)
+                    ];
+                }
+                this.$l.alphaWidth = pb.max(pb.fwidth(this.alpha), 1e-4);
+                this.$l.shadowCutoff = pb.max(pb.sub(this.cutoff, pb.min(0.18, pb.mul(this.alphaWidth, 2))), 0);
+                this.$l.coverage = pb.clamp(pb.add(pb.div(pb.sub(this.alpha, this.shadowCutoff), this.alphaWidth), 0.5), 0, 1);
+                this.$l.pixel = pb.mod(pb.floor(this.$builtins.fragCoord.xy), pb.vec2(4));
+                // Scramble the ordered dither with shadow depth so overlapping masked layers
+                // at the same texel do not all discard the exact same coverage bits.
+                this.$l.layerJitter = pb.floor(pb.mul(pb.fract(pb.mul(this.$builtins.fragCoord.z, 131.37)), 16));
+                this.$l.ditherIndex = pb.mod(pb.add(pb.add(pb.mul(this.pixel.y, 4), this.pixel.x), this.layerJitter), 16);
+                this.$l.noise = this.Z_shadowDither4x4.at(pb.uint(this.ditherIndex));
+                this.$return(pb.lessThan(this.coverage, this.noise));
+            } else if (that.featureUsed(FEATURE_ALPHADITHER) && !that.isTransparentPass(that.pass, that.drawContext)) {
                 this.$l.frame = pb.float(ShaderHelper.getFramestamp(this));
                 this.$l.phase = pb.add(this.$builtins.fragCoord.xy, pb.vec2(this.frame, pb.mul(this.frame, 0.754877666)));
                 this.$l.noise = pb.fract(pb.mul(pb.sin(pb.dot(this.phase, pb.vec2(12.9898, 78.233))), 43758.5453));
@@ -830,19 +968,19 @@ let FEATURE_DISABLE_TAA = 0;
             this.$l.outColor = color ? this.color : pb.vec4();
             if (that.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT) {
                 let output = true;
-                if (!that.isTransparentPass(that.pass) && !that.alphaToCoverage) {
+                if (!that.isTransparentPass(that.pass, that.drawContext) && !that.alphaToCoverage) {
                     this.outColor.a = 1;
-                } else if (that.isTransparentPass(that.pass)) {
+                } else if (that.isTransparentPass(that.pass, that.drawContext)) {
                     const opacity = that.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING ? this.$inputs.zOpacity : this.zOpacity;
                     this.outColor.a = pb.mul(this.outColor.a, opacity);
                 }
-                if (that.isTransparentPass(that.pass)) {
+                if (that.isTransparentPass(that.pass, that.drawContext)) {
                     if (this.zAlphaCutoff) {
                         this.$if(pb.getGlobalScope()[alphaClipFuncName](this.outColor.a, this.zAlphaCutoff), function() {
                             pb.discard();
                         });
                     }
-                    if (that.drawContext.oit && that.drawContext.lightBlending) {
+                    if (that.drawContext.oit && that.drawContext.lightBlending && that.drawContext.oit.getType() !== 'ab') {
                         // For OIT with multi-light decomposition, keep additive light passes
                         // color-only to avoid duplicating per-fragment transmittance.
                         this.outColor = pb.vec4(this.outColor.rgb, 0);
@@ -914,15 +1052,32 @@ let FEATURE_DISABLE_TAA = 0;
         if (that.drawContext.materialFlags & MaterialVaryingFlags.SSR_STORE_ROUGHNESS) {
             // Transparent/blended passes (and materials that depend on scene color like transmission)
             // do not have a stable depth match for SSR, so force-disable SSR contribution on those pixels.
-            const disableSSR = that.isTransparentPass(that.pass) && that.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT;
+            const disableSSR = that.isTransparentPass(that.pass, that.drawContext) && that.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT;
             const disableSceneColorSSR = that.needSceneColor() && that.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT;
             if (disableSSR || disableSceneColorSSR) {
                 scope.$outputs.zSSRRoughness = pb.vec4(0, 0, 0, 1);
                 scope.$outputs.zSSRNormal = pb.vec4(0);
             } else {
-                scope.$outputs.zSSRRoughness = ssrRoughness ?? pb.vec4(1, 0, 0, 1);
+                scope.$outputs.zSSRRoughness = ssrRoughness ?? pb.vec4(1, 1, 0, 1);
                 scope.$outputs.zSSRNormal = ssrNormal ? ssrNormal : scope.$inputs.wNorm ? pb.vec4(pb.add(pb.mul(pb.normalize(scope.$inputs.wNorm), 0.5), pb.vec3(0.5)), 1) : pb.vec4(0.5, 0.5, 1, 1);
             }
+        } else if (that.drawContext.materialFlags & MaterialVaryingFlags.SSS_STORE_NORMAL) {
+            const disableNormal = that.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT && (that.isTransparentPass(that.pass, that.drawContext) && !that.alphaToCoverage || that.needSceneColor());
+            scope.$outputs.zSSRNormal = disableNormal ? pb.vec4(0) : ssrNormal ? ssrNormal : scope.$inputs.wNorm ? pb.vec4(pb.add(pb.mul(pb.normalize(scope.$inputs.wNorm), 0.5), pb.vec3(0.5)), 1) : pb.vec4(0.5, 0.5, 1, 1);
+        }
+        if (that.drawContext.materialFlags & MaterialVaryingFlags.SSS_STORE_PROFILE) {
+            const disableSSS = that.drawContext.renderPass.type === RENDER_PASS_TYPE_LIGHT && (that.isTransparentPass(that.pass, that.drawContext) && !that.alphaToCoverage || that.needSceneColor());
+            const writeSSSProfile = sssProfileEnabled && !disableSSS;
+            scope.$outputs.zSSSProfile = writeSSSProfile ? sssProfile ?? pb.vec4(0) : pb.vec4(0);
+            scope.$outputs.zSSSParams = writeSSSProfile ? sssParams ?? pb.vec4(0) : pb.vec4(0);
+        }
+        if (that.drawContext.materialFlags & MaterialVaryingFlags.SSS_STORE_DIFFUSE) {
+            const disableSSS = that.drawContext.renderPass.type !== RENDER_PASS_TYPE_LIGHT || that.isTransparentPass(that.pass, that.drawContext) && !that.alphaToCoverage || that.needSceneColor();
+            scope.$outputs.zSSSDiffuse = disableSSS ? pb.vec4(0) : sssDiffuse ?? pb.vec4(0);
+        }
+        if (that.drawContext.materialFlags & MaterialVaryingFlags.SSS_STORE_TRANSMISSION) {
+            const disableSSS = that.drawContext.renderPass.type !== RENDER_PASS_TYPE_LIGHT || that.isTransparentPass(that.pass, that.drawContext) && !that.alphaToCoverage || that.needSceneColor();
+            scope.$outputs.zSSSTransmission = disableSSS ? pb.vec4(0) : sssTransmission ?? pb.vec4(0);
         }
     }
 }