@forgeax/engine-shader 0.1.21 → 0.1.24

package/src/material/artifact-types.ts

@@ -1,14 +1,151 @@
 import type { BindGroupLayoutDescriptor } from '@forgeax/engine-types';
 
+export interface MaterialShaderResourceSlot {
+  readonly name: string;
+  readonly parameter: string;
+  readonly kind: 'sampler' | 'texture';
+  readonly group: number;
+  readonly binding: number;
+}
+
+export interface MaterialShaderVertexInput {
+  readonly semantic: string;
+  readonly location: number;
+  readonly format: string;
+}
+
+export interface MaterialShaderArtifactReceipt {
+  readonly directEntry: string;
+  readonly sceneIndexEntry: string;
+  readonly materialRow: {
+    readonly byteLength: number;
+    readonly fields: readonly string[];
+  };
+  readonly resourceSlots: readonly MaterialShaderResourceSlot[];
+  readonly uvSets: readonly { readonly parameter: string; readonly set: number }[];
+  readonly vertexInputs: readonly MaterialShaderVertexInput[];
+  readonly alphaMask: { readonly cutoff: string; readonly source: string };
+  readonly skinPaletteAddress?: {
+    readonly group: number;
+    readonly binding: number;
+    readonly stride: number;
+  };
+  readonly reflection: {
+    readonly layoutIdentity: string;
+    readonly resourceSlots: readonly MaterialShaderResourceSlot[];
+    readonly vertexInputs: readonly MaterialShaderVertexInput[];
+  };
+  readonly receiptIdentity: string;
+  readonly generation: number;
+}
+
 export interface MaterialShaderArtifact {
   readonly material: string;
   readonly pass: string;
   readonly wgsl: string;
   readonly layoutIdentity: string;
+  /** Naga-reflected UV set count used to derive clamp-to-last vertex aliases. */
+  readonly uvSetCount?: number;
   readonly bindings: readonly BindGroupLayoutDescriptor[];
   readonly deps: readonly string[];
   readonly vertexInputs: readonly Readonly<Record<string, unknown>>[];
   readonly specializationKey?: string;
+  /** Producer-owned ABI facts shared by direct and scene-index consumers. */
+  readonly receipt?: MaterialShaderArtifactReceipt;
+}
+
+const STANDARD_PBR_TEXTURES = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularColorTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
+] as const;
+
+const STANDARD_PBR_NUMERIC_FIELDS = [
+  'baseColor',
+  'metallic',
+  'roughness',
+  'metallicChannel',
+  'roughnessChannel',
+  'aoChannel',
+  'extraChannel',
+  'emissive',
+  'emissiveIntensity',
+  'occlusionStrength',
+  'alphaCutoff',
+  'clearcoat',
+  'clearcoatRoughness',
+  'specularColor',
+  'normalScale',
+  'transmission',
+  'ior',
+  'thickness',
+  'attenuationColor',
+  'attenuationDistance',
+] as const;
+
+const STANDARD_PBR_VERTEX_INPUTS: readonly MaterialShaderVertexInput[] = [
+  { semantic: 'position', location: 0, format: 'float32x3' },
+  { semantic: 'normal', location: 1, format: 'float32x3' },
+  { semantic: 'uv', location: 2, format: 'float32x2' },
+  { semantic: 'tangent', location: 3, format: 'float32x4' },
+];
+
+function standardPbrResourceSlots(): MaterialShaderResourceSlot[] {
+  return STANDARD_PBR_TEXTURES.flatMap((parameter, index) => [
+    {
+      name: `${parameter}_sampler`,
+      parameter,
+      kind: 'sampler' as const,
+      group: 1,
+      binding: index * 2 + 1,
+    },
+    {
+      name: parameter,
+      parameter,
+      kind: 'texture' as const,
+      group: 1,
+      binding: index * 2 + 2,
+    },
+  ]);
+}
+
+/**
+ * Builds the one Standard PBR ABI receipt consumed by both material lanes.
+ * The skinned module uses the same material producer and only adds its palette
+ * address; it must retain the same receipt identity for material compatibility.
+ */
+export function createStandardPbrArtifactReceipt(skinned = false): MaterialShaderArtifactReceipt {
+  const resourceSlots = standardPbrResourceSlots();
+  const uvSets = STANDARD_PBR_TEXTURES.map((parameter) => ({ parameter, set: 0 }));
+  const vertexInputs = skinned
+    ? [
+        ...STANDARD_PBR_VERTEX_INPUTS,
+        { semantic: 'skinIndex', location: 4, format: 'uint16x4' },
+        { semantic: 'skinWeight', location: 5, format: 'float32x4' },
+      ]
+    : [...STANDARD_PBR_VERTEX_INPUTS];
+  return {
+    directEntry: 'vs_main',
+    sceneIndexEntry: 'vs_scene_index',
+    materialRow: { byteLength: 384, fields: [...STANDARD_PBR_NUMERIC_FIELDS] },
+    resourceSlots,
+    uvSets,
+    vertexInputs,
+    alphaMask: { cutoff: 'alphaCutoff', source: 'baseColor.a' },
+    ...(skinned ? { skinPaletteAddress: { group: 2, binding: 1, stride: 64 } } : {}),
+    reflection: {
+      layoutIdentity: 'standard-pbr/material-row-v1',
+      resourceSlots,
+      vertexInputs,
+    },
+    receiptIdentity: 'standard-pbr/material-row-v1',
+    generation: 1,
+  };
 }
 
 export function isMaterialShaderArtifact(value: unknown): value is MaterialShaderArtifact {

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-schemas.ts

@@ -1,38 +1,85 @@
 import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import {
+  STANDARD_MATERIAL_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_PARAMETER_NAMES,
+} from '@forgeax/engine-types';
+import {
+  createStandardPbrArtifactReceipt,
+  type MaterialShaderArtifactReceipt,
+} from './material/artifact-types.js';
 
 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 =
+  createStandardPbrArtifactReceipt();
+
+/** Skinned Standard PBR keeps the material receipt identity and adds palette ABI. */
+export const STANDARD_PBR_SKIN_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt =
+  createStandardPbrArtifactReceipt(true);
 
 export const DEFAULT_UNLIT_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
   { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },

package/src/register-default-sprite-lit.ts

@@ -56,12 +56,9 @@ export interface SpriteLitCaps {
  * compiled by @forgeax/engine-vite-plugin-shader at build time and surfaced
  * in manifest.json. The caller reads it from the manifest entries.
  *
- * `caps.storageBuffer` switches the runtime BGL buffer types for
- * @group(0) bindings 1+2 (pointLightsBuffer / spotLightsBuffer):
- * `false` -> uniform fallback (AC-10 WebGL2 path); `true` -> read-only-storage.
- * The BGL itself is built downstream in runtime/pbr-pipeline.ts (sprite-lit
- * reuses pbr-view / pbr-mesh-array / pbr-instances unchanged; AC-07
- * BGL byte-identical).
+ * `caps.storageBuffer` is retained for the shared mesh/instance layout
+ * selection. Sprite-lit local lighting reads the same Standard Cluster group
+ * as PBR; the view group has no direct point/spot arrays.
  *
  * @param registry ShaderRegistry instance (engine boot path).
  * @param composedWgsl Post-naga_oil composed WGSL source string.

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/sprite-lit.wgsl

@@ -2,7 +2,7 @@
 #pragma variant_axis CLUSTER_FORWARD_AVAILABLE
 #define_import_path forgeax_material::sprite-lit
 
-#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, sampleMaterialTexture}
+#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, sampleMaterialTexture, packSceneTemporal}
 #import forgeax_scene_temporal::{packSceneTemporalV1, sceneViewZ}
 #ifdef CLUSTER_FORWARD_AVAILABLE
 #import forgeax_standard::cluster::{evaluateStandardClusterLights}
@@ -39,11 +39,11 @@
 // 1 string change in MaterialAsset.passes[0].shader).
 //
 // Bindings (byte-identical to sprite.wgsl so the 4 BindGroupLayout chain is
-// reused without a per-pipeline BGL; the 4 PBR-unused entries 3..6 bind
+// reused without a per-pipeline BGL; the PBR-unused entries 3..6 bind
 // pipelineState.defaultSampler + .defaultWhiteTextureView on the host side):
 //
 //   @group(0) @binding(0) view                       uniform
-//   @group(0) @binding(1..2) Standard Cluster storage (selected variant)
+//   @group(2) @binding(3..6) Standard Cluster storage (selected variant)
 //   @group(1) @binding(0) material                   uniform (sprite layout
 //                                                             colorTint /
 //                                                             region /

package/src/sprite.wgsl

@@ -152,7 +152,7 @@ fn resolveSpriteVertex(in : VsIn, idx : u32, vertex_index : u32) -> SpriteVertex
   // pivotAndSize.zw scaled the local quad AND the world matrix also scaled
   // it, producing the scale^2 visual size debt that research F-4 flagged.
   // Post-w11 there is one and only one scale source: the entity's
-  // Transform.world. The mesh's built-in vertex.pos is NOT consumed (sprite
+  // GlobalTransform.world. The mesh's built-in vertex.pos is NOT consumed (sprite
   // geometry is fully re-derived from uv + pivot) so HANDLE_QUAD's mesh.pos
   // remains a placeholder driving vertex count (4) and topology only.
   //