@forgeax/engine-render 0.1.23 → 0.1.24

package/src/record/main-pass-geometry.ts

@@ -10,7 +10,7 @@ import {
   RhiError,
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
-import type { PassKind, PrimitiveTopology } from '@forgeax/engine-types';
+import type { ParamSchemaEntry, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
 import { GpuBuffer } from '../gpu-resource';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
@@ -22,8 +22,12 @@ import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import {
   createPbrSkinMeshBindGroupEntries,
+  isCanonicalStandardPbrMaterialShader,
   isStandardPbrMaterialShader,
+  isStandardPbrSkinMaterialShader,
+  materialBindGroupLayoutIdentity,
   pbrSkinMeshDynamicOffsets,
+  physicalTextureFields,
   SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
 import {
@@ -41,7 +45,7 @@ import {
   PROBE_BLEND_RECORD_STRIDE,
   probeBlendRecordOffset,
 } from '../scene/probe-blend-record';
-import { worldEntityKey } from './frame-snapshot';
+import { getOpaqueResourceIdentity, worldEntityKey } from './frame-snapshot';
 import {
   geometryRenderStateForTopology,
   isEntityFullyTransparent,
@@ -75,6 +79,18 @@ type GeometryBindingState = {
   probeOffset: number;
 };
 
+function materialDiagnosticsEnabled(): boolean {
+  if (typeof globalThis !== 'object' || globalThis === null || !('process' in globalThis)) {
+    return false;
+  }
+  const processValue = (
+    globalThis as {
+      readonly process?: { readonly env?: Record<string, string | undefined> };
+    }
+  ).process;
+  return processValue?.env?.FORGEAX_MATERIAL_DIAGNOSTICS === '1';
+}
+
 type MaterialPipelineLookup = {
   readonly materialShaderId: string;
   readonly isHdrTarget: boolean;
@@ -94,6 +110,121 @@ type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection
 
 type GeometryRenderState = ReturnType<typeof geometryRenderStateForTopology>;
 
+/**
+ * Select the transmission shader axis from authored material data, not the
+ * canonical boot schema.  The latter reserves transmission fields for the
+ * shared Standard ABI even when a material remains base-only.
+ */
+export function requestsStandardTransmissionVariant(
+  material: Pick<MaterialSnapshot, 'materialShaderId' | 'paramSnapshot'>,
+): boolean {
+  return (
+    material.materialShaderId === 'forgeax::default-standard-pbr' &&
+    material.paramSnapshot?.transmission !== undefined
+  );
+}
+
+function recordIblPipelineBinding(
+  c: _InternalRenderPipelineContext,
+  material: MaterialSnapshot,
+  pipeline: RenderPipeline,
+  materialGroup: BindGroup,
+): void {
+  const receipt = c.frameState.iblBindingInspection;
+  if (receipt === undefined || !isStandardPbrMaterialShader(material.materialShaderId)) return;
+  const materialBgl =
+    c.runtime.getMaterialBindGroupLayout?.(
+      material.materialShaderId ?? 'forgeax::default-standard-pbr',
+    ) ?? c.pipelineState.materialBindGroupLayout;
+  c.frameState.iblBindingInspection = {
+    ...receipt,
+    pipeline: {
+      pipelineIdentity: getOpaqueResourceIdentity(pipeline as object),
+      effectiveMaterialLayoutIdentity: effectiveMaterialLayoutIdentity(
+        material.materialShaderId ?? 'forgeax::default-standard-pbr',
+        material.materialParamSchema,
+      ),
+      materialBglIdentity: getOpaqueResourceIdentity(materialBgl as object),
+      bindGroupIdentity: getOpaqueResourceIdentity(materialGroup as object),
+      drawFrameId: c.frameState.frameNumber,
+    },
+  };
+  const materialReceipt = c.frameState.iblBindingInspection.material;
+  const errors: string[] = [];
+  if (
+    materialReceipt !== undefined &&
+    materialReceipt.materialBglIdentity !== getOpaqueResourceIdentity(materialBgl as object)
+  ) {
+    errors.push('material-pipeline-bgl-identity-mismatch');
+  }
+  if (
+    materialReceipt !== undefined &&
+    materialReceipt.bindGroupIdentity !== getOpaqueResourceIdentity(materialGroup as object)
+  ) {
+    errors.push('material-bind-group-identity-mismatch');
+  }
+  if (materialReceipt !== undefined) {
+    const expectedResourceIdentities = [
+      receipt.resources.irradiance.viewIdentity,
+      receipt.resources.irradiance.samplerIdentity,
+      receipt.resources.prefilter.viewIdentity,
+      receipt.resources.prefilter.samplerIdentity,
+      receipt.resources.brdfLut.viewIdentity,
+      receipt.resources.brdfLut.samplerIdentity,
+      receipt.resources.intensityBufferIdentity,
+    ];
+    const actualResourceIdentities = materialReceipt.entries
+      .filter((entry) => entry.binding >= materialReceipt.skylightBindingStart)
+      .slice(0, expectedResourceIdentities.length)
+      .map((entry) => entry.resourceIdentity);
+    if (
+      actualResourceIdentities.length !== expectedResourceIdentities.length ||
+      actualResourceIdentities.some(
+        (identity, index) => identity !== expectedResourceIdentities[index],
+      )
+    ) {
+      errors.push('material-ibl-resource-identity-mismatch');
+    }
+  }
+  c.frameState.iblBindingInspection = {
+    ...c.frameState.iblBindingInspection,
+    status: errors.length === 0 ? 'binding-chain-consistent' : 'binding-chain-mismatch',
+    errors,
+  };
+}
+
+const SHARED_BOOT_MATERIAL_SHADER_IDS = new Set([
+  'forgeax::default-unlit',
+  'forgeax::default-shadow-caster',
+  'forgeax::sprite',
+  'forgeax::sprite-lit',
+  'forgeax::default-sprite',
+  'forgeax::msdf-text',
+  'forgeax::default-standard-pbr',
+  'forgeax::pbr-skin',
+  'forgeax::default-standard-pbr-skin',
+]);
+
+/**
+ * Returns the layout identity that can distinguish a material PSO in the
+ * record cache. Shared boot shaders keep the boot layout identity even when a
+ * manifest exposes a schema; Standard PBR only opts into a schema-derived
+ * identity when authored clearcoat texture bindings extend that layout.
+ */
+export function effectiveMaterialLayoutIdentity(
+  materialShaderId: string,
+  materialParamSchema?: readonly ParamSchemaEntry[],
+): string | undefined {
+  if (materialParamSchema === undefined) return undefined;
+  const hasStandardPhysicalMaps =
+    isStandardPbrMaterialShader(materialShaderId) &&
+    physicalTextureFields(materialParamSchema).length > 0;
+  if (SHARED_BOOT_MATERIAL_SHADER_IDS.has(materialShaderId) && !hasStandardPhysicalMaps) {
+    return undefined;
+  }
+  return materialBindGroupLayoutIdentity(materialShaderId, materialParamSchema);
+}
+
 /**
  * Resolve the depth contract for a geometry pass without changing the base
  * material state. Temporal scene-data shares the main pass depth attachment:
@@ -228,6 +359,7 @@ export function recordGeometryDraws(
     viewBindGroup,
     viewBindGroupDynamicOffset = 0,
   } = c;
+  const diagnosticsEnabled = materialDiagnosticsEnabled();
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
   // The prepared Standard topology is the frame authority. A bind-group
   // identity is only a resource result; using it to infer the shader lane
@@ -587,7 +719,22 @@ export function recordGeometryDraws(
     // and walks 0, 1536, 3072, ... on the storage path.
     const skinAllocator = pipelineState.skinPaletteAllocator;
     const skinSlice = entry.source.skin;
-    const clusteredSkin = clusteredLighting;
+    // Authored Standard skin aliases deliberately publish the physical root
+    // with only their STORAGE_BUFFER capability axis. Their composed WGSL is
+    // the direct-lighting/palette (`skin`) ABI, even when the frame's
+    // canonical Standard lane uses clustered lighting. Only the canonical
+    // engine skin artifact can consume the HDRP unified skin group(2) layout;
+    // selecting it from the frame topology alone would bind
+    // `hdrp-skin-unified-bg-group2` to a three-entry URP skin PSO.
+    const clusteredSkin =
+      clusteredLighting &&
+      entry.source.materials.every((material) => {
+        const shaderId = material.materialShaderId;
+        return (
+          !isStandardPbrSkinMaterialShader(shaderId) ||
+          isCanonicalStandardPbrMaterialShader(shaderId)
+        );
+      });
     const skinMeshBindGroupLayout = clusteredSkin
       ? pipelineState.hdrpSkinMeshBindGroupLayout
       : pipelineState.pbrSkinMeshBindGroupLayout;
@@ -734,6 +881,19 @@ export function recordGeometryDraws(
       // the async PSO compile resolves the cache hits and the next frame
       // routes the skin BG + skin pipeline together. Mirrors the uniform
       // null skip-draw shape (M6-T1, charter P3 explicit failure).
+      if (diagnosticsEnabled) {
+        console.error(
+          `[render-material] skin draw skipped: ${JSON.stringify({
+            entityKey: entry.source.entityKey,
+            materialHandle: entry.source.material.materialHandle,
+            reason: 'skin-pipeline-unavailable',
+            skinResourcesReady: skinResources !== null,
+            skinPsoReady: skinPsoProbe !== null,
+            paletteBufferReady: skinSlice?.buffer !== undefined,
+            paletteByteOffset: skinSlice?.byteOffset,
+          })}`,
+        );
+      }
       continue;
     }
     // feat-20260520-2d-sprite-layer-mvp M-3 / w25 (@fallback sprite
@@ -828,6 +988,26 @@ export function recordGeometryDraws(
       // injection, and Skylight merge; deduped cross-entity via the
       // shaderId-outer `materialBgShared` cache.
       const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
+      const processValue = (
+        globalThis as {
+          process?: { env?: Record<string, string | undefined> };
+        }
+      ).process;
+      if (
+        processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === '1' &&
+        (submeshMaterial.materialShaderId === 'forgeax::default-standard-pbr' ||
+          submeshMaterial.materialShaderId === 'forgeax::pbr-skin')
+      ) {
+        console.error(
+          `[render-material] draw receipt: ${JSON.stringify({
+            entityIndex: entry.renderableIndex,
+            materialSlot,
+            materialHandle: submeshMaterial.materialHandle,
+            clearcoat: submeshMaterial.paramSnapshot?.clearcoat,
+            shader: submeshMaterial.materialShaderId,
+          })}`,
+        );
+      }
       perSubmeshBg =
         profilePhase === undefined
           ? resolveMaterialBindGroup(
@@ -849,7 +1029,9 @@ export function recordGeometryDraws(
       const smTopology = sm.topology;
       const smMaterialShaderId =
         entry.source.skin !== undefined
-          ? SKIN_MATERIAL_SHADER_ID
+          ? isStandardPbrSkinMaterialShader(submeshMaterial.materialShaderId)
+            ? submeshMaterial.materialShaderId
+            : SKIN_MATERIAL_SHADER_ID
           : submeshMaterial.materialShaderId;
       const probeBlendAvailable =
         probeBlendRecordAvailable && isStandardPbrMaterialShader(smMaterialShaderId);
@@ -930,6 +1112,11 @@ export function recordGeometryDraws(
           hasVertexColor,
           probeBlendAvailable,
         );
+        const transmissionAvailable = requestsStandardTransmissionVariant(submeshMaterial);
+        const materialCapabilityVariantSet =
+          transmissionAvailable && !capabilityVariantSet.includes('TRANSMISSION_AVAILABLE=')
+            ? `${capabilityVariantSet === '' ? '' : `${capabilityVariantSet}+`}TRANSMISSION_AVAILABLE=true`
+            : capabilityVariantSet;
         // Sprite's base request must retain the boot-selected artifact. Only
         // SpriteInstances uses the explicit empty key for the
         // PER_INSTANCE_REGION=true variant; synthesizing the generic PBR
@@ -940,7 +1127,7 @@ export function recordGeometryDraws(
             ? ''
             : undefined
           : entry.variantSet === undefined
-            ? capabilityVariantSet
+            ? materialCapabilityVariantSet
             : capabilityVariantSet === ''
               ? entry.variantSet
               : `${capabilityVariantSet}+${entry.variantSet}`;
@@ -973,6 +1160,16 @@ export function recordGeometryDraws(
       }
 
       if (smPipelineHandle === null) {
+        if (diagnosticsEnabled) {
+          console.error(
+            `[render-material] draw skipped: ${JSON.stringify({
+              entityKey: entry.source.entityKey,
+              materialHandle: submeshMaterial.materialHandle,
+              shader: smMaterialShaderId,
+              reason: 'pipeline-unavailable',
+            })}`,
+          );
+        }
         continue;
       }
       // The probe record is an ABI extension of the built-in Standard PBR
@@ -1003,6 +1200,31 @@ export function recordGeometryDraws(
         if (selectedGroup === null) continue;
         group2BindGroup = selectedGroup;
       }
+      if (diagnosticsEnabled && submeshMaterial.textureHandles !== undefined) {
+        console.error(
+          `[render-material] draw submitted: ${JSON.stringify({
+            entityKey: entry.source.entityKey,
+            materialHandle: submeshMaterial.materialHandle,
+            shader: smMaterialShaderId,
+            textureHandles: [...submeshMaterial.textureHandles.entries()].map(
+              ([field, handle]) => ({
+                field,
+                handle,
+              }),
+            ),
+            skin: isSkinEntry
+              ? {
+                  resourcesReady: skinResources !== null,
+                  psoReady: skinPsoProbe !== null,
+                  paletteBufferReady: skinSlice?.buffer !== undefined,
+                  paletteByteOffset: skinSlice?.byteOffset,
+                  dynamicOffsets: [...group2DynamicOffsets],
+                }
+              : undefined,
+            pipelineReady: true,
+          })}`,
+        );
+      }
       pass.setBindGroup(2, group2BindGroup, group2DynamicOffsets);
 
       if (profilePhase === undefined) {
@@ -1034,6 +1256,9 @@ export function recordGeometryDraws(
           ),
         );
       }
+      if (diagnosticsEnabled && perSubmeshBg !== null) {
+        recordIblPipelineBinding(c, submeshMaterial, smPipelineHandle, perSubmeshBg);
+      }
     }
   }
 }