@forgeax/engine-render 0.1.23 → 0.1.25

package/src/pbr-pipeline.ts

@@ -32,7 +32,11 @@ import type {
   TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA, type ShaderCatalog } from '@forgeax/engine-shader';
+import {
+  type ShaderCatalog,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+  standardPhysicalTextureFields,
+} from '@forgeax/engine-shader';
 import { derive, type ParamSchemaEntry } from '@forgeax/engine-types';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from './gpu-stage';
 import type { PipelineSpec } from './pipeline-spec-types';
@@ -101,11 +105,13 @@ export function standardPbrColorFormats(
 /**
  * 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 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
- * shader package; this module only derives the GPU layout.
+ * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the canonical
+ * Standard user-region textures + a numeric UBO run; `derive()` collapses the
+ * numerics into binding 0 and emits one sampler/texture pair per declared
+ * texture. Physical map pairs stay outside this boot region and are appended
+ * only for an authored root that declares them. The shared PBR parameter
+ * contract comes from the shader package; this module only derives the GPU
+ * layout.
  */
 /**
  * Build the PBR material BGL **user-region** from a paramSchema via the
@@ -116,9 +122,10 @@ export function standardPbrColorFormats(
  * 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 8 textures,
- * so this derives to binding 0 UBO + 8 pairs = 17 entries. Injection is appended
- * after that derived region.
+ * The canonical `STANDARD_PIPELINE_PARAM_SCHEMA` currently declares seven
+ * non-physical textures, so this derives to binding 0 UBO + seven pairs = 15
+ * entries. IBL and transmission injection are appended after that region;
+ * authored physical maps are appended after the engine-owned injections.
  *
  * One material-UBO convention is layered on top of the pure `derive()` output:
  * binding 0 is patched to `{ type: 'uniform', hasDynamicOffset: true }` with
@@ -132,9 +139,18 @@ export function standardPbrColorFormats(
  *   built-in standard-PBR shape when omitted, for the caps-driven seam).
  */
 export function buildPbrMaterialUserRegionEntries(
-  paramSchema: readonly ParamSchemaEntry[] = DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  paramSchema: readonly ParamSchemaEntry[] = STANDARD_PIPELINE_PARAM_SCHEMA,
+  excludedTextureFields: readonly string[] = [],
 ): GPUBindGroupLayoutEntry[] {
-  const derived = derive(paramSchema);
+  const excluded = new Set(excludedTextureFields);
+  for (const field of standardPhysicalTextureFields(paramSchema)) excluded.add(field);
+  const derived = derive(
+    excluded.size === 0
+      ? paramSchema
+      : paramSchema.filter(
+          (entry) => !excluded.has(entry.name) || !entry.type.startsWith('texture'),
+        ),
+  );
   // Project the engine-owned entry shape into the DOM WebGPU descriptor. Omit
   // absent optional members so exactOptionalPropertyTypes remains true at the
   // boundary instead of leaking an `undefined` property into the descriptor.
@@ -330,6 +346,68 @@ export const INJECTION_KIND_LENGTHS = {
   transmission: TRANSMISSION_INJECTION_LENGTH,
 };
 
+export function physicalTextureFields(paramSchema: readonly ParamSchemaEntry[]): readonly string[] {
+  return standardPhysicalTextureFields(paramSchema);
+}
+
+export function appendTextureInjection(
+  bgl: readonly GPUBindGroupLayoutEntry[],
+  fields: readonly string[],
+): GPUBindGroupLayoutEntry[] {
+  const start = bgl.length;
+  const fieldSet = new Set(fields);
+  return standardPhysicalTextureFields(
+    fields.map((name) => ({ name, type: 'texture2d' as const })),
+  ).flatMap((field, index) => {
+    if (!fieldSet.has(field)) return [];
+    const binding = start + index * 2;
+    return [
+      {
+        binding,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' as const },
+      },
+      {
+        binding: binding + 1,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float' as const, viewDimension: '2d' as const },
+      },
+    ];
+  });
+}
+
+/**
+ * Return the stable identity of the merged material bind-group layout.
+ *
+ * This is deliberately derived from the same descriptor builder consumed by
+ * the device path. Callers use it to keep pipeline, bind-group, and
+ * frame-local lookup caches on one layout identity even when equivalent
+ * paramSchema arrays were allocated independently.
+ */
+export function materialBindGroupLayoutIdentity(
+  shaderId: string,
+  paramSchema: readonly ParamSchemaEntry[],
+): string {
+  const descriptor = buildBindGroupLayoutDescriptor(
+    {
+      shader: { id: shaderId, passKind: 'forward', variantSet: undefined },
+      attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+      geometry: { topology: 'triangle-list', vertexLayout: {} },
+      renderState: undefined,
+    },
+    { kind: 'pbr-material-merged', materialParamSchema: paramSchema },
+  );
+  // Descriptor shape alone cannot distinguish two Standard roots that expose
+  // the same number of physical texture pairs under different semantic names.
+  // The resource order is part of the admitted root contract, so include the
+  // canonical physical projection in the cache identity while keeping the
+  // actual WebGPU descriptor owned by the builder above.
+  return JSON.stringify({
+    entries: descriptor.entries,
+    physicalTextureFields: physicalTextureFields(paramSchema),
+  });
+}
+
 /**
  * Caps shape consumed by the BGL factory functions for storage-buffer vs
  * uniform-buffer branching. Mirrors the two fields the engine reads from
@@ -568,7 +646,7 @@ export function buildPbrPipelineLayouts(
 
   // 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.
+  // length (= 22 for the canonical Standard schema) by appendInjection.
   const materialBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-material-merged' }),
   );
@@ -658,6 +736,21 @@ export function buildPbrPipelineLayouts(
 export const SKIN_MATERIAL_SHADER_ID = 'forgeax::pbr-skin' as const;
 export const SHADOW_CASTER_SHADER_ID = 'forgeax::default-shadow-caster' as const;
 
+// Authored Standard templates are published under a unique module id for each
+// root contract.  Keep the family marker in the id so every downstream render
+// owner (extract, layout, and record) can make the same Standard-vs-custom and
+// rigid-vs-skinned decision without a second registry or a runtime shader
+// inspection pass.
+const AUTHORED_STANDARD_ID_RE = /::(?:standard|pbr-skin)(?:-|$)/;
+
+export function isStandardPbrSkinMaterialShader(shaderId: string | undefined): boolean {
+  return (
+    shaderId === SKIN_MATERIAL_SHADER_ID ||
+    shaderId === 'forgeax::default-standard-pbr-skin' ||
+    (shaderId !== undefined && /::pbr-skin(?:-|$)/.test(shaderId))
+  );
+}
+
 export function shadowCasterVariantSet(storageBuffer: boolean, skinned: boolean): string {
   const skinningDisabled = !skinned;
   if (storageBuffer && skinningDisabled) return '';
@@ -692,6 +785,22 @@ export function resolvePipelineGroup2Contract(source: string): PipelineGroup2Con
 
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
+  return (
+    shaderId === 'forgeax::default-standard-pbr' ||
+    shaderId === SKIN_MATERIAL_SHADER_ID ||
+    shaderId === 'forgeax::default-standard-pbr-skin' ||
+    (shaderId !== undefined && AUTHORED_STANDARD_ID_RE.test(shaderId))
+  );
+}
+
+/**
+ * Return true only for the two engine-owned Standard roots. Authored Standard
+ * aliases intentionally remain outside this set: their cooked root schema may
+ * omit transmission or other optional resources, so their compact user-region
+ * layout must be derived from that artifact instead of borrowing the boot
+ * layout's reserved slots.
+ */
+export function isCanonicalStandardPbrMaterialShader(shaderId: string | undefined): boolean {
   return (
     shaderId === 'forgeax::default-standard-pbr' ||
     shaderId === SKIN_MATERIAL_SHADER_ID ||
@@ -1240,14 +1349,29 @@ export function buildBindGroupLayoutDescriptor(
       // + 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.
+      // The built-in standard-PBR schema is 17 + 7 + 2 = 26 entries;
+      // clearcoat texture pairs are derived from the effective root schema.
       //
       // 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 effectiveSchema = resolvedSchema ?? STANDARD_PIPELINE_PARAM_SCHEMA;
+      const physicalFields = physicalTextureFields(effectiveSchema);
+      // Standard's built-in shader keeps the transmission user-region slots
+      // reserved even when a particular root omits those values.  Physical
+      // maps extend that canonical region; they must not compact the IBL
+      // bindings to the smaller authored subset.  A compact user region is
+      // still correct for authored (non-engine) material shaders.
+      const userRegionSchema = isCanonicalStandardPbrMaterialShader(spec.shader.id)
+        ? STANDARD_PIPELINE_PARAM_SCHEMA
+        : effectiveSchema;
+      const userRegion = buildPbrMaterialUserRegionEntries(userRegionSchema);
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
-      const merged = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const afterTransmission = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const merged = [
+        ...afterTransmission,
+        ...appendTextureInjection(afterTransmission, physicalFields),
+      ];
       return {
         label: 'pbr-material-skylight-bgl',
         entries: merged,

package/src/pipeline-builder.ts

@@ -277,7 +277,13 @@ export function buildPipelineForMaterialShader(
   const vsEntry = vertexEntry ?? (passKind === 'temporal' ? 'vs_temporal' : 'vs_main');
   const fsEntry =
     fragmentEntry ??
-    (passKind === 'temporal' ? 'fs_temporal' : passKind === 'deferred' ? 'fs_gbuffer' : 'fs_main');
+    (passKind === 'temporal'
+      ? 'fs_temporal'
+      : passKind === 'deferred'
+        ? 'fs_gbuffer'
+        : passKind === 'shadow-caster'
+          ? 'fs_shadow'
+          : 'fs_main');
 
   let source = entry.source;
   if (defines !== undefined && Object.keys(defines).length > 0) {
@@ -345,15 +351,13 @@ export function buildPipelineForMaterialShader(
       vertex: {
         module: shaderModule,
         entryPoint: vsEntry,
-        buffers:
-          ctx.layoutKind === 'pbr-skin'
-            ? [...ctx.vertexBuffers]
-            : [
-                {
-                  arrayStride: 12 * 4,
-                  attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as const }],
-                },
-              ],
+        // Surface-backed Standard shadow entries evaluate the same material
+        // surface as Forward/Deferred, so their vertex stage consumes normal,
+        // UV, and tangent inputs in addition to position. Keep the complete
+        // derived mesh layout here; extra attributes remain legal for legacy
+        // position-only custom casters, while trimming to position would make
+        // the built-in Surface shadow shader fail WebGPU validation.
+        buffers: [...ctx.vertexBuffers],
       },
       // Vertex-only depth pass writes `fragment: undefined` (GPU derives
       // depth from gl_Position.z). A custom ShadowCaster shader with a

package/src/pipeline-spec.ts

@@ -19,6 +19,7 @@
 
 import {
   deriveVertexBufferLayout,
+  deriveVertexBufferLayoutFromProjection,
   deriveVertexLayoutProjection,
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
@@ -407,20 +408,11 @@ export function buildPipelineDescriptor(
             ? { shaderUvSetCount: geometry.shaderUvSetCount }
             : {}),
         })
-      : geometry.vertexLayoutProjection.attributes.length === 0
-        ? []
-        : [
-            {
-              arrayStride: geometry.vertexLayoutProjection.arrayStride,
-              attributes: geometry.vertexLayoutProjection.attributes.map(
-                ({ shaderLocation, offset, format }) => ({
-                  shaderLocation,
-                  offset,
-                  format,
-                }),
-              ),
-            },
-          ];
+      : deriveVertexBufferLayoutFromProjection(geometry.vertexLayoutProjection, {
+          ...(geometry.shaderUvSetCount !== undefined
+            ? { shaderUvSetCount: geometry.shaderUvSetCount }
+            : {}),
+        });
 
   const descriptor: Record<string, unknown> = {
     vertex: {

package/src/points-lines/__tests__/cache-recovery.unit.test.ts

@@ -154,4 +154,26 @@ describe('Points/Lines expansion cache and LKG recovery', () => {
     expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
     expect(preparation.inspect()).toMatchObject({ status: 'resident', lastKnownGood: true });
   });
+
+  it('abandons lost-device handles without invoking the dead-device destroy path', () => {
+    let destroys = 0;
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter: {
+        create: () => ok('lost-device-resource'),
+        upload: () => ok(64),
+        validate: () => ok(undefined),
+        destroy: () => {
+          destroys += 1;
+        },
+      },
+    });
+
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    preparation.abandonForDeviceLoss();
+    preparation.abandonForDeviceLoss();
+
+    expect(destroys).toBe(0);
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+  });
 });

package/src/points-lines/prepare.ts

@@ -37,6 +37,8 @@ export interface PointsLinesLanePreparationAdapter<Resource> {
     mesh: MeshAsset,
   ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError>;
   resetForDeviceLoss(): void;
+  /** Drop lost-device handles without calling destroy on the dead device. */
+  abandonForDeviceLoss(): void;
   lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined;
   inspect(): PointsLinesPreparationInspection<Resource>;
 }
@@ -121,6 +123,12 @@ export class PointsLinesPreparation<Resource> {
     this.status = 'rebuild-pending';
   }
 
+  abandonForDeviceLoss(): void {
+    this.live = undefined;
+    this.pendingCandidateBytes = 0;
+    this.status = 'rebuild-pending';
+  }
+
   lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined {
     return this.live;
   }
@@ -171,6 +179,7 @@ export function createPointsLinesLanePreparationAdapter<Resource>(
     contract: createPointsLinesLaneContract(lane, backend),
     prepare: (snapshot, mesh) => preparation.prepare(snapshot, mesh),
     resetForDeviceLoss: () => preparation.resetForDeviceLoss(),
+    abandonForDeviceLoss: () => preparation.abandonForDeviceLoss(),
     lastKnownGood: () => preparation.lastKnownGood(),
     inspect: () => preparation.inspect(),
   };