@forgeax/engine-shader 0.1.21 → 0.1.23

package/src/common.wgsl

@@ -142,13 +142,10 @@ fn ditherUnorm8(value : vec3<f32>, pixelPosition : vec2<f32>) -> vec3<f32> {
 // the per-spot perspective `spotLightViewProj` matrices (4 lanes, fragment-read)
 // fold into the View UBO tail instead of a standalone @group(0) binding 9
 // uniform buffer. The standalone binding pushed the fragment-stage uniform
-// buffer count to 12 (view + pointLights + spotLights + shadowParams +
-// shadowCasterCascade + spotLightViewProj on the WebGL2 fallback path),
-// exceeding GLES 3.0's `max_uniform_buffers_per_shader_stage = 11` so the
-// WebGL2 fallback (mobile / WebKit — this feat's compat target) crashed
-// pipeline-layout creation. Folding into the View UBO costs zero new bindings
-// (the count drops back to 11). D-1 rejected the View UBO for the CASTER vertex
-// channel (binding 7) because directional + spot casters both need a light-view
+// buffer count to 12 before the local-light arrays were removed. The current
+// view declares no point/spot light arrays; the spot matrices remain folded
+// into the View UBO with no standalone binding. D-1 rejected the View UBO for
+// the CASTER vertex channel (binding 7) because directional + spot casters both need a light-view
 // matrix in the same frame (same-frame write contention); the FRAGMENT read
 // channel has no such contention — the host writes all <=4 spot matrices once
 // per frame before the forward pass, so the fold is safe. mat4 array align=16:
@@ -207,12 +204,22 @@ struct Mesh {
 #endif
 };
 
+// Retained CPU ProbeBlendRecord ABI: 4 scalar lanes plus 9 vec4 lanes = 160 B.
+// The last lane carries padding for the 27 f32 SH coefficients. Sky residual
+// is derived in lighting-probe.wgsl, never stored as a second fraction.
+struct ProbeBlendRecord {
+  objectKey         : f32,
+  generation        : f32,
+  localBlendFraction : f32,
+  flags             : f32,
+  shPreblend        : array<vec4<f32>, 9>,
+};
+
 // feat-20260519-light-casters-point-spot-pbr M4 / w21 (D-S1 + D-S2 +
 // AC-04 b/c + AC-05 binding declaration). Punctual-light std430 storage
-// types byte-for-byte mirror packPointLight / packSpotLight in
-// `packages/runtime/src/light-buffer-layout.ts`:
+// types use the shared five-row host ABI in `light-buffer-layout.ts`:
 //
-//   PointLight (32 B / 8 floats):
+//   Point/Spot/Rect direct slot (80 B / 20 u32-or-float lanes):
 //     [ 0..2 ] position vec3<f32>
 //     [   3 ] invRangeSquared f32 (Bevy color_inverse_square_range.w; 0
 //             collapses range falloff to a pure 1/d^2 inverse-square law)
@@ -220,7 +227,7 @@ struct Mesh {
 //             color * intensity so the shader avoids the per-fragment mul)
 //     [   7 ] pad f32 = 0
 //
-//   SpotLight (80 B / 20 floats):
+//   The metadata row carries kind, shadow, IES, and Cookie identities.
 //     [ 0..2 ] position vec3<f32>
 //     [   3 ] invRangeSquared f32
 //     [ 4..6 ] colorTimesIntensity vec3<f32>
@@ -229,81 +236,31 @@ struct Mesh {
 //     [ 8..10] direction vec3<f32> (raw outgoing vector; shader reads
 //             via dot(L, -direction) for cone angle test)
 //     [  11 ] cosOuter f32
-//     [12] depthBias f32, [13] normalBias f32, [14] pcfKernelSize f32
-//     [  15 ] shadowAtlasTile i32 (sentinel -1 = unassigned/clipped,
-//             0..3 = spot atlas tile index; feat-20260625 M2/M3 D-4)
-//     [  16 ] shadowIntensity f32 (fraction of sampled shadow to apply)
-//     [17..19] alignment tail padding
+//     Spot row 3: [12] depthBias, [13] normalBias, [14] shadowIntensity,
+//     [15] rollDeg. The unified slot has no separate pcf lane; the current
+//     surface and volume receivers use the stable PCF3 profile.
+//     Rect row 1/2/3: halfWidth, axisY + halfHeight, axisX + zero pad. The
+//     final metadata row carries the kind,
+//     shadow, IES, and Cookie identities.
 //
 // WGSL std430 alignment audit: vec3<f32> alignof=16 / sizeof=12. The
 // f32 lane wedged immediately after each vec3 fills the 4 B remainder
 // (WGSL struct member rule: next.offset = roundUp(prev.offset +
 // prev.size, this.alignof) - for f32 alignof=4 the round-up is a
 // no-op, so position[3] / color[3] / direction[3] sit at byte
-// offsets 12 / 28 / 44 with zero internal padding). PointLight stays
-// 32 B; SpotLight grows from 64 B (feat-20260625 M2/M3 D-4) for the three
-// receiver controls plus `shadowAtlasTile: i32`, then to 80 B for the
-// parity-only `shadowIntensity` lane at byte 64. These struct sizes match the
-// host packers (packPointLight 32 B / packSpotLight 80 B) exactly.
+// offsets 12 / 28 / 44 with zero internal padding). Point, Spot, and Rect all
+// use the unified 80 B host packer; this shared slot is the sole local-light
+// carrier.
 //
-// Header `count: u32` lives in a wrapper struct with the trailing
-// runtime-sized array. Array-of-vec4-aligned-struct alignof = 16, so
-// `slots` starts at byte 16 (count u32 occupies 0..4; bytes 4..16 are
-// implicit padding). This matches `packLightArrayHeader`'s 16 B
-// (count u32 + 12 B pad) layout in light-buffer-layout.ts.
-
-struct PointLight {
-  position            : vec3<f32>,
-  invRangeSquared     : f32,
-  colorTimesIntensity : vec3<f32>,
-  // feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-8 (plan-strategy §D-2):
-  // Repurposes the prior `pointPadW` (f32 zero-pad) lane as `shadowAtlasLayer`
-  // (i32 sentinel, -1 = no shadow, 0..3 = cube_array atlas layer index for
-  // shadow-casting point lights). Cap = 4 enforced by the PointLightShadow
-  // ECS component cardinality. The shader path samples the cube_array atlas
-  // (binding 5) only when `shadowAtlasLayer >= 0`. Field name is unique to
-  // this struct (no `pad0`/`pad1` collision with the pbr Material struct
-  // under naga_oil writeback substitution).
-  shadowAtlasLayer    : i32,
-};
-
-struct SpotLight {
-  position            : vec3<f32>,
-  invRangeSquared     : f32,
-  colorTimesIntensity : vec3<f32>,
-  cosInner            : f32,
-  direction           : vec3<f32>,
-  cosOuter            : f32,
-  // feat-20260625-spot-light-shadow-mapping M3 / w13 (plan-strategy D-4):
-  // The trailing vec4 transports receiver controls and the tile identity.
-  // Host packSpotLight writes slots 12..14 from the same snapshot; slot 15 is
-  // the i32 shadow tile sentinel and slot 16 carries shadowIntensity.
-  depthBias           : f32,
-  normalBias          : f32,
-  pcfKernelSize       : f32,
-  shadowAtlasTile     : i32,
-  shadowIntensity     : f32,
-};
-
-struct PointLightsArray {
-  count : u32,
-  slots : array<PointLight, 4>,
-};
-
-struct SpotLightsArray {
-  count : u32,
-  slots : array<SpotLight, 4>,
+struct DirectLightSlot {
+  position            : vec4<f32>, // row0: position + inverse range
+  colorTimesIntensity : vec4<f32>, // row1: color + first angular fact
+  direction           : vec4<f32>, // row2: primary axis + second angular fact
+  auxiliary           : vec4<f32>, // row3: auxiliary Rect axis
+  metadata : vec4<u32>,
 };
 
 @group(0) @binding(0) var<uniform> view : View;
-
-#if STORAGE_BUFFER_AVAILABLE == true
-@group(0) @binding(1) var<storage, read> pointLightsBuffer : PointLightsArray;
-@group(0) @binding(2) var<storage, read> spotLightsBuffer  : SpotLightsArray;
-#else
-@group(0) @binding(1) var<uniform> pointLightsBuffer : PointLightsArray;
-@group(0) @binding(2) var<uniform> spotLightsBuffer  : SpotLightsArray;
-#endif
 // feat-20260520-directional-light-shadow-mapping M3 / w16 (D-1 / plan-strategy §8.1):
 // shadowMap + shadowSampler consume @group(0) bindings 3/4 (smallest unused
 // slots adjacent to view UBO at 0). M3 uses 3x3 PCF with textureLoad on
@@ -314,7 +271,7 @@ struct SpotLightsArray {
 // layers=4, depth32float; one cube per shadow-casting point light, cap=4).
 // Binding 6 declares the per-light shadow params buffer (URP only — proj
 // constants for cube depth-ref reconstruction); HDRP rides the same constants
-// on LightSlot pad lanes (.kind_and_pad.wyz) so binding 6 stays unbound on
+// on direct-light metadata so binding 6 stays unbound on
 // the HDRP path. Sample-time gating by PointLight.shadowAtlasLayer >= 0.
 @group(0) @binding(3) var shadowMap       : texture_depth_2d;
 @group(0) @binding(4) var shadowSampler   : sampler_comparison;
@@ -337,7 +294,7 @@ struct SpotLightsArray {
 //   depth-ref reconstruction (research L0.5 + L1.13). Each lane stores the
 //   shader-side reconstruction constants for one shadow-casting point light;
 //   slot N matches `PointLight.shadowAtlasLayer = N`. HDRP rides the same
-//   constants on `LightSlot.kind_and_pad.wyz` so binding 6 stays unbound on
+//   constants on direct-light metadata so binding 6 stays unbound on
 //   the HDRP path.
 #ifdef POINT_SHADOW_AVAILABLE
 @group(0) @binding(5) var shadowAtlas : texture_depth_cube_array;
@@ -410,6 +367,23 @@ struct ShadowCasterCascade {
 // — folded there in feat-20260625 w25 (scope-amend) to keep the WebGL2 fallback
 // fragment uniform-buffer count <= 11; binding 8 is the last view-BG binding.
 @group(0) @binding(8) var spotShadowMap : texture_depth_2d;
+// Extended-lighting resources are a real optional view topology.  The
+// renderer selects the matching material variant and BGL together; keeping
+// these declarations behind the same axis prevents a no-extension variant
+// from consuming texture budget or requiring absent bindings.
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+@group(0) @binding(9) var spotModifierSampler : sampler;
+@group(0) @binding(11) var iesProfileTexture : texture_2d_array<f32>;
+@group(0) @binding(12) var cookieTexture : texture_2d_array<f32>;
+@group(0) @binding(13) var ltcLambertTexture : texture_2d<f32>;
+@group(0) @binding(14) var ltcGgxTexture : texture_2d<f32>;
+// One aspect-correction matrix per Cookie array slice. The matrix is kept in
+// the shared view group so the same projected Cookie semantics are available
+// to both the ordinary and clustered Standard PBR consumers.
+@group(0) @binding(15) var<uniform> cookieMatrices : array<mat4x4<f32>, 32>;
+#endif
+#ifdef PROJECTOR_AVAILABLE
+#ifndef EXTENDED_LIGHTING_AVAILABLE
 // Optional authored SpotLight projector. Surface and volume bind the same
 // accepted TextureAsset view and linear-clamp sampler; an unprojected spot
 // receives the renderer-owned white fallback. The declaration is capability
@@ -417,10 +391,10 @@ struct ShadowCasterCascade {
 // minimum of 16 sampled textures without this optional cookie. Devices that
 // cannot expose the 17th sampled texture select the matching white-projector
 // shader variant and omit these resources from the view BGL.
-#ifdef PROJECTOR_AVAILABLE
 @group(0) @binding(11) var projectorTexture : texture_2d<f32>;
 @group(0) @binding(12) var projectorSampler : sampler;
 #endif
+#endif
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(2) @binding(0) var<storage, read> meshes : array<Mesh>;
 #else

package/src/default-standard-pbr-skin.wgsl

@@ -1,8 +1,9 @@
-#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, sampleMaterialTexture}
+#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, shadowMap, shadowSampler, sampleMaterialTexture}
 #import forgeax_scene_temporal::{sceneViewZ}
 #import forgeax_pbr::temporal::{projectPbrSceneTemporal}
 #import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
 #import forgeax_pbr::ibl_sampling::{sampleIblDiffuse, sampleIblSpecular}
+#import forgeax_pbr::lighting_probe::{evaluateProbeDiffuse}
 #import forgeax_pbr::tbn::{decodeTangentSpaceNormalRg, scaleTangentSpaceNormal, applyTBN}
 #import forgeax_pbr::lighting_directional::{evalDirectionalNoShadow, evalDirectionalShadowFactor}
 #ifdef CLUSTER_FORWARD_AVAILABLE
@@ -13,6 +14,9 @@
 #pragma variant_axis STORAGE_BUFFER_AVAILABLE
 #pragma variant_axis CLUSTER_FORWARD_AVAILABLE
 #pragma variant_axis VERTEX_COLOR_AVAILABLE
+#pragma variant_axis PROBE_BLEND_AVAILABLE
+#pragma variant_axis EXTENDED_LIGHTING_AVAILABLE
+
 #pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE
 
 // @forgeax/engine-shader - default-standard-pbr-skin.wgsl
@@ -171,14 +175,36 @@ struct SkylightUniforms {
 @group(1) @binding(22) var brdfLutSampler       : sampler;
 @group(1) @binding(23) var<uniform> skylight    : SkylightUniforms;
 
-#if STORAGE_BUFFER_AVAILABLE == true
-@group(2) @binding(1) var<storage, read> palette : array<mat4x4<f32>>;
-@group(2) @binding(2) var<storage, read> previousPalette : array<mat4x4<f32>>;
+#ifdef PROBE_BLEND_AVAILABLE
+// Optional consumer lane. The host must provide the retained 160B record
+// buffer and matching BGL before enabling this capability.
+@group(3) @binding(1) var<storage, read> probeBlendRecords : array<vec4<f32>>;
+#endif
+
+#ifdef STORAGE_BUFFER_AVAILABLE
+@group(2) @binding(1) var<storage, read> paletteStorage : array<mat4x4<f32>>;
+@group(2) @binding(2) var<storage, read> previousPaletteStorage : array<mat4x4<f32>>;
 #else
-@group(2) @binding(1) var<uniform> palette : array<mat4x4<f32>, 255>;
-@group(2) @binding(2) var<uniform> previousPalette : array<mat4x4<f32>, 255>;
+@group(2) @binding(1) var<uniform> paletteUniform : array<mat4x4<f32>, 255>;
+@group(2) @binding(2) var<uniform> previousPaletteUniform : array<mat4x4<f32>, 255>;
 #endif
 
+fn skinPalette(index : u32) -> mat4x4<f32> {
+#ifdef STORAGE_BUFFER_AVAILABLE
+  return paletteStorage[index];
+#else
+  return paletteUniform[index];
+#endif
+}
+
+fn previousSkinPalette(index : u32) -> mat4x4<f32> {
+#ifdef STORAGE_BUFFER_AVAILABLE
+  return previousPaletteStorage[index];
+#else
+  return previousPaletteUniform[index];
+#endif
+}
+
 struct VsIn  {
   @location(0) pos     : vec3<f32>,
   @location(1) normal  : vec3<f32>,
@@ -232,8 +258,7 @@ fn pick_channel(rgba : vec4<f32>, channelIndex : u32) -> f32 {
   }
 }
 
-@vertex
-fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+fn vs_main_impl(in : VsIn, idx : u32) -> VsOut {
   // 4-bone weighted skinning (plan-strategy D-3 / D-3a).
   // The host pre-computes each joint matrix as worldFromJoint * inverseBindMatrix
   // (CPU-side pre-multiplication, per D-4) and writes them into the palette
@@ -245,10 +270,10 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   // The host sets the BindGroup dynamic offset to (byteOffset / 64) so the
   // first palette entry visible to this draw is palette[0]. The shader
   // indexes into palette directly using the per-vertex skinIndex values.
-  let skinMatrix = palette[in.skinIndex.x] * in.skinWeight.x +
-    palette[in.skinIndex.y] * in.skinWeight.y +
-    palette[in.skinIndex.z] * in.skinWeight.z +
-    palette[in.skinIndex.w] * in.skinWeight.w;
+  let skinMatrix = skinPalette(in.skinIndex.x) * in.skinWeight.x +
+    skinPalette(in.skinIndex.y) * in.skinWeight.y +
+    skinPalette(in.skinIndex.z) * in.skinWeight.z +
+    skinPalette(in.skinIndex.w) * in.skinWeight.w;
 
   // glTF 2.0 sec.Skins Implementation Note: when a mesh node has a skin
   // property, the joint matrices already encode the global transform of each
@@ -260,7 +285,7 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   // skinnedLocal IS the world position -- no additional left-multiply by
   // meshes[0].worldFromLocal or instanceLocal is needed.
   //
-  // This removes the implicit contract "Skin entity Transform.world must be
+  // This removes the implicit contract "Skin entity GlobalTransform.world must be
   // identity" -- a skin entity can be parented under any Transform chain and
   // the skinned mesh will rigidly follow via joint propagation alone.
   let skinnedLocal = skinMatrix * vec4<f32>(in.pos, 1.0);
@@ -312,6 +337,16 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   return out;
 }
 
+@vertex
+fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  return vs_main_impl(in, idx);
+}
+
+@vertex
+fn vs_scene_index(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  return vs_main_impl(in, idx);
+}
+
 fn transformedMaterialUv(transform : vec4<f32>, metadata : vec4<f32>, in : VsOut) -> vec2<f32> {
   var source = in.uv;
   if (metadata.x >= 1.0) { source = in.uv1; }
@@ -383,16 +418,34 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
     prefilterMap, prefilterSampler, brdfLut, brdfLutSampler,
   );
   let skyColor = vec3<f32>(skylight.colorR, skylight.colorG, skylight.colorB);
+  let skyFactor = skyColor * skylight.intensity;
   var ambient = (kD * irradiance * albedo + specularIbl) * (vec3<f32>(1.0) - coatF);
+#ifdef PROBE_BLEND_AVAILABLE
+  // group(3) is the per-object bind group; record zero is the object selected
+  // by this draw, independent of instance count.
+  let probeShPreblend = array<vec4<f32>, 9>(
+    probeBlendRecords[1], probeBlendRecords[2], probeBlendRecords[3],
+    probeBlendRecords[4], probeBlendRecords[5], probeBlendRecords[6],
+    probeBlendRecords[7], probeBlendRecords[8], probeBlendRecords[9],
+  );
+  let probeLocalBlendFraction = probeBlendRecords[0].z;
+  let probeDiffuseK = kD / max(vec3<f32>(1.0 - metallic), vec3<f32>(0.0001));
+  let probeDiffuse = evaluateProbeDiffuse(probeShPreblend, probeLocalBlendFraction, n, irradiance * skyFactor, probeDiffuseK, albedo, metallic);
+  ambient = (probeDiffuse + specularIbl * skyFactor) * (vec3<f32>(1.0) - coatF);
+#endif
   if (material.clearcoat != 0.0) {
     let clearcoatIbl = sampleIblSpecular(
       n, v, coatRoughness, vec3<f32>(0.04),
       skylight.rotation,
       prefilterMap, prefilterSampler, brdfLut, brdfLutSampler,
     );
-    ambient = ambient + clearcoatIbl * material.clearcoat;
+    ambient = ambient + clearcoatIbl * material.clearcoat * skyFactor;
   }
-  ambient = ambient * skyColor * skylight.intensity;
+#ifdef PROBE_BLEND_AVAILABLE
+  ambient = ambient;
+#else
+  ambient = ambient * skyFactor;
+#endif
   var color = ambient;
   let directionalShadow = evalDirectionalShadowFactor(n, in.worldPos, in.viewZ);
   let directionalBase = evalDirectionalNoShadow(n, v, albedo, metallic, a, f0);
@@ -437,14 +490,14 @@ struct TemporalVsOut {
 
 @vertex
 fn vs_temporal(in : VsIn, @builtin(instance_index) idx : u32) -> TemporalVsOut {
-  let currentSkin = palette[in.skinIndex.x] * in.skinWeight.x +
-    palette[in.skinIndex.y] * in.skinWeight.y +
-    palette[in.skinIndex.z] * in.skinWeight.z +
-    palette[in.skinIndex.w] * in.skinWeight.w;
-  let previousSkin = previousPalette[in.skinIndex.x] * in.skinWeight.x +
-    previousPalette[in.skinIndex.y] * in.skinWeight.y +
-    previousPalette[in.skinIndex.z] * in.skinWeight.z +
-    previousPalette[in.skinIndex.w] * in.skinWeight.w;
+  let currentSkin = skinPalette(in.skinIndex.x) * in.skinWeight.x +
+    skinPalette(in.skinIndex.y) * in.skinWeight.y +
+    skinPalette(in.skinIndex.z) * in.skinWeight.z +
+    skinPalette(in.skinIndex.w) * in.skinWeight.w;
+  let previousSkin = previousSkinPalette(in.skinIndex.x) * in.skinWeight.x +
+    previousSkinPalette(in.skinIndex.y) * in.skinWeight.y +
+    previousSkinPalette(in.skinIndex.z) * in.skinWeight.z +
+    previousSkinPalette(in.skinIndex.w) * in.skinWeight.w;
   let currentWorld = currentSkin * vec4<f32>(in.pos, 1.0);
   let previousWorld = previousSkin * vec4<f32>(in.pos, 1.0);
   var out : TemporalVsOut;
@@ -481,6 +534,10 @@ fn temporalVertexAlpha(in : TemporalVsOut) -> f32 {
 
 @fragment
 fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
+  var reactive = 0.0;
+#ifdef STORAGE_BUFFER_AVAILABLE
+  reactive = meshes[0].temporal.x;
+#endif
   return projectPbrSceneTemporal(
     material.baseColor.a * temporalVertexAlpha(in),
     material.alphaCutoff,