@forgeax/engine-shader 0.1.19 → 0.1.21

package/src/lighting-directional.wgsl

@@ -48,14 +48,38 @@
 #import forgeax_view::common::{view, shadowMap, shadowSampler}
 #import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
 #import forgeax_pbr::shadow_pcf::{sample_shadow_2d}
+#ifdef DIRECTIONAL_PCSS_AVAILABLE
+#import forgeax_pbr::shadow_pcf::{shadow_biased_receiver_depth, shadow_clamp_texel_to_tile, shadow_load_raw_depth, shadow_sample_compare}
+#endif
 
 // feat-20260621-learn-render-5-3-production-shadow-demos M0 / AC-14:
 // compile-time upper bound on the PCF half-extent so the WGSL tap loops keep
 // a constant trip count (no dynamic loop bounds / shader variants). half=2
-// covers pcfKernelSize in {1,3,5} -> {1,9,25} taps; view.pcfKernelSize selects
-// the runtime radius via a per-iteration clip (plan-strategy D-1).
+// covers the PCF1/3/5 profiles -> {1,9,25} taps; the profile carrier selects
+// the runtime radius while keeping the receiver variant-free.
 const MAX_PCF_HALF : u32 = 2u;
 
+#ifdef DIRECTIONAL_PCSS_AVAILABLE
+const PCSS_MEDIUM_RAW_TAPS : u32 = 8u;
+const PCSS_MEDIUM_COMPARE_TAPS : u32 = 16u;
+const PCSS_HIGH_RAW_TAPS : u32 = 16u;
+const PCSS_HIGH_COMPARE_TAPS : u32 = 32u;
+
+// Cascade-local disk points are fixed, bounded, and shared by raw and compare
+// phases. A rotation derived from the integer receiver texel and cascade keeps
+// the pattern stable without a temporal input.
+const PCSS_DISK_OFFSETS : array<vec2<f32>, 32> = array<vec2<f32>, 32>(
+  vec2<f32>(-0.326, -0.945), vec2<f32>(0.236, -0.873), vec2<f32>(0.891, -0.404), vec2<f32>(-0.761, -0.581),
+  vec2<f32>(0.612, 0.146), vec2<f32>(-0.148, 0.514), vec2<f32>(-0.527, -0.109), vec2<f32>(0.074, 0.911),
+  vec2<f32>(-0.944, 0.238), vec2<f32>(0.444, -0.736), vec2<f32>(0.707, 0.641), vec2<f32>(-0.184, -0.342),
+  vec2<f32>(0.318, 0.382), vec2<f32>(-0.638, 0.526), vec2<f32>(0.955, -0.083), vec2<f32>(-0.401, 0.816),
+  vec2<f32>(-0.083, -0.632), vec2<f32>(0.539, -0.262), vec2<f32>(-0.735, -0.168), vec2<f32>(0.162, 0.719),
+  vec2<f32>(-0.841, 0.003), vec2<f32>(0.791, 0.332), vec2<f32>(-0.291, -0.791), vec2<f32>(0.021, -0.224),
+  vec2<f32>(0.386, 0.799), vec2<f32>(-0.558, 0.134), vec2<f32>(0.638, -0.555), vec2<f32>(-0.189, 0.957),
+  vec2<f32>(-0.977, -0.117), vec2<f32>(0.271, 0.589), vec2<f32>(0.819, -0.719), vec2<f32>(-0.472, -0.409),
+);
+#endif
+
 // Source: Three.js r184 src/nodes/functions/BSDF/DFGLUT.js. The full 16x16
 // RG16F table is decoded to exact f32 constants here; the lookup below mirrors
 // the source DataTexture's linear filtering and clamp-to-edge sampling without
@@ -226,8 +250,128 @@ fn _atlasTileOrigin(layer : u32, count : u32) -> vec2<f32> {
   return vec2<f32>(tile) / vec2<f32>(grid);
 }
 
+#ifdef DIRECTIONAL_PCSS_AVAILABLE
+fn _pcssDiskRotation(texel : vec2<i32>, layer : u32) -> f32 {
+  let hash = u32(texel.x) * 1664525u + u32(texel.y) * 1013904223u + (layer + 1u) * 374761393u;
+  return f32(hash % 6283u) * 0.001;
+}
+
+fn _pcssDiskPoint(index : u32, angle : f32, radius : f32) -> vec2<f32> {
+  let point = PCSS_DISK_OFFSETS[index];
+  let cs = cos(angle);
+  let sn = sin(angle);
+  return vec2<f32>(point.x * cs - point.y * sn, point.x * sn + point.y * cs) * radius;
+}
+
+fn _pcssProjectedSample(
+  shadowMapSize : vec2<u32>,
+  tileOrigin   : vec2<u32>,
+  tileSize     : vec2<u32>,
+  baseTexel    : vec2<i32>,
+  offset       : vec2<f32>,
+) -> vec2<f32> {
+  let texel = shadow_clamp_texel_to_tile(
+    baseTexel + vec2<i32>(round(offset)),
+    vec2<i32>(tileOrigin),
+    vec2<i32>(tileSize),
+    1,
+  );
+  return (vec2<f32>(texel) + vec2<f32>(0.5)) / vec2<f32>(shadowMapSize);
+}
+
+fn _samplePcssForCascade(
+  worldPos : vec3<f32>,
+  layer    : u32,
+  count    : u32,
+  normal   : vec3<f32>,
+  l        : vec3<f32>,
+  profile  : u32,
+) -> f32 {
+  let lightClip = _cascadeLightViewProj(layer) * vec4<f32>(worldPos, 1.0);
+  if (!(lightClip.w > 0.0 || lightClip.w < 0.0)) {
+    return 1.0;
+  }
+  let projCoords = lightClip.xyz / lightClip.w;
+  let tileUv = vec2<f32>(projCoords.x * 0.5 + 0.5, -projCoords.y * 0.5 + 0.5);
+  if (!(tileUv.x >= 0.0 && tileUv.x <= 1.0 && tileUv.y >= 0.0 && tileUv.y <= 1.0 && projCoords.z >= 0.0 && projCoords.z <= 1.0)) {
+    return 1.0;
+  }
+  let nDotL = dot(normal, l);
+  if (!(nDotL >= -1.0 && nDotL <= 1.0)) {
+    return 1.0;
+  }
+  let shadowMapSize = textureDimensions(shadowMap, 0);
+  let grid = _atlasTileGrid(count);
+  let tileSize = shadowMapSize / grid;
+  let tileOrigin = vec2<u32>(layer % grid.x, layer / grid.x) * tileSize;
+  let baseTexel = vec2<i32>(tileOrigin) + vec2<i32>(floor(tileUv * vec2<f32>(tileSize)));
+  let angle = _pcssDiskRotation(baseTexel, layer);
+  let biasedDepth = shadow_biased_receiver_depth(
+    projCoords.z,
+    view.normalBias,
+    view.depthBias,
+    nDotL,
+  );
+
+  let rawRadius = select(2.0, 3.0, profile == 5u);
+  var blockerDepth = 0.0;
+  var blockerCount = 0u;
+  if (profile == 4u) {
+    for (var i = 0u; i < PCSS_MEDIUM_RAW_TAPS; i = i + 1u) {
+      let rawUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, rawRadius));
+      let rawTexel = vec2<i32>(rawUv * vec2<f32>(shadowMapSize) - vec2<f32>(0.5));
+      let rawDepth = shadow_load_raw_depth(shadowMap, rawTexel);
+      if (rawDepth >= 0.0 && rawDepth < biasedDepth) {
+        blockerDepth = blockerDepth + rawDepth;
+        blockerCount = blockerCount + 1u;
+      }
+    }
+  } else {
+    for (var i = 0u; i < PCSS_HIGH_RAW_TAPS; i = i + 1u) {
+      let rawUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, rawRadius));
+      let rawTexel = vec2<i32>(rawUv * vec2<f32>(shadowMapSize) - vec2<f32>(0.5));
+      let rawDepth = shadow_load_raw_depth(shadowMap, rawTexel);
+      if (rawDepth >= 0.0 && rawDepth < biasedDepth) {
+        blockerDepth = blockerDepth + rawDepth;
+        blockerCount = blockerCount + 1u;
+      }
+    }
+  }
+  if (blockerCount == 0u) {
+    return 1.0;
+  }
+
+  let averageBlockerDepth = blockerDepth / f32(blockerCount);
+  let lightDepthWorldSpan = max(view.splitPlanes[layer].z, 0.0);
+  let worldUnitsPerTexel = max(view.splitPlanes[layer].y, 0.0);
+  if (!(lightDepthWorldSpan > 0.0 && worldUnitsPerTexel > 0.0 && view.directionalShadowFilter.y >= 0.0 && view.directionalShadowFilter.z >= 0.0)) {
+    return 1.0;
+  }
+  let worldDistance = max(0.0, biasedDepth - averageBlockerDepth) * lightDepthWorldSpan;
+  let penumbraTexels = clamp(
+    worldDistance * tan(view.directionalShadowFilter.y) / worldUnitsPerTexel,
+    0.0,
+    view.directionalShadowFilter.z,
+  );
+  let compareRadius = max(0.5, penumbraTexels);
+  var litSum = 0.0;
+  if (profile == 4u) {
+    for (var i = 0u; i < PCSS_MEDIUM_COMPARE_TAPS; i = i + 1u) {
+      let compareUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, compareRadius));
+      litSum = litSum + shadow_sample_compare(shadowMap, shadowSampler, compareUv, biasedDepth);
+    }
+    return litSum / f32(PCSS_MEDIUM_COMPARE_TAPS);
+  }
+  for (var i = 0u; i < PCSS_HIGH_COMPARE_TAPS; i = i + 1u) {
+    let compareUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, compareRadius));
+    litSum = litSum + shadow_sample_compare(shadowMap, shadowSampler, compareUv, biasedDepth);
+  }
+  return litSum / f32(PCSS_HIGH_COMPARE_TAPS);
+}
+#endif
+
 // Sample the shadow atlas with the LO 3.1.3 slope-scaled bias + dynamic PCF
-// kernel (driven by view.pcfKernelSize, MAX_PCF_HALF=2),
+// kernel (driven by the directional filter profile, MAX_PCF_HALF=2),
 // against the lightViewProj for the chosen cascade. The shader maps NDC
 // xy to that cascade's atlas tile in fragment space (matrix carries
 // clip-space; tile placement happens here so shadow_caster.gl_Position
@@ -238,6 +382,7 @@ fn _sampleShadowForCascade(
   count    : u32,
   normal   : vec3<f32>,
   l        : vec3<f32>,
+  useNormalBias : bool,
 ) -> f32 {
   let lvp = _cascadeLightViewProj(layer);
   let lightClip = lvp * vec4<f32>(worldPos, 1.0);
@@ -253,7 +398,7 @@ fn _sampleShadowForCascade(
   // shadow fields carried in the View UBO -- normalBias scales the
   // (1 - N.L) slope term, depthBias is the constant floor. Replaces the prior
   // hardcoded max(0.05*(1-N.L), 0.005).
-  let bias = max(view.normalBias * (1.0 - dot(normal, l)), view.depthBias);
+  let bias = select(view.depthBias, max(view.normalBias * (1.0 - dot(normal, l)), view.depthBias), useNormalBias);
   let adjustedDepth = currentDepth - bias;
   // NaN-safe bounds: relational < and > do not reject NaN (NaN < 0 is
   // false), so a zero / degenerate lightViewProj matrix that produces
@@ -274,21 +419,16 @@ fn _sampleShadowForCascade(
   // [tileOrigin, tileOrigin+tileScale) (one texel inset) so taps stay in-tile.
   let tileLo = tileOrigin + texel;
   let tileHi = tileOrigin + tileScale - texel;
-  // Variable-width PCF kernel driven by view.pcfKernelSize (feat-20260621
-  // 5.3-production-shadow-demos AC-14 merged with the DirectionalLightShadow
-  // merge). Constant trip count to MAX_PCF_HALF with a per-iteration clip to the
-  // runtime radius keeps the shader variant-free (no dynamic loop bound, legal
-  // for textureSampleCompareLevel uniform control flow). Host clamps
-  // view.pcfKernelSize to {1,3,5}; divisor = actual tap count, so pcfKernelSize=3
-  // -> half=1 -> 9 taps / 9.0 (result-identical to the prior hard-coded 3x3);
-  // pcfKernelSize=1 -> half=0 -> single centre tap (hard edge); pcfKernelSize=5
-  // -> half=2 -> 25-tap soft penumbra.
-  let requestedKernel = clamp(u32(round(view.pcfKernelSize)), 1u, 2u * MAX_PCF_HALF + 1u);
-  // Preserve the previous radius mapping for malformed even values:
-  // 1 -> 1x1, 2/3/4 -> 3x3, 5 -> 5x5. The authored component accepts only
-  // {1,3,5}, but keeping this normalization makes the refactor output-stable
-  // for raw UBO callers too.
-  let kernel = select(select(5u, 3u, requestedKernel <= 4u), 1u, requestedKernel == 1u);
+  // PCF1/3/5 profiles 1/2/3 retain their existing receiver. PCSS profiles 4/5
+  // use the bounded three-stage receiver below without a material or variant
+  // axis; the carrier y/z lanes provide angular radius and penumbra limit.
+  let filterProfile = clamp(u32(round(view.directionalShadowFilter.x)), 1u, 5u);
+  #ifdef DIRECTIONAL_PCSS_AVAILABLE
+  if (filterProfile >= 4u) {
+    return _samplePcssForCascade(worldPos, layer, count, normal, l, filterProfile);
+  }
+  #endif
+  let kernel = select(select(3u, 5u, filterProfile == 3u), 1u, filterProfile == 1u);
   if (kernel == 1u) {
     let lit = textureSampleCompareLevel(shadowMap, shadowSampler, clamp(uv, tileLo, tileHi), adjustedDepth);
     return lit;
@@ -414,7 +554,7 @@ fn evalDirectionalShadowFactor(
     return 1.0;
   }
   let layer = _pickCascadeLayer(viewDepth, count);
-  let shadowCurr = _sampleShadowForCascade(worldPos, layer, count, normal, l);
+  let shadowCurr = _sampleShadowForCascade(worldPos, layer, count, normal, l, true);
 
   var shadow = shadowCurr;
   if (view.cascadeBlend > 0.0 && layer + 1u < count) {
@@ -424,7 +564,7 @@ fn evalDirectionalShadowFactor(
       let dist = spCurr - viewDepth;
       let t = clamp(1.0 - dist / blendWidth, 0.0, 1.0);
       if (t > 0.0) {
-        let shadowNext = _sampleShadowForCascade(worldPos, layer + 1u, count, normal, l);
+        let shadowNext = _sampleShadowForCascade(worldPos, layer + 1u, count, normal, l, true);
         shadow = mix(shadowCurr, shadowNext, t);
       }
     }
@@ -432,6 +572,33 @@ fn evalDirectionalShadowFactor(
   return shadow;
 }
 
+// Volume receivers are samples in a medium, not surfaces. They therefore use
+// the same cascade selection, atlas placement, PCF, and shadow-distance SSOT
+// but only the bounded constant receiver bias; a ray direction is never
+// treated as a geometric normal for normalBias.
+fn evalDirectionalVolumeShadowFactor(
+  worldPos : vec3<f32>,
+  viewDepth : f32,
+) -> f32 {
+  if (view.cascadeCount < 1.0 || viewDepth > view.splitPlanes[u32(max(view.cascadeCount, 1.0)) - 1u].x) {
+    return 1.0;
+  }
+  let count = u32(max(view.cascadeCount, 1.0));
+  let layer = _pickCascadeLayer(viewDepth, count);
+  let lightDirection = normalize(-view.lightDir);
+  let current = _sampleShadowForCascade(worldPos, layer, count, vec3<f32>(0.0), lightDirection, false);
+  if (view.cascadeBlend <= 0.0 || layer + 1u >= count) {
+    return current;
+  }
+  let blendWidth = view.splitPlanes[layer].x * view.cascadeBlend;
+  if (blendWidth <= 0.0) {
+    return current;
+  }
+  let blend = clamp(1.0 - (view.splitPlanes[layer].x - viewDepth) / blendWidth, 0.0, 1.0);
+  let next = _sampleShadowForCascade(worldPos, layer + 1u, count, vec3<f32>(0.0), lightDirection, false);
+  return mix(current, next, blend);
+}
+
 // `evalDirectional` evaluates the GGX direct-lighting term for the single
 // directional light carried in `view.lightDir / view.lightColor`. CSM
 // pathway: pick cascade layer from viewZ + splitPlanes, sample the atlas

package/src/lighting-punctual.wgsl

@@ -32,12 +32,13 @@
 //              invRangeSquared, ...) -> vec3<f32>
 
 #import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
+#import forgeax_pbr::lighting_attenuation::{evalDistanceAttenuation, evalSpotAttenuation, projectSpotUv}
 // feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-5):
 // spot shadow sampling reuses the shared 2D 9-tap PCF core (sample_shadow_2d)
 // and the always-on `spotShadowMap` (binding 8) + `shadowSampler` (binding 4).
 // `shadowSampler` is imported UNCONDITIONALLY here (spot is always-on, D-5):
 // the point-shadow #ifdef block below must NOT re-import it (double import).
-#import forgeax_pbr::shadow_pcf::{sample_shadow_2d}
+#import forgeax_pbr::shadow_pcf::{sample_shadow_2d_kernel}
 #import forgeax_view::common::{spotShadowMap, shadowSampler}
 #ifdef POINT_SHADOW_AVAILABLE
 #import forgeax_pbr::shadow_pcf::{sample_shadow_cube_hw2x2}
@@ -48,6 +49,35 @@
 #import forgeax_view::common::{shadowAtlas}
 #endif
 
+// Volume lighting uses the same host-derived range and cone facts as surface
+// lighting. These wrappers intentionally return radiance factors only; the
+// volume integrator owns density, phase, transmittance, and accumulation.
+fn evalVolumePoint(
+  lightPos            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+) -> vec3<f32> {
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), 1e-4);
+  let safeDistance = max(dSquared, 1e-4);
+  return colorTimesIntensity * evalDistanceAttenuation(safeDistance, invRangeSquared);
+}
+
+fn evalVolumeSpot(
+  lightPos            : vec3<f32>,
+  lightDir            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  cosInner            : f32,
+  cosOuter            : f32,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+) -> vec3<f32> {
+  return colorTimesIntensity * evalSpotAttenuation(
+    lightPos, lightDir, worldPos, cosInner, cosOuter, invRangeSquared,
+  );
+}
+
 // Shared punctual BRDF body returning (diffuse + specular) *
 // colorTimesIntensity * nDotL * attenuation. Cone factor is applied by the
 // caller (evalSpot only).
@@ -75,8 +105,7 @@ fn evalPunctualBody(
   let specular = d_ggx(nDotH, alphaSq) * v_smith(nDotV, nDotL, alphaSq) * f;
   let kd = (vec3<f32>(1.0) - f) * (1.0 - metallic);
   let diffuse = kd * baseColor / 3.14159265;
-  let factor = max(min(1.0 - (dSquared * invRangeSquared) * (dSquared * invRangeSquared), 1.0), 0.0);
-  let attenuation = factor * factor / dSquared;
+  let attenuation = evalDistanceAttenuation(dSquared, invRangeSquared);
   return (diffuse + specular) * colorTimesIntensity * nDotL * attenuation;
 }
 
@@ -99,6 +128,50 @@ fn evalPoint(
   );
 }
 
+// Flat 2D punctual evaluators share the range/cone math with the compatibility
+// path and the clustered path, but intentionally skip the 3D BRDF normal term.
+// Sprite-lit treats every quad as an omnidirectional receiver; keeping this
+// owner here prevents URP and Cluster from drifting when the light lies in the
+// sprite plane (the common 2D flashlight setup).
+fn evalFlatRangeAttenuation(dSquared : f32, invRangeSquared : f32) -> f32 {
+  let factor = max(min(1.0 - (dSquared * invRangeSquared) * (dSquared * invRangeSquared), 1.0), 0.0);
+  return factor / dSquared;
+}
+
+fn evalPointFlat(
+  lightPos            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  baseColor           : vec3<f32>,
+) -> vec3<f32> {
+  // The flat 2D path shares the same finite-range attenuation owner as the
+  // clustered and direct Standard paths; its only intentional difference is
+  // that a sprite is an omnidirectional receiver.
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), 1e-4);
+  return baseColor * colorTimesIntensity * evalFlatRangeAttenuation(dSquared, invRangeSquared);
+}
+
+fn evalSpotFlat(
+  lightPos            : vec3<f32>,
+  lightDir            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  cosInner            : f32,
+  cosOuter            : f32,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  baseColor           : vec3<f32>,
+) -> vec3<f32> {
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), 1e-4);
+  let l = toLight / sqrt(dSquared);
+  let cone = smoothstep(cosOuter, cosInner, dot(l, -lightDir));
+  return evalPointFlat(
+    lightPos, colorTimesIntensity, invRangeSquared, worldPos, baseColor,
+  ) * cone;
+}
+
 #ifdef POINT_SHADOW_AVAILABLE
 // Shadow-modulated omnidirectional point light: same BRDF body * shadow factor.
 //
@@ -136,13 +209,13 @@ fn evalPointShadowed(
     lightPos, colorTimesIntensity, invRangeSquared,
     worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
   );
-  // Fragment-to-light direction; cubemap sample uses the local-space
-  // direction (research L0.5: Bevy convention). For a right-handed world,
-  // the cubemap convention flips Z so the +Z face look direction matches.
+  // Keep the fragment-to-light vector for BRDF and nDotL. Shadow matrices are
+  // authored light-to-fragment (`lookAt(lightPos, fragment)`), so the cube
+  // lookup must use the opposite direction. For a right-handed world, the
+  // cubemap convention flips Z so the +Z face look direction matches.
   let toLight = lightPos - worldPos;
-  // Cubemap sample direction is from-fragment-to-light (Bevy + LearnOpenGL),
-  // negated to fragment-from-light when reconstructing the depth ref.
-  let lightLocal = vec3<f32>(toLight.x, toLight.y, -toLight.z);
+  let fromLight = worldPos - lightPos;
+  let lightLocal = vec3<f32>(fromLight.x, fromLight.y, -fromLight.z);
   // Reconstruct [0,1] NDC depth from world-space distance: largest-axis
   // projection (research L0.5). Match the per-face perspective near / far
   // configured by buildPointShadowMatrices (PointLightShadow.nearPlane /
@@ -185,10 +258,9 @@ fn evalSpot(
     lightPos, colorTimesIntensity, invRangeSquared,
     worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
   );
-  let toLight = lightPos - worldPos;
-  let l = normalize(toLight);
-  let cone = smoothstep(cosOuter, cosInner, dot(l, -lightDir));
-  return body * cone;
+  return body * evalSpotAttenuation(
+    lightPos, lightDir, worldPos, cosInner, cosOuter, invRangeSquared,
+  ) / max(evalDistanceAttenuation(dot(lightPos - worldPos, lightPos - worldPos), invRangeSquared), 1e-4);
 }
 
 // feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-4 +
@@ -234,6 +306,8 @@ fn evalSpotShadowed(
   shadowAtlasTile     : i32,
   depthBias           : f32,
   normalBias          : f32,
+  pcfKernelSize       : f32,
+  shadowIntensity     : f32,
 ) -> vec3<f32> {
   let body = evalSpot(
     lightPos, lightDir, colorTimesIntensity, cosInner, cosOuter, invRangeSquared,
@@ -245,11 +319,8 @@ fn evalSpotShadowed(
   // Perspective divide; guard a zero/near-zero w (fragment behind the light or
   // a degenerate matrix) so the OOB gate below catches it as fully lit.
   let invW = select(1.0 / splane.w, 0.0, abs(splane.w) < 1e-6);
-  let ndcXY = splane.xy * invW;
+  let clipUv = projectSpotUv(lightViewProj, worldPos);
   let depthRef = splane.z * invW;
-  // Clip-space [-1,1] -> texture UV [0,1] with the standard Y flip.
-  let clipUv = vec2<f32>(ndcXY.x * 0.5 + 0.5, ndcXY.y * -0.5 + 0.5);
-
   // OOB / NaN gate: outside the light frustum (or NaN from a degenerate matrix)
   // returns fully lit. Mirrors the directional `>= 0 && <= 1` NaN-safe form.
   if (!(clipUv.x >= 0.0 && clipUv.x <= 1.0 && clipUv.y >= 0.0 && clipUv.y <= 1.0 && depthRef <= 1.0)) {
@@ -267,8 +338,12 @@ fn evalSpotShadowed(
   let texel = vec2<f32>(1.0, 1.0) / atlasDims;
 
   let nDotL = max(dot(normal, normalize(lightPos - worldPos)), 0.0);
-  let shadowFactor = sample_shadow_2d(
+  let shadowFactor = sample_shadow_2d_kernel(
     spotShadowMap, shadowSampler, atlasUv, texel, depthRef, normalBias, depthBias, nDotL,
+    pcfKernelSize,
   );
-  return body * shadowFactor;
+  // Three's SpotLight.shadow.intensity is the opacity of the shadow, not a
+  // multiplier on the light's candela radiance. A value of 1 keeps the
+  // sampled visibility fully opaque; 0 leaves the unshadowed body intact.
+  return body * mix(1.0, shadowFactor, clamp(shadowIntensity, 0.0, 1.0));
 }

package/src/msdf-text.wgsl

@@ -1,7 +1,6 @@
 #pragma variant_axis STORAGE_BUFFER_AVAILABLE
 
-#import forgeax_view::common::{View, FogViewParams, FogRay, Mesh, view, meshes, sampleMaterialTexture}
-#import forgeax_view::fog::{apply_fog}
+#import forgeax_view::common::{View, Mesh, view, meshes, sampleMaterialTexture}
 
 // @forgeax/engine-shader - msdf-text.wgsl
 // (feat-20260531-world-space-msdf-text-rendering M5 / w20).
@@ -146,22 +145,6 @@ fn screen_px_range(uv : vec2<f32>) -> f32 {
   return max(0.5 * dot(unit_range, screen_tex_size), 1.0);
 }
 
-fn applySceneFog(viewParams : View, color : vec3<f32>, alpha : f32, worldPos : vec3<f32>) -> vec4<f32> {
-  var origin = viewParams.cameraPos;
-  var direction = normalize(worldPos - origin);
-  var rayDistance = length(worldPos - origin);
-  if (viewParams.temporalProjection.z >= 0.5) {
-    let nearH = viewParams.inverseViewProj * vec4<f32>(0.0, 0.0, 0.0, 1.0);
-    let farH = viewParams.inverseViewProj * vec4<f32>(0.0, 0.0, 1.0, 1.0);
-    let nearPoint = nearH.xyz / nearH.w;
-    let farPoint = farH.xyz / farH.w;
-    direction = normalize(farPoint - nearPoint);
-    origin = worldPos - direction * dot(worldPos - viewParams.cameraPos, direction);
-    rayDistance = max(dot(worldPos - origin, direction), 0.0);
-  }
-  return apply_fog(viewParams.fog, FogRay(origin, direction, rayDistance), vec4<f32>(color, alpha));
-}
-
 // fs_main_hdr: outputs linear premultiplied alpha for the rgba16float
 // offscreen target (D-7 / R-7). The tonemap fullscreen pass handles sRGB
 // encoding; writing hdrColor lets the bloom bright-pass catch the text.
@@ -176,8 +159,7 @@ fn fs_main_hdr(in : VsOut) -> @location(0) vec4<f32> {
   let alpha = clamp(dist + 0.5, 0.0, 1.0) * material.tintColor.a;
   // Premultiplied output: rgb already multiplied by alpha for srcFactor=ONE /
   // dstFactor=ONE_MINUS_SRC_ALPHA (wiki section 6 SSOT).
-  let fogged = applySceneFog(view, material.tintColor.rgb, alpha, in.worldPos);
-  return vec4<f32>(fogged.rgb * fogged.a, fogged.a);
+  return vec4<f32>(material.tintColor.rgb * alpha, alpha);
 }
 
 // linear_to_srgb: per-channel IEC 61966-2-1 transfer function for the LDR
@@ -197,12 +179,11 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   let sd = median(msd.r, msd.g, msd.b);
   let dist = (sd - 0.5) * screen_px_range(in.uv);
   let alpha = clamp(dist + 0.5, 0.0, 1.0) * material.tintColor.a;
-  let fogged = applySceneFog(view, material.tintColor.rgb, alpha, in.worldPos);
-  let premult = fogged.rgb * fogged.a;
+  let premult = material.tintColor.rgb * alpha;
   return vec4<f32>(
     linear_to_srgb(premult.r),
     linear_to_srgb(premult.g),
     linear_to_srgb(premult.b),
-    fogged.a,
+    alpha,
   );
 }

package/src/scene-temporal.wgsl

@@ -27,17 +27,23 @@ fn sceneTemporalUv(clip : vec4<f32>) -> vec2<f32> {
   return vec2<f32>(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
 }
 
-fn sceneTemporalViewDepth(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
-  let perspectiveDepth = max(clip.w, 0.0);
+// Signed view-space Z shared by temporal reconstruction and Standard Cluster
+// lookup. Both CPU and WGSL binners consume the negative camera-space depth:
+// perspective uses -clip.w, while orthographic depth is reconstructed from
+// the projection's near/far payload rather than Euclidean world distance.
+fn sceneViewZ(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
   let ndcDepth = clip.z / max(abs(clip.w), 1e-6);
-  let orthographicDepth = temporalProjection.x +
-    ndcDepth * (temporalProjection.y - temporalProjection.x);
-  let viewDepth = select(
-    perspectiveDepth,
-    max(orthographicDepth, 0.0),
+  let orthographicViewZ = -(temporalProjection.x +
+    ndcDepth * (temporalProjection.y - temporalProjection.x));
+  return select(
+    -clip.w,
+    orthographicViewZ,
     temporalProjection.z >= 0.5,
   );
-  return log2(1.0 + viewDepth);
+}
+
+fn sceneTemporalViewDepth(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
+  return log2(1.0 + max(-sceneViewZ(clip, temporalProjection), 0.0));
 }
 
 fn packSceneTemporalV1(

package/src/shadow-pcf.wgsl

@@ -20,6 +20,49 @@
 //
 // Return: 1.0 = fully lit, 0.0 = fully shadowed.
 
+// === Directional PCSS sampling primitives ====================================
+//
+// These functions deliberately accept tile bounds from their caller. They own
+// only integer addressing, raw depth, comparison sampling, and the shared
+// receiver-bias equation; cascade selection, profile selection, blocker
+// averaging, penumbra sizing, and cascade blending remain Directional policy.
+
+fn shadow_clamp_texel_to_tile(
+  texel      : vec2<i32>,
+  tileOrigin : vec2<i32>,
+  tileSize   : vec2<i32>,
+  inset      : i32,
+) -> vec2<i32> {
+  let tileMin = tileOrigin + vec2<i32>(inset);
+  let tileMax = tileOrigin + max(vec2<i32>(inset), tileSize - vec2<i32>(1 + inset));
+  return min(tileMax, max(tileMin, texel));
+}
+
+fn shadow_load_raw_depth(
+  shadowMap : texture_depth_2d,
+  texel     : vec2<i32>,
+) -> f32 {
+  return textureLoad(shadowMap, texel, 0);
+}
+
+fn shadow_sample_compare(
+  shadowMap    : texture_depth_2d,
+  shadowSampler: sampler_comparison,
+  uv           : vec2<f32>,
+  depthRef     : f32,
+) -> f32 {
+  return textureSampleCompareLevel(shadowMap, shadowSampler, uv, depthRef);
+}
+
+fn shadow_biased_receiver_depth(
+  receiverDepth : f32,
+  normalBias    : f32,
+  depthBias     : f32,
+  nDotL         : f32,
+) -> f32 {
+  return receiverDepth - max(normalBias * (1.0 - nDotL), depthBias);
+}
+
 // 3x3 integer offset table for PCF kernel (9 taps).
 // Extracted from lighting-directional.wgsl inline loop (T-M2-4);
 // `sample_shadow_2d` walks all 9 taps; `sample_shadow_cube_hw2x2` does NOT
@@ -49,6 +92,22 @@ fn sample_shadow_2d(
   normalBias   : f32,
   depthBias    : f32,
   nDotL        : f32,
+) -> f32 {
+  return sample_shadow_2d_kernel(
+    shadowMap, shadowSampler, uv, texel, depthRef, normalBias, depthBias, nDotL, 3.0,
+  );
+}
+
+fn sample_shadow_2d_kernel(
+  shadowMap    : texture_depth_2d,
+  shadowSampler: sampler_comparison,
+  uv           : vec2<f32>,
+  texel        : vec2<f32>,
+  depthRef     : f32,
+  normalBias   : f32,
+  depthBias    : f32,
+  nDotL        : f32,
+  kernelSize   : f32,
 ) -> f32 {
   // feat-20260621-merge-directionallightshadow-into-directionallight M3 / m3-t5:
   // param names aligned to the D-1 directional convention -- the slope
@@ -60,17 +119,22 @@ fn sample_shadow_2d(
   let bias = max(normalBias * (1.0 - nDotL), depthBias / 1000.0);
   let adjustedDepth = depthRef - bias;
 
-  // 9-tap 3x3 PCF kernel. textureSampleCompareLevel returns 1.0 when
-  // adjustedDepth < sampledDepth (sampler compare op = 'less'), 0.0 otherwise.
-  // Sampler uses clamp-to-edge wrap so OOB texels return the nearest border value.
+  let halfWidth = clamp((i32(round(kernelSize)) - 1) / 2, 0, 2);
+  // Variable odd-kernel PCF. textureSampleCompareLevel returns 1.0 when
+  // adjustedDepth < sampledDepth; sampler clamp-to-edge handles OOB texels.
   var blocked = 0.0;
-  for (var i = 0u; i < 9u; i++) {
-    let off = PCF_OFFSETS[i];
-    let offsetUv = uv + vec2<f32>(f32(off.x), f32(off.y)) * texel;
-    let lit = textureSampleCompareLevel(shadowMap, shadowSampler, offsetUv, adjustedDepth);
-    blocked = blocked + (1.0 - lit);
+  var samples = 0.0;
+  for (var y = -2; y <= 2; y = y + 1) {
+    for (var x = -2; x <= 2; x = x + 1) {
+      if (abs(x) <= halfWidth && abs(y) <= halfWidth) {
+        let offsetUv = uv + vec2<f32>(f32(x), f32(y)) * texel;
+        let lit = textureSampleCompareLevel(shadowMap, shadowSampler, offsetUv, adjustedDepth);
+        blocked = blocked + (1.0 - lit);
+        samples = samples + 1.0;
+      }
+    }
   }
-  return 1.0 - blocked / 9.0;
+  return 1.0 - blocked / max(samples, 1.0);
 }
 
 // === Cube point-light-shadow wrapper =========================================
@@ -78,7 +142,7 @@ fn sample_shadow_2d(
 // `shadowAtlas` is @group(0) @binding(5) texture_depth_cube_array.
 // `shadowSampler` is @group(0) @binding(4) sampler_comparison (shared with
 // directional shadows — same sampler type, no dimension distinction).
-// `lightLocal` is the fragment-to-light direction vector in the cubemap's
+// `lightLocal` is the light-to-fragment direction vector in the cubemap's
 // coordinate system (Bevy convention: left-handed cubemap; caller applies
 // flip_z = vec3(1,1,-1) to convert right-hand world to left-hand cubemap).
 // `layer` is the cube_array layer index (i32; 0..3 for 4 shadow-casting
@@ -117,4 +181,4 @@ fn sample_shadow_cube_hw2x2(
   // handles face-boundary texel fetches. Returns 1.0 = fully lit, 0.0 = fully
   // shadowed.
   return textureSampleCompareLevel(shadowAtlas, shadowSampler, lightLocal, layer, adjustedDepth);
-}
+}