@forgeax/engine-shader 0.1.20 → 0.1.23

package/src/lighting-punctual.wgsl

@@ -31,8 +31,12 @@
 //   - evalSpot(lightPos, lightDir, colorTimesIntensity, cosInner, cosOuter,
 //              invRangeSquared, ...) -> vec3<f32>
 
-#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
-#import forgeax_pbr::lighting_attenuation::{evalDistanceAttenuation, evalSpotAttenuation}
+#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx, threeR184DirectMultiScatter}
+#import forgeax_pbr::lighting_spot_modifiers::{spotModifierProduct}
+
+// extendedLighting is one closed resource topology for IES, Cookie, and
+// probe factors. The ordinary path supplies identity factors.
+#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).
@@ -78,16 +82,6 @@ fn evalVolumeSpot(
   );
 }
 
-// One projector UV helper is shared by surface and volume. The accepted
-// projectorRevision travels in the host tuple; it is deliberately not a
-// second shader registry or a device-side identity.
-fn projectSpotUv(lightViewProj : mat4x4<f32>, worldPos : vec3<f32>) -> vec2<f32> {
-  let clip = lightViewProj * vec4<f32>(worldPos, 1.0);
-  let invW = select(1.0 / clip.w, 0.0, abs(clip.w) < 1e-6);
-  let projectorUv = vec2<f32>(clip.x * invW * 0.5 + 0.5, clip.y * invW * -0.5 + 0.5);
-  return projectorUv;
-}
-
 // Shared punctual BRDF body returning (diffuse + specular) *
 // colorTimesIntensity * nDotL * attenuation. Cone factor is applied by the
 // caller (evalSpot only).
@@ -112,9 +106,13 @@ fn evalPunctualBody(
   let nDotH = max(dot(normal, h), 0.0);
   let vDotH = max(dot(viewDir, h), 0.0);
   let f = f_schlick(vDotH, F0);
-  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 roughness = sqrt(max(alphaSq, 0.0));
+  let multiScatter = threeR184DirectMultiScatter(roughness, nDotV, nDotL, F0);
+  let specular = d_ggx(nDotH, alphaSq) * v_smith(nDotV, nDotL, alphaSq) * f + multiScatter;
+  // Three r184 direct-light parity keeps diffuse independent of the
+  // view-dependent Schlick term; the metallic factor is the only diffuse
+  // energy gate in this punctual path.
+  let diffuse = (1.0 - metallic) * baseColor / 3.14159265;
   let attenuation = evalDistanceAttenuation(dSquared, invRangeSquared);
   return (diffuse + specular) * colorTimesIntensity * nDotL * attenuation;
 }
@@ -138,6 +136,50 @@ fn evalPoint(
   );
 }
 
+// Flat 2D punctual evaluators share the range/cone math with 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 * 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.
 //
@@ -148,7 +190,8 @@ fn evalPoint(
 // projection (research L0.5 Bevy pattern); the caller passes `near` / `far`
 // directly so both pipelines route the same constants without owning the
 // upstream binding (URP reads them from `shadowParams[layer]` at @group(0)
-// binding 6; HDRP unpacks them off `LightSlot.kind_and_pad.zw` per
+// binding 6; the shared DirectLightSlot metadata remains the identity owner
+// while this shadow-parameter buffer carries the reconstruction constants per
 // plan-strategy §D-8).
 //
 // Caller responsibility: gate this on `shadowAtlasLayer >= 0` so the
@@ -175,13 +218,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 /
@@ -224,9 +267,10 @@ fn evalSpot(
     lightPos, colorTimesIntensity, invRangeSquared,
     worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
   );
-  return body * evalSpotAttenuation(
-    lightPos, lightDir, worldPos, cosInner, cosOuter, invRangeSquared,
-  ) / max(evalDistanceAttenuation(dot(lightPos - worldPos, lightPos - worldPos), invRangeSquared), 1e-4);
+  let toLight = lightPos - worldPos;
+  let l = normalize(toLight);
+  let cone = smoothstep(cosOuter, cosInner, dot(l, -lightDir));
+  return body * spotModifierProduct(1.0, 1.0, cone, 1.0, 1.0, 1.0);
 }
 
 // feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-4 +
@@ -287,10 +331,6 @@ fn evalSpotShadowed(
   let invW = select(1.0 / splane.w, 0.0, abs(splane.w) < 1e-6);
   let clipUv = projectSpotUv(lightViewProj, worldPos);
   let depthRef = splane.z * invW;
-  // The accepted projectorRevision selects the same texture tuple for
-  // surface and volume; a bound projector uses textureSampleLevel here.
-  let projectorRevision = 0.0;
-
   // 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)) {

package/src/lighting-rect-area.wgsl

@@ -0,0 +1,162 @@
+#define_import_path forgeax_pbr::lighting_rect_area
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+#import forgeax_view::common::{ltcLambertTexture, ltcGgxTexture, spotModifierSampler}
+#endif
+
+// One-sided finite-area direct lighting using the same Heitz LTC formulation
+// and tracked 64x64 tables as Three.js r184. The rectangle corners, rather
+// than a punctual center direction, are transformed into the fitted cosine
+// space before the spherical edge integral is evaluated.
+
+fn ltcUv(n : vec3<f32>, v : vec3<f32>, roughness : f32) -> vec2<f32> {
+  let lutScale = 63.0 / 64.0;
+  let lutBias = 0.5 / 64.0;
+  let nDotV = clamp(dot(n, v), 0.0, 1.0);
+  return vec2<f32>(clamp(roughness, 0.0, 1.0), sqrt(1.0 - nDotV)) * lutScale + lutBias;
+}
+
+fn ltcClippedSphereFormFactor(f : vec3<f32>) -> f32 {
+  let magnitude = length(f);
+  return max((magnitude * magnitude + f.z) / (magnitude + 1.0), 0.0);
+}
+
+fn ltcEdgeVectorFormFactor(v1 : vec3<f32>, v2 : vec3<f32>) -> vec3<f32> {
+  let x = clamp(dot(v1, v2), -1.0, 1.0);
+  let y = abs(x);
+  let a = 0.8543985 + (0.4965155 + 0.0145206 * y) * y;
+  let b = 3.4175940 + (4.1616724 + y) * y;
+  let rational = a / b;
+  let thetaOverSinTheta = select(
+    0.5 * inverseSqrt(max(1.0 - x * x, 1e-7)) - rational,
+    rational,
+    x > 0.0,
+  );
+  return cross(v1, v2) * thetaOverSinTheta;
+}
+
+fn ltcEvaluate(
+  n : vec3<f32>,
+  v : vec3<f32>,
+  worldPos : vec3<f32>,
+  mInv : mat3x3<f32>,
+  lightPos : vec3<f32>,
+  axisX : vec3<f32>,
+  axisY : vec3<f32>,
+  halfWidth : f32,
+  halfHeight : f32,
+) -> f32 {
+  let halfX = axisX * halfWidth;
+  let halfY = axisY * halfHeight;
+  // Counter-clockwise from the authored front (+cross(axisX, axisY)).
+  let rect0 = lightPos - halfX - halfY;
+  let rect1 = lightPos + halfX - halfY;
+  let rect2 = lightPos + halfX + halfY;
+  let rect3 = lightPos - halfX + halfY;
+  let lightNormal = cross(rect1 - rect0, rect3 - rect0);
+  if (dot(lightNormal, worldPos - rect0) <= 0.0) {
+    return 0.0;
+  }
+
+  let tangentCandidate = v - n * dot(v, n);
+  let tangentLengthSquared = dot(tangentCandidate, tangentCandidate);
+  var tangent = vec3<f32>(1.0, 0.0, 0.0);
+  if (tangentLengthSquared > 1e-7) {
+    tangent = tangentCandidate * inverseSqrt(tangentLengthSquared);
+  } else {
+    let fallback = select(vec3<f32>(0.0, 1.0, 0.0), vec3<f32>(1.0, 0.0, 0.0), abs(n.x) < 0.9);
+    tangent = normalize(cross(fallback, n));
+  }
+  let bitangent = -cross(n, tangent);
+  let transform = mInv * transpose(mat3x3<f32>(tangent, bitangent, n));
+
+  let c0 = normalize(transform * (rect0 - worldPos));
+  let c1 = normalize(transform * (rect1 - worldPos));
+  let c2 = normalize(transform * (rect2 - worldPos));
+  let c3 = normalize(transform * (rect3 - worldPos));
+  let vectorFormFactor =
+    ltcEdgeVectorFormFactor(c0, c1) +
+    ltcEdgeVectorFormFactor(c1, c2) +
+    ltcEdgeVectorFormFactor(c2, c3) +
+    ltcEdgeVectorFormFactor(c3, c0);
+  return ltcClippedSphereFormFactor(vectorFormFactor);
+}
+
+fn rectAreaRangeFactor(lightPos : vec3<f32>, worldPos : vec3<f32>, invRangeSquared : f32) -> f32 {
+  let toLight = lightPos - worldPos;
+  let distanceSquared = dot(toLight, toLight);
+  let rangeTerm = distanceSquared * invRangeSquared;
+  let factor = clamp(1.0 - rangeTerm * rangeTerm, 0.0, 1.0);
+  return factor * factor;
+}
+
+fn evalRectAreaLtcDiffuse(
+  lightPos : vec3<f32>, lightColor : vec3<f32>, axisX : vec3<f32>, axisY : vec3<f32>,
+  halfWidth : f32, halfHeight : f32, invRangeSquared : f32, worldPos : vec3<f32>,
+  n : vec3<f32>, v : vec3<f32>, baseColor : vec3<f32>, metallic : f32, alphaSq : f32, F0 : vec3<f32>,
+) -> vec3<f32> {
+  let identity = mat3x3<f32>(
+    vec3<f32>(1.0, 0.0, 0.0),
+    vec3<f32>(0.0, 1.0, 0.0),
+    vec3<f32>(0.0, 0.0, 1.0),
+  );
+  let formFactor = ltcEvaluate(
+    n, v, worldPos, identity, lightPos, axisX, axisY, halfWidth, halfHeight,
+  );
+  // The LTC edge fit is already normalized by 1/(2*pi); unlike punctual
+  // irradiance this form factor must not receive another Lambert 1/pi.
+  let diffuse = baseColor * (1.0 - metallic);
+  return lightColor * diffuse * formFactor * rectAreaRangeFactor(lightPos, worldPos, invRangeSquared);
+}
+
+fn evalRectAreaLtcStandard(
+  lightPos : vec3<f32>, lightColor : vec3<f32>, axisX : vec3<f32>, axisY : vec3<f32>,
+  halfWidth : f32, halfHeight : f32, invRangeSquared : f32, worldPos : vec3<f32>,
+  n : vec3<f32>, v : vec3<f32>, baseColor : vec3<f32>, metallic : f32, alphaSq : f32, F0 : vec3<f32>,
+) -> vec3<f32> {
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+  let uv = ltcUv(n, v, sqrt(max(alphaSq, 0.0)));
+  let matrixSample = textureSampleLevel(ltcLambertTexture, spotModifierSampler, uv, 0.0);
+  let fresnelSample = textureSampleLevel(ltcGgxTexture, spotModifierSampler, uv, 0.0);
+  let mInv = mat3x3<f32>(
+    vec3<f32>(matrixSample.x, 0.0, matrixSample.y),
+    vec3<f32>(0.0, 1.0, 0.0),
+    vec3<f32>(matrixSample.z, 0.0, matrixSample.w),
+  );
+  let fresnel = F0 * fresnelSample.x + (vec3<f32>(1.0) - F0) * fresnelSample.y;
+  let specularFormFactor = ltcEvaluate(
+    n, v, worldPos, mInv, lightPos, axisX, axisY, halfWidth, halfHeight,
+  );
+  let diffuse = evalRectAreaLtcDiffuse(
+    lightPos, lightColor, axisX, axisY, halfWidth, halfHeight, invRangeSquared,
+    worldPos, n, v, baseColor, metallic, alphaSq, F0,
+  );
+  return diffuse + lightColor * fresnel * specularFormFactor * rectAreaRangeFactor(lightPos, worldPos, invRangeSquared);
+#else
+  return vec3<f32>(0.0);
+#endif
+}
+
+// Both renderer routes consume one complete Standard-PBR Rect contribution.
+// The public names retain the direct/cluster shader import contract while the
+// Lambert and fitted-GGX terms stay inseparable in one owner implementation.
+fn evalRectAreaLtcLambert(
+  lightPos : vec3<f32>, lightColor : vec3<f32>, axisX : vec3<f32>, axisY : vec3<f32>,
+  halfWidth : f32, halfHeight : f32, invRangeSquared : f32, worldPos : vec3<f32>,
+  n : vec3<f32>, v : vec3<f32>, baseColor : vec3<f32>, metallic : f32, alphaSq : f32, F0 : vec3<f32>,
+) -> vec3<f32> {
+  return evalRectAreaLtcStandard(
+    lightPos, lightColor, axisX, axisY, halfWidth, halfHeight, invRangeSquared,
+    worldPos, n, v, baseColor, metallic, alphaSq, F0,
+  );
+}
+
+fn evalRectAreaLtcGgx(
+  lightPos : vec3<f32>, lightColor : vec3<f32>, axisX : vec3<f32>, axisY : vec3<f32>,
+  halfWidth : f32, halfHeight : f32, invRangeSquared : f32, worldPos : vec3<f32>,
+  n : vec3<f32>, v : vec3<f32>, baseColor : vec3<f32>, metallic : f32, alphaSq : f32, F0 : vec3<f32>,
+) -> vec3<f32> {
+  return evalRectAreaLtcStandard(
+    lightPos, lightColor, axisX, axisY, halfWidth, halfHeight, invRangeSquared,
+    worldPos, n, v, baseColor, metallic, alphaSq, F0,
+  );
+}

package/src/lighting-spot-modifiers.wgsl

@@ -0,0 +1,93 @@
+#define_import_path forgeax_pbr::lighting_spot_modifiers
+
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+#import forgeax_view::common::{spotModifierSampler, iesProfileTexture, cookieTexture, cookieMatrices}
+#endif
+
+// DirectLightSlot.metadata.y carries this marker for the SpotLight projector
+// path. A marked spot samples the shared array with its lightViewProj in the
+// punctual owner, so the Cookie projection
+// below must not modulate it a second time.
+const PROJECTOR_FLAG: u32 = 0x40000000u;
+
+// Shared Spot modifier composition. Identity defaults preserve the ordinary
+// punctual path when an extension resource is absent.
+fn spotModifierProduct(
+  brdf   : f32,
+  range  : f32,
+  cone   : f32,
+  ies    : f32,
+  cookie : f32,
+  shadow : f32,
+) -> f32 {
+  return brdf * range * cone * ies * cookie * shadow;
+}
+
+// Shared IES/Cookie projection owner. The light direction is the authored
+// outgoing axis (light -> scene), matching evalSpot's `dot(L, -lightDir)`.
+// Cookie matrices carry only source-texture aspect correction; keeping the
+// cone term here allows a Cookie slice to be shared by Spots with different
+// outer cones.
+fn spotModifierFactors(
+  lightPos : vec3<f32>,
+  lightDir : vec3<f32>,
+  cosOuter : f32,
+  worldPos : vec3<f32>,
+  rollDeg : f32,
+  metadata : vec4<u32>,
+) -> vec4<f32> {
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+  let toSurface = worldPos - lightPos;
+  let distanceToSurface = length(toSurface);
+  var ies = 1.0;
+  var cookie = vec3<f32>(1.0);
+  if (distanceToSurface <= 0.000001) {
+    return vec4<f32>(ies, cookie);
+  }
+
+  let outgoing = toSurface / distanceToSurface;
+  let forward = normalize(lightDir);
+  var referenceUp = vec3<f32>(0.0, 1.0, 0.0);
+  if (abs(forward.y) > 0.999) {
+    referenceUp = vec3<f32>(0.0, 0.0, 1.0);
+  }
+  let right = normalize(cross(forward, referenceUp));
+  let up = normalize(cross(right, forward));
+  let localX = dot(outgoing, right);
+  let localY = dot(outgoing, up);
+  let depth = dot(outgoing, forward);
+  let roll = rollDeg * 0.01745329252;
+  let rolledX = localX * cos(roll) - localY * sin(roll);
+  let rolledY = localX * sin(roll) + localY * cos(roll);
+
+  if (metadata.z != 0xffffffffu) {
+    let azimuth = (atan2(rolledY, rolledX) + 6.283185307) % 6.283185307;
+    let elevation = acos(clamp(depth, -1.0, 1.0)) / 3.14159265;
+    let iesUv = vec2<f32>(azimuth / 6.283185307, elevation);
+    ies = max(textureSampleLevel(iesProfileTexture, spotModifierSampler, iesUv, metadata.z, 0.0).r, 0.0);
+  }
+
+  if (metadata.w != 0xffffffffu && (metadata.y & PROJECTOR_FLAG) == 0u) {
+    if (depth <= 0.0) {
+      cookie = vec3<f32>(0.0);
+    } else {
+      let sinOuter = sqrt(max(1.0 - cosOuter * cosOuter, 0.0));
+      let tanOuter = sinOuter / max(cosOuter, 0.0001);
+      let matrixPlane = cookieMatrices[metadata.w] * vec4<f32>(rolledX / depth, rolledY / depth, 0.0, 1.0);
+      let cookieUv = vec2<f32>(0.5) + matrixPlane.xy / tanOuter * 0.5;
+      if (
+        cookieUv.x < 0.0 || cookieUv.x > 1.0 ||
+        cookieUv.y < 0.0 || cookieUv.y > 1.0
+      ) {
+        cookie = vec3<f32>(0.0);
+      } else {
+        let cookieSample = textureSampleLevel(cookieTexture, spotModifierSampler, cookieUv, metadata.w, 0.0);
+        cookie = max(cookieSample.rgb * cookieSample.a, vec3<f32>(0.0));
+      }
+    }
+  }
+  return vec4<f32>(ies, cookie);
+#else
+  return vec4<f32>(1.0);
+#endif
+}

package/src/ltc/provenance.ts

@@ -0,0 +1,19 @@
+// @forgeax/engine-shader - provenance for the tracked RectArea LTC tables.
+
+/**
+ * The table source is the Three.js r184 RectAreaLight implementation. The
+ * source arrays are converted to IEEE-754 binary16 offline and checked into
+ * `tables.ts`; the runtime never fetches or parses a source file.
+ */
+export const LTC_SOURCE_PROVENANCE = {
+  source: 'Three.js',
+  revision: 'r184',
+  sourceUrl:
+    'https://github.com/mrdoob/three.js/blob/r184/examples/jsm/lights/RectAreaLightTexturesLib.js',
+  upstreamData: 'selfshadow/ltc_code fit/results/ltc.js',
+  generator: 'deterministic Three.js source-array to rgba16float conversion',
+  inputSha256: {
+    lambert: 'cf5cf21e5c112d2095c7e2418cb0a1ac54636e275d73e42f3453646c67f26814',
+    ggx: '3b1b09080b26104498db277c14fc1733786465c6958e7a8403d688b1e24c2ff5',
+  },
+} as const;