@forgeax/engine-render 0.1.7 → 0.1.19

package/src/materials.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import type {
   MaterialAsset,
   MaterialColorSpace,
@@ -7,6 +8,49 @@ import type {
   MaterialValue,
 } from '@forgeax/engine-types';
 
+export type MaterialTransmissionValidationReason =
+  | 'non-finite'
+  | 'range'
+  | 'shape'
+  | 'blend'
+  | 'depth-write';
+
+/** Structured authoring failure for the Standard transmission contract. */
+export class MaterialTransmissionContractError extends Error {
+  readonly code = 'material-transmission-contract-invalid' as const;
+  readonly expected = 'transmission material values satisfy finite ranges and Forward depth rules';
+  readonly hint =
+    'repair the named transmission value or pass state before publishing the material';
+  readonly detail: {
+    readonly code: 'material-transmission-contract-invalid';
+    readonly material: 'Standard';
+    readonly parameter:
+      | 'transmission'
+      | 'ior'
+      | 'thickness'
+      | 'attenuationColor'
+      | 'attenuationDistance';
+    readonly reason: MaterialTransmissionValidationReason;
+    readonly actual?: unknown;
+  };
+
+  constructor(
+    parameter: (typeof MaterialTransmissionContractError.prototype.detail)['parameter'],
+    reason: MaterialTransmissionValidationReason,
+    actual?: unknown,
+  ) {
+    super(`Materials.standard: ${parameter} violates the transmission contract (${reason})`);
+    this.name = 'MaterialTransmissionContractError';
+    this.detail = {
+      code: 'material-transmission-contract-invalid',
+      material: 'Standard',
+      parameter,
+      reason,
+      ...(actual === undefined ? {} : { actual }),
+    };
+  }
+}
+
 export const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState = {
   color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
   alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
@@ -31,28 +75,26 @@ function authoredColorParameter(
 }
 
 function standardParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {
-  return [
-    authoredColorParameter('baseColor', 'color', colorSpace),
-    { name: 'metallic', type: 'f32' },
-    { name: 'roughness', type: 'f32' },
-    { name: 'metallicChannel', type: 'f32', optional: true },
-    { name: 'roughnessChannel', type: 'f32', optional: true },
-    { name: 'aoChannel', type: 'f32', optional: true },
-    { name: 'extraChannel', type: 'f32', optional: true },
-    authoredColorParameter('emissive', 'vec3', colorSpace, true),
-    { name: 'emissiveIntensity', type: 'f32', optional: true },
-    { name: 'occlusionStrength', type: 'f32', optional: true },
-    { name: 'alphaCutoff', type: 'f32', optional: true },
-    { name: 'clearcoat', type: 'f32', optional: true },
-    { name: 'clearcoatRoughness', type: 'f32', optional: true },
-    authoredColorParameter('specularTint', 'vec3', colorSpace, true),
-    { name: 'baseColorTexture', type: 'texture', optional: true },
-    { name: 'metallicRoughnessTexture', type: 'texture', optional: true },
-    { name: 'normalTexture', type: 'texture', optional: true },
-    { name: 'specularTintTexture', type: 'texture', optional: true },
-    { name: 'emissiveTexture', type: 'texture', optional: true },
-    { name: 'occlusionTexture', type: 'texture', optional: true },
-  ];
+  return DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => {
+    const type = entry.type.startsWith('texture') ? 'texture' : entry.type;
+    const isRequired =
+      entry.name === 'baseColor' || entry.name === 'metallic' || entry.name === 'roughness';
+    const authoredColor =
+      entry.type === 'color' || (entry.type === 'vec3' && entry.name !== 'attenuationColor');
+    const schemaColorSpace = 'colorSpace' in entry ? entry.colorSpace : undefined;
+    const colorSpaceProjection: { colorSpace?: MaterialColorSpace } = {};
+    if (authoredColor && !(type === 'color' && colorSpace === 'srgb')) {
+      colorSpaceProjection.colorSpace = colorSpace;
+    } else if (!authoredColor && schemaColorSpace !== undefined) {
+      colorSpaceProjection.colorSpace = schemaColorSpace;
+    }
+    return {
+      name: entry.name,
+      type,
+      ...colorSpaceProjection,
+      ...(isRequired ? {} : { optional: true }),
+    } as MaterialParameter;
+  });
 }
 
 function unlitParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {
@@ -143,6 +185,13 @@ interface StandardOpts {
   readonly occlusionTexture?: MaterialValue;
   readonly occlusionStrength?: number;
   readonly alphaCutoff?: number;
+  readonly transmission?: number;
+  readonly transmissionTexture?: MaterialValue;
+  readonly ior?: number;
+  readonly thickness?: number;
+  readonly thicknessTexture?: MaterialValue;
+  readonly attenuationColor?: readonly [number, number, number];
+  readonly attenuationDistance?: number;
   readonly renderState?: MaterialRenderState;
   readonly castShadow?: boolean;
   readonly queue?: number;
@@ -157,6 +206,21 @@ function validateChannel(
   }
 }
 
+function validateFiniteRange(
+  name: 'transmission' | 'ior' | 'thickness' | 'attenuationDistance',
+  value: number | undefined,
+  minimum: number,
+  maximum?: number,
+): void {
+  if (value === undefined || !Number.isFinite(value)) {
+    if (value === undefined) return;
+    throw new MaterialTransmissionContractError(name, 'non-finite', value);
+  }
+  if (value < minimum || (maximum !== undefined && value > maximum)) {
+    throw new MaterialTransmissionContractError(name, 'range', value);
+  }
+}
+
 function standard(opts: StandardOpts): MaterialAsset {
   const occlusionStrength = opts.occlusionStrength ?? 1;
   if (occlusionStrength < 0 || occlusionStrength > 1) {
@@ -169,12 +233,36 @@ function standard(opts: StandardOpts): MaterialAsset {
   }
   validateChannel('metallicChannel', opts.metallicChannel);
   validateChannel('roughnessChannel', opts.roughnessChannel);
+  const transmission = opts.transmission ?? 0;
+  const ior = opts.ior ?? 1.5;
+  const thickness = opts.thickness ?? 0;
+  const attenuationColor = opts.attenuationColor ?? [1, 1, 1];
+  validateFiniteRange('transmission', transmission, 0, 1);
+  validateFiniteRange('ior', ior, 1);
+  validateFiniteRange('thickness', thickness, 0);
+  validateFiniteRange('attenuationDistance', opts.attenuationDistance, Number.MIN_VALUE);
+  if (
+    attenuationColor.length !== 3 ||
+    attenuationColor.some((value) => !Number.isFinite(value) || value < 0 || value > 1)
+  ) {
+    throw new MaterialTransmissionContractError('attenuationColor', 'shape', attenuationColor);
+  }
+  if (transmission > 0 && opts.renderState?.blend !== undefined) {
+    throw new MaterialTransmissionContractError('transmission', 'blend', opts.renderState.blend);
+  }
+  if (transmission > 0 && opts.renderState?.depthWriteEnabled === true) {
+    throw new MaterialTransmissionContractError('transmission', 'depth-write', true);
+  }
   const values: Record<string, MaterialValue> = {
     baseColor: opts.baseColor,
     metallic: opts.metallic ?? 0,
     roughness: opts.roughness ?? 0.5,
     occlusionStrength,
     specularTint: opts.specularTint ?? [1, 1, 1],
+    transmission,
+    ior,
+    thickness,
+    attenuationColor,
   };
   if (opts.metallicChannel !== undefined) values.metallicChannel = opts.metallicChannel;
   if (opts.roughnessChannel !== undefined) values.roughnessChannel = opts.roughnessChannel;
@@ -193,10 +281,17 @@ function standard(opts: StandardOpts): MaterialAsset {
     values.specularTintTexture = opts.specularTintTexture;
   }
   if (opts.alphaCutoff !== undefined) values.alphaCutoff = opts.alphaCutoff;
+  if (opts.transmissionTexture !== undefined) values.transmissionTexture = opts.transmissionTexture;
+  if (opts.thicknessTexture !== undefined) values.thicknessTexture = opts.thicknessTexture;
+  if (opts.attenuationDistance !== undefined) values.attenuationDistance = opts.attenuationDistance;
+  const forwardRenderState =
+    transmission > 0 ? { ...(opts.renderState ?? {}), depthWriteEnabled: false } : opts.renderState;
   const passes: [MaterialPass, ...MaterialPass[]] = [
-    pass('forward', STANDARD_MODULE, opts.renderState, 'fs_main', opts.queue),
-    pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue),
+    pass('forward', STANDARD_MODULE, forwardRenderState, 'fs_main', opts.queue),
   ];
+  if (transmission === 0) {
+    passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));
+  }
   if (opts.castShadow !== false) passes.push(pass('shadow-caster', STANDARD_MODULE, undefined));
   return {
     kind: 'material',

package/src/pbr-pipeline.ts

@@ -65,7 +65,7 @@ export interface PbrPipelineLayoutBundle {
   readonly viewBgl: BindGroupLayout;
   /**
    * PBR material BindGroupLayout (slot 1) -- derived user-region entries plus
-   * Skylight and lightmap injection.
+   * Skylight and transmission injection.
    */
   readonly materialBgl: BindGroupLayout;
   /** Per-entity mesh BindGroupLayout (slot 2). */
@@ -89,7 +89,7 @@ export interface PbrPipelineLayoutBundle {
 /**
  * The built-in standard-PBR material paramSchema's texture/user-region shape,
  * used as the fallback when the material BGL is built without a registry
- * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 3 standard
+ * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 8 Standard
  * user-region textures + a numeric UBO run; `derive()` collapses the numerics
  * into binding 0 and emits sampler/texture pairs at 1..6 — byte-equivalent to
  * the legacy fixed base-7. The shared PBR parameter contract comes from the
@@ -99,13 +99,13 @@ export interface PbrPipelineLayoutBundle {
  * Build the PBR material BGL **user-region** from a paramSchema via the
  * `derive()` SSOT (D-1). The user-region is binding 0 (the run-merged material
  * UBO) followed by one sampler/texture pair per declared texture. Engine
- * injection (IBL + lightmap) is appended AFTER this region by the caller via
+ * injection (IBL + transmission) is appended AFTER this region by the caller via
  * `appendInjection`, with start binding = `userRegion.length` — so a 4-texture
  * custom schema (e.g. parallax + heightTexture) shifts the injection region by
  * one sampler/texture pair automatically.
  *
- * The built-in `default-standard-pbr` paramSchema declares exactly 4 textures,
- * so this derives to binding 0 UBO + 4 pairs = 9 entries. Injection is appended
+ * The built-in `default-standard-pbr` paramSchema declares exactly 8 textures,
+ * so this derives to binding 0 UBO + 8 pairs = 17 entries. Injection is appended
  * after that derived region.
  *
  * One material-UBO convention is layered on top of the pure `derive()` output:
@@ -178,11 +178,16 @@ export function buildPbrMaterialUserRegionEntries(
 //                keep that meaning under the generic 'lightmap' label
 //                (per-surface secondary-lighting injection) so future
 //                lightmap support lands without renaming the kind.
+//   - 'transmission' the engine-owned sampler + backdrop texture pair. The
+//                record stage supplies a real backdrop only for the active
+//                transmission pass; all other variants bind layout-safe
+//                placeholders because their shaders do not read these slots.
 export type InjectionKind = keyof typeof INJECTION_KIND_LENGTHS;
 
 const IBL_INJECTION_LENGTH = 7;
 const LIGHTMAP_INJECTION_LENGTH = 4;
 const SHADOW_INJECTION_LENGTH = 2;
+const TRANSMISSION_INJECTION_LENGTH = 2;
 
 /**
  * Append the engine-injection BGL entries for the given `kind` after the
@@ -289,6 +294,19 @@ export function appendInjection(
           texture: { sampleType: 'depth', viewDimension: '2d' },
         },
       ];
+    case 'transmission':
+      return [
+        {
+          binding: start,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: 'filtering' },
+        },
+        {
+          binding: start + 1,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: 'float', viewDimension: '2d' },
+        },
+      ];
   }
 }
 
@@ -297,6 +315,7 @@ export const INJECTION_KIND_LENGTHS = {
   shadow: SHADOW_INJECTION_LENGTH,
   ibl: IBL_INJECTION_LENGTH,
   lightmap: LIGHTMAP_INJECTION_LENGTH,
+  transmission: TRANSMISSION_INJECTION_LENGTH,
 };
 
 /**
@@ -479,17 +498,16 @@ export function buildPbrPipelineLayouts(
   // D-13 round-2: 4 BGLs route through buildBindGroupLayoutDescriptor.
   // The dispatcher reads kind + caps; spec content is unused without a
   // registry (no shader-axis reflection at this seam — the 4 BGLs are
-  // caps-driven literals + the deterministic Skylight + lightmap merge
+  // caps-driven literals + the deterministic Skylight + transmission merge
   // sequence that has no dependency on shader.id).
   const viewBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-view', caps }),
   );
   if (!viewBglRes.ok) throw viewBglRes.error;
 
-  // Material BGL: derived user region + Skylight + lightmap injection.
-  // feat-20260613 fix-issue-5: drop the buildPbrMaterialEmissiveAoEntries
-  // shim. The lightmap injection start binding is computed from the post-
-  // skylight BGL length (= 14) directly inside appendInjection.
+  // Material BGL: derived user region + Skylight + transmission injection.
+  // The transmission start binding is computed from the post-Skylight BGL
+  // length (= 24 for the built-in Standard schema) by appendInjection.
   const materialBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-material-merged' }),
   );
@@ -542,6 +560,23 @@ export function buildPbrPipelineLayouts(
  * `LayoutKind = 'pbr-skin'` upstream.
  */
 export const SKIN_MATERIAL_SHADER_ID = 'forgeax::pbr-skin' as const;
+export const SHADOW_CASTER_SHADER_ID = 'forgeax::default-shadow-caster' as const;
+
+export function shadowCasterVariantSet(storageBuffer: boolean, skinned: boolean): string {
+  const skinningDisabled = !skinned;
+  if (storageBuffer && skinningDisabled) return '';
+  return `SKINNING_DISABLED=${String(skinningDisabled)}+STORAGE_BUFFER_AVAILABLE=${String(storageBuffer)}`;
+}
+
+export function isSkinnedShadowCasterVariant(
+  materialShaderId: string | undefined,
+  variantSet: string | undefined,
+): boolean {
+  return (
+    materialShaderId === SHADOW_CASTER_SHADER_ID &&
+    variantSet?.includes('SKINNING_DISABLED=false') === true
+  );
+}
 
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
@@ -745,7 +780,7 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *
  * Three groups by derivation source:
  * 1. Shader-derived (paramSchema reflection + injection chain):
- *    - `'pbr-material-merged'` — derived user region + Skylight 7 + lightmap 4
+ *    - `'pbr-material-merged'` — derived user region + Skylight 7 + transmission 2
  *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
  *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
  * 2. Caps-driven literal shapes (no shader):
@@ -852,7 +887,7 @@ export function createHdrpBindGroupLayoutDescriptor(
  * Shader-derived kinds (`'pbr-material-merged'` / `'unlit-material'` /
  * `'hdrp-7-slot'`) require `options.registry` to look up the shader entry
  * and reflect its `paramSchema` via {@link deriveBglShapeFromShader}; they
- * compose the per-entry injection chain (Skylight + lightmap for material;
+ * compose the per-entry injection chain (Skylight + transmission for material;
  * HDRP variantSet for cluster-forward).
  *
  * Caps-driven kinds (`'pbr-view'` / `'pbr-mesh-array'` / `'pbr-instances'` /
@@ -951,7 +986,11 @@ export function buildBindGroupLayoutDescriptor(
         entries: [
           {
             binding: 0,
-            visibility: GPU_SHADER_STAGE_VERTEX,
+            // Standard transmission reads the same per-instance transform in
+            // fs_main to convert glTF unit-space thickness into world metres.
+            // Keep one shared instances BGL and widen its visibility instead
+            // of introducing a second transform upload or six new varyings.
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
             buffer: { type: meshBufType, hasDynamicOffset: false },
           },
         ],
@@ -980,24 +1019,24 @@ export function buildBindGroupLayoutDescriptor(
     }
     case 'pbr-material-merged': {
       // Material BGL: per-shader user-region (derive(paramSchema).bglEntries)
-      // + IBL injection (7) + lightmap injection (4). The user-region size is
-      // the only variable; injection start = userRegion.length so a 4-texture
-      // custom schema shifts IBL/lightmap by one sampler/texture pair (D-1).
-      // For the built-in 4-texture standard-PBR schema this is 9 + 7 + 4 = 20.
+      // + IBL injection (7) + transmission injection (2). The user-region
+      // size is the only variable; injection start = userRegion.length so a
+      // custom schema shifts IBL/transmission by its sampler/texture pairs.
+      // The built-in 8-texture standard-PBR schema is 17 + 7 + 2 = 26 entries.
       //
       // Schema source priority (D-1): explicit materialParamSchema option >
       // registry lookup of spec.shader.id > built-in standard-PBR fallback.
       const resolvedSchema = resolveMaterialParamSchema(spec, options);
       const userRegion = buildPbrMaterialUserRegionEntries(resolvedSchema);
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
-      const merged = [...afterIbl, ...appendInjection(afterIbl, 'lightmap')];
+      const merged = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
       return {
         label: 'pbr-material-skylight-bgl',
         entries: merged,
       };
     }
     case 'unlit-material': {
-      // Unlit material BGL: per-shader user-region only. No IBL/lightmap
+      // Unlit material BGL: per-shader user-region only. No IBL/transmission
       // injection (D-5 round-4: unlit demos do not pay for IBL state).
       const resolvedSchema = resolveMaterialParamSchema(spec, options);
       return {