@forgeax/engine-shader 0.1.23 → 0.1.25

package/src/material/physical/anisotropy.wgsl

@@ -0,0 +1,26 @@
+#define_import_path forgeax_pbr::anisotropy
+
+// Engine-owned anisotropy helpers.  The root contract supplies strength and
+// rotation; the map (when present) supplies tangent direction in RG and a
+// strength multiplier in B.  Keeping the frame operation here means the
+// Standard evaluator and custom Surface share one deterministic seam.
+fn evaluateAnisotropicNormal(
+  normal : vec3<f32>,
+  tangent : vec4<f32>,
+  strength : f32,
+  rotation : f32,
+  direction : vec2<f32>,
+) -> vec3<f32> {
+  let frameTangent = normalize(tangent.xyz);
+  let handedBitangent = normalize(cross(normal, frameTangent)) * select(-1.0, 1.0, tangent.w >= 0.0);
+  var mapDirection = vec2<f32>(1.0, 0.0);
+  if (dot(direction, direction) >= 1e-6) {
+    mapDirection = normalize(direction);
+  }
+  let mappedTangent = normalize(frameTangent * mapDirection.x + handedBitangent * mapDirection.y);
+  let mappedBitangent = normalize(cross(normal, mappedTangent)) * select(-1.0, 1.0, tangent.w >= 0.0);
+  let axis = normalize(mappedTangent * cos(rotation) + mappedBitangent * sin(rotation));
+  // A bounded bent normal preserves the zero-strength isotropic path while
+  // moving only the base specular highlight for non-zero anisotropy.
+  return normalize(normal + axis * clamp(strength, -0.999, 0.999) * 0.35);
+}

package/src/material/physical/clearcoat.wgsl

@@ -0,0 +1,24 @@
+#define_import_path forgeax_pbr::clearcoat
+
+// Clearcoat is the terminal physical layer. Its Fresnel term owns both the
+// attenuation of lower layers and the weight of the coat radiance.
+// The root supplies clearcoatRoughness and clearcoatNormalScale after their
+// texture projections; this module deliberately owns only layer energy.
+fn evaluateClearcoatFresnel(viewCosine : f32, clearcoatFactor : f32) -> f32 {
+  let cosine = clamp(viewCosine, 0.0, 1.0);
+  let oneMinusCosine = 1.0 - cosine;
+  let dielectricFresnel = 0.04 + 0.96 * oneMinusCosine * oneMinusCosine *
+    oneMinusCosine * oneMinusCosine * oneMinusCosine;
+  return clamp(clearcoatFactor, 0.0, 1.0) * dielectricFresnel;
+}
+
+fn evaluateClearcoatLayer(
+  baseRadiance : vec3<f32>,
+  coatRadiance : vec3<f32>,
+  viewCosine : f32,
+  clearcoatFactor : f32,
+) -> vec3<f32> {
+  let fresnel = evaluateClearcoatFresnel(viewCosine, clearcoatFactor);
+  let attenuatedBase = baseRadiance * (1.0 - fresnel);
+  return attenuatedBase + coatRadiance * fresnel;
+}

package/src/material/physical/iridescence.wgsl

@@ -0,0 +1,23 @@
+#define_import_path forgeax_pbr::iridescence
+
+// Bounded RGB thin-film Fresnel approximation.  Thickness is deliberately
+// not clamped to min/max order: the glTF contract permits inverted bounds and
+// the caller supplies the authored interval verbatim.
+fn evaluateIridescenceFresnel(
+  baseF0 : vec3<f32>,
+  strength : f32,
+  filmIor : f32,
+  thicknessNanometres : f32,
+) -> vec3<f32> {
+  let safeStrength = clamp(strength, 0.0, 1.0);
+  let safeIor = max(filmIor, 1.0);
+  let base = clamp((safeIor - 1.0) / (safeIor + 1.0), 0.0, 1.0);
+  let phase = thicknessNanometres * 0.018;
+  let spectral = vec3<f32>(
+    0.5 + 0.5 * cos(phase),
+    0.5 + 0.5 * cos(phase + 2.0943952),
+    0.5 + 0.5 * cos(phase + 4.1887903),
+  );
+  let film = clamp(vec3<f32>(base) * spectral, vec3<f32>(0.0), vec3<f32>(1.0));
+  return clamp(mix(baseF0, film, safeStrength), vec3<f32>(0.0), vec3<f32>(1.0));
+}

package/src/material/physical/sheen.wgsl

@@ -0,0 +1,17 @@
+#define_import_path forgeax_pbr::sheen
+
+// Charlie-like grazing lobe approximation with explicit energy compensation.
+// It is evaluated below clearcoat, so the caller attenuates this result when
+// the top coat Fresnel is applied.
+fn evaluateSheenLayer(
+  baseRadiance : vec3<f32>,
+  sheenColor : vec3<f32>,
+  sheenRoughness : f32,
+  viewCosine : f32,
+) -> vec3<f32> {
+  let roughness = clamp(sheenRoughness, 0.04, 1.0);
+  let grazing = pow(1.0 - clamp(viewCosine, 0.0, 1.0), 2.0);
+  let lobe = grazing * (1.0 - 0.5 * roughness);
+  let energy = clamp(max(max(sheenColor.r, sheenColor.g), sheenColor.b), 0.0, 1.0);
+  return baseRadiance * (1.0 - energy * lobe * 0.5) + sheenColor * lobe;
+}

package/src/material/standard-physical-layer.wgsl

@@ -0,0 +1,12 @@
+#define_import_path forgeax_material::standard_physical_layer
+
+// Engine-owned physical layer facts are selected from the root StandardLayerPlan.
+// Surface modules only produce base SurfaceData and never own this interface.
+// The Standard template owns the facts struct; this module supplies the one
+// physical evaluator body when the clearcoat plan is present.
+fn evaluate_standard_physical_layer() -> StandardPhysicalLayerFacts {
+  return StandardPhysicalLayerFacts(
+    clamp(material.clearcoat, 0.0, 1.0),
+    clamp(material.clearcoatRoughness, 0.04, 1.0),
+  );
+}

package/src/material-schemas.ts

@@ -1,4 +1,8 @@
 import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import {
+  STANDARD_MATERIAL_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_PARAMETER_NAMES,
+} from '@forgeax/engine-types';
 import {
   createStandardPbrArtifactReceipt,
   type MaterialShaderArtifactReceipt,
@@ -7,36 +11,67 @@ import {
 export const STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
 
 /** Shared material contract for the standard PBR and skinned PBR shaders. */
-export const DEFAULT_STANDARD_PBR_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
-  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
-  { name: 'metallic', type: 'f32', default: 0 },
-  { name: 'roughness', type: 'f32', default: 0.5 },
-  { name: 'metallicChannel', type: 'f32', default: 2 },
-  { name: 'roughnessChannel', type: 'f32', default: 1 },
-  { name: 'aoChannel', type: 'f32', default: 0 },
-  { name: 'extraChannel', type: 'f32', default: 0 },
-  { name: 'emissive', type: 'vec3', colorSpace: 'srgb', default: [0, 0, 0] },
-  { name: 'emissiveIntensity', type: 'f32', default: 0 },
-  { name: 'occlusionStrength', type: 'f32', default: 1 },
-  { name: 'alphaCutoff', type: 'f32', default: STANDARD_PBR_ALPHA_CUTOFF_DEFAULT },
-  { name: 'clearcoat', type: 'f32', default: 0 },
-  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
-  { name: 'specularTint', type: 'vec3', colorSpace: 'srgb', default: [1, 1, 1] },
-  { name: 'normalScale', type: 'f32', default: 1 },
-  { name: 'transmission', type: 'f32', default: 0 },
-  { name: 'ior', type: 'f32', default: 1.5 },
-  { name: 'thickness', type: 'f32', default: 0 },
-  { name: 'attenuationColor', type: 'vec3', colorSpace: 'linear', default: [1, 1, 1] },
-  { name: 'attenuationDistance', type: 'f32' },
-  { name: 'baseColorTexture', type: 'texture2d' },
-  { name: 'metallicRoughnessTexture', type: 'texture2d' },
-  { name: 'normalTexture', type: 'texture2d' },
-  { name: 'specularTintTexture', type: 'texture2d' },
-  { name: 'emissiveTexture', type: 'texture2d' },
-  { name: 'occlusionTexture', type: 'texture2d' },
-  { name: 'transmissionTexture', type: 'texture2d' },
-  { name: 'thicknessTexture', type: 'texture2d' },
-];
+export const DEFAULT_STANDARD_PBR_PARAM_SCHEMA = STANDARD_MATERIAL_PARAM_SCHEMA;
+
+export type { StandardPhysicalTextureField } from '@forgeax/engine-types';
+/**
+ * Backward-compatible export name for callers that need the physical
+ * projection.  Every entry is selected from the Standard root schema above;
+ * no independent defaults or binding inventory can drift from it.
+ */
+/**
+ * Stable physical texture injection order.  The order is part of the
+ * Standard template's resource ABI and is derived from the root schema by
+ * `standardPhysicalTextureFields`; render/cook must not maintain another
+ * field inventory.
+ */
+export {
+  STANDARD_PHYSICAL_TEXTURE_FIELDS,
+  standardPhysicalTextureFields,
+} from '@forgeax/engine-types';
+
+export const STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA: readonly ParamSchemaEntry[] =
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter((entry) =>
+    STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name),
+  );
+
+/**
+ * Canonical static Standard entry.  It deliberately contains only the base
+ * contract (including the specular extension) so a base-only material keeps
+ * its Deferred path and carries no second-stage physical resources.
+ */
+export const STANDARD_BASE_PARAM_SCHEMA: readonly ParamSchemaEntry[] =
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+    (entry) =>
+      !STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) &&
+      ![
+        'transmission',
+        'thickness',
+        'attenuationColor',
+        'attenuationDistance',
+        'transmissionTexture',
+        'thicknessTexture',
+      ].includes(entry.name),
+  );
+
+/**
+ * Canonical boot-time user region for the shared Standard material BGL.
+ *
+ * It is still a projection of the root schema, but unlike the author-facing
+ * base-only projection it retains the pre-existing transmission texture pair.
+ * The template reserves those two pairs before the IBL/backdrop injection so
+ * a base-only shader and a transmissive shader can share one boot layout;
+ * physical texture pairs are never included here and are appended only for a
+ * root contract that declares them.
+ */
+export const STANDARD_PIPELINE_PARAM_SCHEMA: readonly ParamSchemaEntry[] =
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+    // The canonical Standard UBO keeps every numeric root coordinate,
+    // including the physical-layer tail. Physical map pairs are engine-owned
+    // resources and are injected after the stable user region.
+    (entry) =>
+      !(STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) && entry.type.startsWith('texture')),
+  );
 
 /** The single producer receipt shared by direct and scene-index Standard PBR. */
 export const STANDARD_PBR_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt =

package/src/register-default-standard-pbr-skin.ts

@@ -13,7 +13,7 @@
 //   - R-10: paramSchema reuses default-standard-pbr schema (same params)
 
 import type { ShaderRegistry } from './index.js';
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from './material-schemas.js';
+import { STANDARD_PIPELINE_PARAM_SCHEMA } from './material-schemas.js';
 
 /**
  * paramSchema for forgeax::pbr-skin — mirrors default-standard-pbr 8 fields.
@@ -69,6 +69,6 @@ export function registerDefaultStandardPbrSkin(
   void caps;
   registry.installMaterialArtifact(RESERVED_ID, {
     source: composedWgsl,
-    paramSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+    paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
   });
 }

package/src/shadow_caster.wgsl

@@ -1,10 +1,16 @@
 #pragma variant_axis STORAGE_BUFFER_AVAILABLE
 #pragma variant_axis SKINNING_DISABLED
+#pragma material_slot surface
+#define_import_path forgeax::default-shadow-caster
+#import forgeax_material::slot::surface::{evaluate_surface}
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+#import forgeax_material::parameters::{material}
 
 // @forgeax/engine-shader shadow_caster.wgsl
 // feat-20260520-directional-light-shadow-mapping M1c / w9 (D-9 / AC-09):
-// vertex-only depth pass for directional shadow map. No fragment stage --
-// the GPU writes depth automatically from gl_Position.z (depth32float RT).
+// depth pass for directional shadow map. The fragment stage evaluates the
+// selected Standard Surface so opacity/alpha-clip stays identical to Forward
+// and Deferred (depth32float is still the only render target).
 //
 // feat-20260613-csm-cascaded-shadow-maps M5 / w28: per-cascade
 // lightViewProj selection. Each cascade pass writes a different
@@ -29,12 +35,25 @@
 
 struct VsInput {
   @location(0) position : vec3<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) uv : vec2<f32>,
+  @location(3) tangent : vec4<f32>,
 #if SKINNING_DISABLED == false
   @location(4) skinIndex : vec4<u32>,
   @location(5) skinWeight : vec4<f32>,
 #endif
 };
 
+struct VsOut {
+  @builtin(position) clip : vec4<f32>,
+  @location(0) positionOS : vec3<f32>,
+  @location(1) positionWS : vec3<f32>,
+  @location(2) normalWS : vec3<f32>,
+  @location(3) tangentWS : vec4<f32>,
+  @location(4) surfaceUv : vec2<f32>,
+  @location(5) vertexColor : vec4<f32>,
+};
+
 #if SKINNING_DISABLED == false
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(2) @binding(1) var<storage, read> palette : array<mat4x4<f32>>;
@@ -53,7 +72,7 @@ fn _cascadeLightViewProj(layer : u32) -> mat4x4<f32> {
 }
 
 @vertex
-fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> @builtin(position) vec4<f32> {
+fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> VsOut {
 #if SKINNING_DISABLED == false
   let skinMatrix = palette[in.skinIndex.x] * in.skinWeight.x +
     palette[in.skinIndex.y] * in.skinWeight.y +
@@ -63,8 +82,14 @@ fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> @builtin(positio
   // produce world-space positions. Applying meshes[0].worldFromLocal again
   // would double-transform a parented skinned entity.
   let worldPos = skinMatrix * vec4<f32>(in.position, 1.0);
+  let worldNormal = normalize((skinMatrix * vec4<f32>(in.normal, 0.0)).xyz);
+  let worldTangent = normalize((skinMatrix * vec4<f32>(in.tangent.xyz, 0.0)).xyz);
 #else
-  let worldPos = meshes[0].worldFromLocal * instances[idx].localFromInstance * vec4<f32>(in.position, 1.0);
+  let instanceLocal = instances[idx].localFromInstance;
+  let worldMatrix = meshes[0].worldFromLocal * instanceLocal;
+  let worldPos = worldMatrix * vec4<f32>(in.position, 1.0);
+  let worldNormal = normalize((worldMatrix * vec4<f32>(in.normal, 0.0)).xyz);
+  let worldTangent = normalize((worldMatrix * vec4<f32>(in.tangent.xyz, 0.0)).xyz);
 #endif
   // feat-20260625-spot-light-shadow-mapping M2 / w10 (D-1): spot shadow passes
   // set `isSpot = 1u` and write their perspective matrix into
@@ -72,8 +97,57 @@ fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> @builtin(positio
   // `view.lightViewProj_A..D` via `index`. Routing on the discriminant keeps
   // the spot matrix out of the directional View UBO (no same-frame contention).
   if (shadowCasterCascade.isSpot == 1u) {
-    return shadowCasterCascade.spotLightViewProj * worldPos;
+    var out : VsOut;
+    out.clip = shadowCasterCascade.spotLightViewProj * worldPos;
+    out.positionOS = in.position;
+    out.positionWS = worldPos.xyz;
+    out.normalWS = worldNormal;
+    out.tangentWS = vec4<f32>(worldTangent, in.tangent.w);
+    out.surfaceUv = in.uv;
+    out.vertexColor = vec4<f32>(1.0);
+    return out;
   }
   let lvp = _cascadeLightViewProj(shadowCasterCascade.index);
-  return lvp * worldPos;
+  var out : VsOut;
+  out.clip = lvp * worldPos;
+  out.positionOS = in.position;
+  out.positionWS = worldPos.xyz;
+  out.normalWS = worldNormal;
+  out.tangentWS = vec4<f32>(worldTangent, in.tangent.w);
+  out.surfaceUv = in.uv;
+  out.vertexColor = vec4<f32>(1.0);
+  return out;
+}
+
+fn evaluateShadowSurface(in : VsOut, frontFacing : bool) -> SurfaceData {
+  let viewDirectionWS = normalize(view.cameraPos - in.positionWS);
+  return evaluate_surface(SurfaceInput(
+    in.positionOS,
+    in.positionWS,
+    in.normalWS,
+    in.tangentWS,
+    viewDirectionWS,
+    in.surfaceUv,
+    in.surfaceUv,
+    in.vertexColor,
+    frontFacing,
+  ));
+}
+
+fn alphaTestShadowSurface(surface : SurfaceData) {
+  if (surface.alphaClipThreshold > 0.0 && surface.opacity <= surface.alphaClipThreshold) {
+    discard;
+  }
+}
+
+// The depth-only path evaluates the selected Surface so alpha-clip ownership
+// remains shared with Forward and Deferred without mutating vertex data.
+@fragment
+fn fs_shadow(in : VsOut, @builtin(front_facing) frontFacing : bool) {
+  alphaTestShadowSurface(evaluateShadowSurface(in, frontFacing));
+}
+
+@fragment
+fn fs_main(in : VsOut, @builtin(front_facing) frontFacing : bool) {
+  alphaTestShadowSurface(evaluateShadowSurface(in, frontFacing));
 }

package/src/standard-cluster.wgsl

@@ -9,18 +9,11 @@
 #define_import_path forgeax_standard::cluster
 
 #import forgeax_pbr::lighting_punctual::{evalPoint, evalPointFlat, evalSpot, evalSpotFlat, evalSpotShadowed}
-#import forgeax_pbr::lighting_attenuation::{projectSpotUv}
 #import forgeax_pbr::lighting_spot_modifiers::{spotModifierFactors}
 #import forgeax_pbr::lighting_rect_area::{evalRectAreaLtcGgx}
 #import forgeax_view::common::{view}
 #ifdef PROJECTOR_AVAILABLE
-#ifdef EXTENDED_LIGHTING_AVAILABLE
-#import forgeax_view::common::{spotModifierSampler, cookieTexture}
-#else
-#ifndef EXTENDED_LIGHTING_AVAILABLE
-#import forgeax_view::common::{projectorTexture, projectorSampler}
-#endif
-#endif
+#import forgeax_pbr::lighting_spot_projector::{sampleStandardSpotProjector}
 #endif
 #ifdef POINT_SHADOW_AVAILABLE
 #import forgeax_pbr::lighting_punctual::{evalPointShadowed}
@@ -95,34 +88,6 @@ fn ndc_position_to_cluster(
   return vec3(cx, cy, cz);
 }
 
-// Surface SpotLight projector sampling is owned by the same clustered light
-// evaluator as the analytic cone/range contribution. The host marks the
-// selected projector in the DirectLightSlot flag and writes its matrix to the
-// corresponding View lane (lane 0 for projector-only); no second
-// material-local sampling loop or resource owner is allowed.
-fn sampleStandardSpotProjector(
-  lightViewProj : mat4x4<f32>,
-  world_pos    : vec3<f32>,
-  metadata     : vec4<u32>,
-) -> vec3<f32> {
-#ifdef PROJECTOR_AVAILABLE
-  let uv = projectSpotUv(lightViewProj, world_pos);
-  if (!(uv.x >= 0.0 && uv.x <= 1.0 && uv.y >= 0.0 && uv.y <= 1.0)) {
-    return vec3<f32>(1.0);
-  }
-#ifdef EXTENDED_LIGHTING_AVAILABLE
-  if (metadata.w == 0xffffffffu) {
-    return vec3<f32>(1.0);
-  }
-  return textureSampleLevel(cookieTexture, spotModifierSampler, uv, metadata.w, 0.0).rgb;
-#else
-  return textureSampleLevel(projectorTexture, projectorSampler, uv, 0.0).rgb;
-#endif
-#else
-  return vec3<f32>(1.0);
-#endif
-}
-
 // Decode one kind first, then delegate the complete evaluation to the shared
 // punctual owner. Unknown kinds are explicitly zero contribution.
 fn evaluate_cluster_light(

package/src/surface_v1.wgsl

@@ -0,0 +1,26 @@
+#define_import_path forgeax_material::surface_v1
+
+// Engine-owned input ABI for authored Standard material surfaces.
+struct SurfaceInput {
+  positionOS : vec3<f32>,
+  positionWS : vec3<f32>,
+  geometricNormalWS : vec3<f32>,
+  tangentWS : vec4<f32>,
+  viewDirectionWS : vec3<f32>,
+  uv0 : vec2<f32>,
+  uv1 : vec2<f32>,
+  vertexColor : vec4<f32>,
+  frontFacing : bool,
+};
+
+// Surface output is consumed by the Standard BRDF and pass family.
+struct SurfaceData {
+  baseColor : vec3<f32>,
+  normalWS : vec3<f32>,
+  metallic : f32,
+  roughness : f32,
+  emissive : vec3<f32>,
+  occlusion : f32,
+  opacity : f32,
+  alphaClipThreshold : f32,
+};

package/src/unlit.wgsl

@@ -111,6 +111,18 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   return vec4<f32>(material.baseColor.rgb * texSample.rgb * vertexColor.rgb, alpha);
 }
 
+// Depth-only shadow variant. Keep alpha clipping identical to the color path,
+// but return no color target because the shadow pass has a depth attachment only.
+@fragment
+fn fs_shadow(in : VsOut) {
+  let texSample = sampleMaterialTextureLinear(baseColorTexture, baseColorSampler, in.uv, material.baseColorTextureCoordinatesMetadata.zw);
+  let vertexColor = materialVertexColor(in);
+  let alpha = material.baseColor.a * texSample.a * vertexColor.a;
+  if (material.alphaCutoff > 0.0 && alpha < material.alphaCutoff) {
+    discard;
+  }
+}
+
 struct TemporalVsOut {
   @builtin(position) clip : vec4<f32>,
   @location(0) uv : vec2<f32>,