@zephyr3d/scene 0.9.25 → 0.9.27

package/dist/shaders/diffusion.js

@@ -0,0 +1,54 @@
+/**
+ * Burley (Christensen-Burley) normalized diffusion weight for one channel.
+ *
+ * @remarks
+ * The profile is
+ *
+ * ```
+ * R(r) = (exp(-r/d) + exp(-r/(3d))) / (8 * pi * d * r)
+ * ```
+ *
+ * where `d` is the shaping distance. The `1/r` factor is the 2D-to-1D Jacobian
+ * of the radially symmetric profile; a separable screen-space blur integrates
+ * along a line rather than over a disc, so it is dropped here and the weights
+ * are renormalized by their own sum instead. That is the standard separable
+ * approximation - it is not exactly the 2D profile, but the error is far below
+ * what the depth-aware tap rejection introduces anyway.
+ *
+ * Two exponentials rather than one Gaussian is what gives skin its
+ * characteristic shape: a sharp peak that keeps detail near the source, plus a
+ * long tail that carries the bleed. A single Gaussian can match one or the
+ * other, not both, which is why Gaussian SSS reads as haze.
+ *
+ * {@link SSS} in `posteffect/sss.ts` carries a more elaborate variant driven by
+ * per-pixel profile slots and a LUT. This one is deliberately separate and much
+ * smaller: {@link SkinSSS} has a single global profile in uniforms, so it needs
+ * no LUT plumbing. Unifying the two is worthwhile but would mean editing a
+ * 2500-line shader that has no pixel-regression coverage.
+ *
+ * @param scope - Shader scope.
+ * @param distance - Absolute distance from the kernel center, in the same units as `d`.
+ * @param d - Shaping distance for this channel. Larger values scatter further.
+ * @returns Unnormalized weight; callers must divide by the accumulated sum.
+ *
+ * @internal
+ */ function burleyDiffusionWeight(scope, distance, d) {
+    const pb = scope.$builder;
+    const funcName = 'lib_burleyDiffusionWeight';
+    pb.func(funcName, [
+        pb.float('distance'),
+        pb.float('d')
+    ], function() {
+        this.$l.safeD = pb.max(this.d, 1e-4);
+        this.$l.r = pb.div(pb.abs(this.distance), this.safeD);
+        // exp() of a large negative is flushed to zero anyway; clamping keeps the
+        // argument in range on backends that are less forgiving about it.
+        this.$l.e1 = pb.exp(pb.neg(pb.min(this.r, 40)));
+        this.$l.e2 = pb.exp(pb.neg(pb.min(pb.div(this.r, 3), 40)));
+        this.$return(pb.div(pb.add(this.e1, this.e2), this.safeD));
+    });
+    return pb.getGlobalScope()[funcName](distance, d);
+}
+
+export { burleyDiffusionWeight };
+//# sourceMappingURL=diffusion.js.map

package/dist/shaders/diffusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffusion.js","sources":["../../src/shaders/diffusion.ts"],"sourcesContent":["import type { PBInsideFunctionScope, PBShaderExp } from '@zephyr3d/device';\r\n\r\n/**\r\n * Burley (Christensen-Burley) normalized diffusion weight for one channel.\r\n *\r\n * @remarks\r\n * The profile is\r\n *\r\n * ```\r\n * R(r) = (exp(-r/d) + exp(-r/(3d))) / (8 * pi * d * r)\r\n * ```\r\n *\r\n * where `d` is the shaping distance. The `1/r` factor is the 2D-to-1D Jacobian\r\n * of the radially symmetric profile; a separable screen-space blur integrates\r\n * along a line rather than over a disc, so it is dropped here and the weights\r\n * are renormalized by their own sum instead. That is the standard separable\r\n * approximation - it is not exactly the 2D profile, but the error is far below\r\n * what the depth-aware tap rejection introduces anyway.\r\n *\r\n * Two exponentials rather than one Gaussian is what gives skin its\r\n * characteristic shape: a sharp peak that keeps detail near the source, plus a\r\n * long tail that carries the bleed. A single Gaussian can match one or the\r\n * other, not both, which is why Gaussian SSS reads as haze.\r\n *\r\n * {@link SSS} in `posteffect/sss.ts` carries a more elaborate variant driven by\r\n * per-pixel profile slots and a LUT. This one is deliberately separate and much\r\n * smaller: {@link SkinSSS} has a single global profile in uniforms, so it needs\r\n * no LUT plumbing. Unifying the two is worthwhile but would mean editing a\r\n * 2500-line shader that has no pixel-regression coverage.\r\n *\r\n * @param scope - Shader scope.\r\n * @param distance - Absolute distance from the kernel center, in the same units as `d`.\r\n * @param d - Shaping distance for this channel. Larger values scatter further.\r\n * @returns Unnormalized weight; callers must divide by the accumulated sum.\r\n *\r\n * @internal\r\n */\r\nexport function burleyDiffusionWeight(\r\n  scope: PBInsideFunctionScope,\r\n  distance: PBShaderExp,\r\n  d: PBShaderExp\r\n): PBShaderExp {\r\n  const pb = scope.$builder;\r\n  const funcName = 'lib_burleyDiffusionWeight';\r\n  pb.func(funcName, [pb.float('distance'), pb.float('d')], function () {\r\n    this.$l.safeD = pb.max(this.d, 1e-4);\r\n    this.$l.r = pb.div(pb.abs(this.distance), this.safeD);\r\n    // exp() of a large negative is flushed to zero anyway; clamping keeps the\r\n    // argument in range on backends that are less forgiving about it.\r\n    this.$l.e1 = pb.exp(pb.neg(pb.min(this.r, 40)));\r\n    this.$l.e2 = pb.exp(pb.neg(pb.min(pb.div(this.r, 3), 40)));\r\n    this.$return(pb.div(pb.add(this.e1, this.e2), this.safeD));\r\n  });\r\n  return pb.getGlobalScope()[funcName](distance, d) as PBShaderExp;\r\n}\r\n"],"names":["burleyDiffusionWeight","scope","distance","d","pb","$builder","funcName","func","float","$l","safeD","max","r","div","abs","e1","exp","neg","min","e2","$return","add","getGlobalScope"],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCC,IACM,SAASA,qBAAAA,CACdC,KAA4B,EAC5BC,QAAqB,EACrBC,CAAc,EAAA;IAEd,MAAMC,EAAAA,GAAKH,MAAMI,QAAQ;AACzB,IAAA,MAAMC,QAAW,GAAA,2BAAA;IACjBF,EAAGG,CAAAA,IAAI,CAACD,QAAU,EAAA;AAACF,QAAAA,EAAAA,CAAGI,KAAK,CAAC,UAAA,CAAA;AAAaJ,QAAAA,EAAAA,CAAGI,KAAK,CAAC,GAAA;KAAK,EAAE,WAAA;QACvD,IAAI,CAACC,EAAE,CAACC,KAAK,GAAGN,EAAGO,CAAAA,GAAG,CAAC,IAAI,CAACR,CAAC,EAAE,IAAA,CAAA;AAC/B,QAAA,IAAI,CAACM,EAAE,CAACG,CAAC,GAAGR,GAAGS,GAAG,CAACT,EAAGU,CAAAA,GAAG,CAAC,IAAI,CAACZ,QAAQ,CAAG,EAAA,IAAI,CAACQ,KAAK,CAAA;;;AAGpD,QAAA,IAAI,CAACD,EAAE,CAACM,EAAE,GAAGX,GAAGY,GAAG,CAACZ,EAAGa,CAAAA,GAAG,CAACb,EAAGc,CAAAA,GAAG,CAAC,IAAI,CAACN,CAAC,EAAE,EAAA,CAAA,CAAA,CAAA;QAC1C,IAAI,CAACH,EAAE,CAACU,EAAE,GAAGf,EAAGY,CAAAA,GAAG,CAACZ,EAAGa,CAAAA,GAAG,CAACb,EAAGc,CAAAA,GAAG,CAACd,EAAGS,CAAAA,GAAG,CAAC,IAAI,CAACD,CAAC,EAAE,CAAI,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA;AACrD,QAAA,IAAI,CAACQ,OAAO,CAAChB,GAAGS,GAAG,CAACT,GAAGiB,GAAG,CAAC,IAAI,CAACN,EAAE,EAAE,IAAI,CAACI,EAAE,CAAG,EAAA,IAAI,CAACT,KAAK,CAAA,CAAA;AAC1D,KAAA,CAAA;AACA,IAAA,OAAON,GAAGkB,cAAc,EAAE,CAAChB,QAAAA,CAAS,CAACJ,QAAUC,EAAAA,CAAAA,CAAAA;AACjD;;;;"}

package/dist/shaders/shadow.js

@@ -426,15 +426,25 @@ function getShadowMapSize(scope) {
     ], function() {
         this.$l.dx = pb.dpdx(this.coords);
         this.$l.dy = pb.dpdy(this.coords);
-        this.$l.biasMultiply = pb.float(1);
         this.$l.uv = pb.vec2(pb.sub(pb.mul(this.dy.y, this.dx.z), pb.mul(this.dx.y, this.dy.z)), pb.sub(pb.mul(this.dx.x, this.dy.z), pb.mul(this.dy.x, this.dx.z)));
-        this.$l.uv = pb.mul(this.$l.uv, pb.div(this.biasMultiply, pb.sub(pb.mul(this.dx.x, this.dy.y), pb.mul(this.dx.y, this.dy.x))));
-        // from unity shader
-        this.$l.minFractionalError = pb.float(0.01);
-        this.$l.fractionalSamplingError = pb.dot(pb.vec2(getShadowMapTexelSize(this)), pb.abs(this.$l.uv));
-        this.$l.staticBias = pb.min(this.$l.fractionalSamplingError, this.$l.minFractionalError);
-        // return
-        this.$return(pb.vec3(this.$l.uv, this.$l.staticBias));
+        // At grazing incidence the shadow-space footprint of a pixel collapses and
+        // this determinant tends to zero, so the gradient blows up (and flips sign
+        // across neighbouring pixels). Rather than clamp the fallout downstream,
+        // report "no usable plane" and let the caller fall back to the constant
+        // depth bias plus normal offset.
+        this.$l.det = pb.sub(pb.mul(this.dx.x, this.dy.y), pb.mul(this.dx.y, this.dy.x));
+        this.$if(pb.lessThan(pb.abs(this.det), 1e-8), function() {
+            this.$return(pb.vec3(0));
+        });
+        this.uv = pb.div(this.uv, this.det);
+        // `.z` used to carry a scalar "static bias" capped at a hardcoded 0.01.
+        // That constant came from a Unity shader operating on perspective (non
+        // linear) shadow depth; for a directional light's orthographic camera the
+        // depth is linear, so 0.01 means 1% of the whole depth range - metres of
+        // world-space push on a typical scene, which is what produced the light
+        // leaks around the terminator. Constant depth bias plus normal offset cover
+        // this properly now, so only the plane gradient survives.
+        this.$return(pb.vec3(this.uv, 0));
     });
     return pb.getGlobalScope()[funcNameComputeReceiverPlaneDepthBias](texCoord);
 }
@@ -805,22 +815,27 @@ function chebyshevUpperBound(scope, distance, occluder, deviceEncoded) {
         depthBias
     ] : []);
 }
-/** @internal */ function filterShadowPCF(scope, lightType, shadowMapFormat, kernelSize, texCoord, receiverPlaneDepthBias, cascade) {
+/**
+ * Fixed-kernel PCF.
+ *
+ * @remarks
+ * Unlike {@link filterShadowPCSS} and {@link filterShadowPoissonDisc}, this
+ * filter never applied the receiver plane depth gradient per tap - it only used
+ * the scalar `.z` guard, which has been removed (see
+ * {@link computeReceiverPlaneDepthBias}). Over a kernel this narrow the plane
+ * correction is worth little, and the constant depth bias plus normal offset
+ * cover the receiver slope, so the parameter is gone rather than left inert.
+ * @internal
+ */ function filterShadowPCF(scope, lightType, shadowMapFormat, kernelSize, texCoord, cascade) {
     const funcNameFilterShadowPCF = `lib_filterShadowPCF${kernelSize}x${kernelSize}`;
     const pb = scope.$builder;
     pb.func(funcNameFilterShadowPCF, [
         pb.vec4('texCoord'),
-        ...receiverPlaneDepthBias ? [
-            pb.vec3('receiverPlaneDepthBias')
-        ] : [],
         ...cascade ? [
             pb.int('cascade')
         ] : []
     ], function() {
         this.$l.lightDepth = this.texCoord.z;
-        if (receiverPlaneDepthBias) {
-            this.lightDepth = REVERSE_Z ? pb.add(this.lightDepth, this.receiverPlaneDepthBias.z) : pb.sub(this.lightDepth, this.receiverPlaneDepthBias.z);
-        }
         const shadowMapTexelSize = getShadowMapTexelSize(this);
         this.$l.uv = pb.add(pb.mul(this.texCoord.xy, pb.vec2(getShadowMapSize(this))), pb.vec2(0));
         this.$l.st = pb.fract(this.uv);
@@ -880,9 +895,7 @@ function chebyshevUpperBound(scope, distance, occluder, deviceEncoded) {
         }
         this.$return(this.shadow);
     });
-    return pb.getGlobalScope()[funcNameFilterShadowPCF](texCoord, ...receiverPlaneDepthBias ? [
-        receiverPlaneDepthBias
-    ] : [], ...cascade ? [
+    return pb.getGlobalScope()[funcNameFilterShadowPCF](texCoord, ...cascade ? [
         cascade
     ] : []);
 }
@@ -941,9 +954,8 @@ function chebyshevUpperBound(scope, distance, occluder, deviceEncoded) {
         // spot receivers and their stored depth use a linear encoding.
         const deviceEncoded = isDeviceDepthShadow(lightType);
         this.$l.lightDepth = this.texCoord.z;
-        if (receiverPlaneDepthBias) {
-            this.lightDepth = REVERSE_Z && deviceEncoded ? pb.add(this.lightDepth, this.receiverPlaneDepthBias.z) : pb.sub(this.lightDepth, this.receiverPlaneDepthBias.z);
-        }
+        // The scalar `.z` guard is gone (see computeReceiverPlaneDepthBias); the
+        // per-tap plane gradient below is the part that was ever load bearing.
         this.$l.sampleBounds = pb.vec4(0, 0, 1, 1);
         if (cascade && getDevice().type === 'webgl' && numCascades > 1) {
             const numCols = numCascades > 1 ? 2 : 1;