@forgeax/engine-render 0.1.25 → 0.1.27

package/src/record/shadow-pass.ts

@@ -1,3 +1,4 @@
+import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import {
   type BindGroup,
   type BindGroupEntry,
@@ -24,6 +25,11 @@ import {
   resolveGeometryInstanceBuffer,
   resolveGeometryInstancesBindGroup,
 } from './main-pass-geometry';
+import {
+  buildPerSubmeshMaterialBg,
+  type PerSubmeshMaterialBgDeps,
+  prepareMaterialSkylight,
+} from './main-pass-material';
 import {
   getOrCreateFromChain,
   MESH_PER_ENTITY_STRIDE,
@@ -31,7 +37,7 @@ import {
   MESH_UBO_FULL_ARRAY_BYTES,
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
-import { STANDARD_PBR_UBO_SIZE } from './render-context';
+import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
 import { POINTS_LINES_VIEW_BYTES, pointShadowViewOffset, VIEW_UNIFORM_BYTES } from './view-ubo';
 
 export const SHADOW_CASTER_SLOT_STRIDE = 256;
@@ -247,11 +253,10 @@ function ensureTypedShadowViewBg(
 }
 
 interface ShadowDispatch {
-  readonly materialHandle: number;
+  readonly vertexEntry: string | undefined;
+  readonly fragmentEntry: string | undefined;
   readonly materialShaderId: string;
   readonly renderState: MaterialRenderState | undefined;
-  readonly materialSlot: number | undefined;
-  readonly paramSnapshot: DispatchEntry['paramSnapshot'];
 }
 
 type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, ShadowDispatch>>;
@@ -265,20 +270,14 @@ export function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispat
         byMaterial = new Map<number, ShadowDispatch>();
         shaders.set(entry.renderableIndex, byMaterial);
       }
-      const candidateSlots =
-        c.materialSlotIndices[entry.renderableIndex] ?? c.materialSlotIndices.flat();
-      const materialSlot = candidateSlots.find(
-        (slot) => c.materialSlots[slot]?.materialHandle === entry.materialHandle,
-      );
       byMaterial.set(entry.materialHandle, {
-        materialHandle: entry.materialHandle,
+        vertexEntry: entry.vertexEntry,
+        fragmentEntry: entry.fragmentEntry,
         materialShaderId:
           entry.materialShaderId === 'forgeax::default-standard-pbr'
             ? SHADOW_CASTER_SHADER_ID
             : entry.materialShaderId,
         renderState: entry.renderState,
-        materialSlot,
-        paramSnapshot: entry.paramSnapshot,
       });
     }
   }
@@ -379,13 +378,15 @@ export function encodeDirectionalShadowPass(
     `view-shadow-directional-${cascadeIndex}`,
   );
   const materialBg = ensureSpotShadowMaterialBg(c);
-  if (pipeline === null || viewBg === null || materialBg === null) return;
-  c.frameState.directionalShadowCacheRecorded = true;
+  if (pipeline === null || viewBg === null || materialBg === null) {
+    c.frameState.directionalShadowCacheRecorded = false;
+    return;
+  }
   pass.setViewport(viewport.x, viewport.y, viewport.w, viewport.h, 0, 1);
   pass.setPipeline(pipeline);
   pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
-  recordShadowCasterDraws(
+  const complete = recordShadowCasterDraws(
     c,
     pass,
     pipeline,
@@ -393,6 +394,8 @@ export function encodeDirectionalShadowPass(
     buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] }),
     shadowShaderMap(c),
   );
+  c.frameState.directionalShadowCacheRecorded =
+    cascadeIndex === 0 ? complete : c.frameState.directionalShadowCacheRecorded && complete;
 }
 
 export function encodePointShadowPass(
@@ -577,7 +580,7 @@ function recordShadowCasterDraws(
   shadowMeshBindGroup: BindGroup,
   matchedIndices: Set<number> | null,
   shadowDispatchByRenderableIdx: ShadowDispatchMap,
-): void {
+): boolean {
   const { runtime, pipelineState, validatedOrdered } = c;
   // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer
   // (the wrapper) -- the de-dup compare uses wrapper identity (one wrapper
@@ -591,6 +594,8 @@ function recordShadowCasterDraws(
   // bound by the setPipeline call above; the loop switches to a custom
   // ShadowCaster PSO when a material supplies one.
   let shadowLastPipeline: RenderPipeline = shadowPipeline;
+  let materialDeps: PerSubmeshMaterialBgDeps | undefined;
+  let complete = true;
 
   for (let i = 0; i < validatedOrdered.length; i++) {
     const entry = validatedOrdered[i];
@@ -601,7 +606,10 @@ function recordShadowCasterDraws(
 
     if (entry.source.skin !== undefined) {
       const skinPipeline = skinnedShadowPipeline(c, entry);
-      if (skinPipeline === null) continue;
+      if (skinPipeline === null) {
+        complete = false;
+        continue;
+      }
       if (skinPipeline !== shadowLastPipeline) {
         shadowPass.setPipeline(skinPipeline);
         shadowLastPipeline = skinPipeline;
@@ -686,21 +694,17 @@ function recordShadowCasterDraws(
         ?.get(submeshMaterial.materialHandle ?? 0);
       const entryShadowShaderId = shadowDispatch?.materialShaderId;
       const entryShadowRenderState = shadowDispatch?.renderState;
-      // A skinned caster's pipeline was selected above together with its
-      // two-binding mesh/palette group. Keep that pairing for every submesh;
-      // resetting to the static shadow pipeline here would bind the skin
-      // group against `pbr-pl` and Dawn rejects the draw at submit time.
-      let entryShadowPipeline =
+      // Canonical skin casters retain their palette layout. Authored casters
+      // select their own program below with the same geometry layout.
+      let entryShadowPipeline: RenderPipeline | null =
         entry.source.skin !== undefined ? shadowLastPipeline : shadowPipeline;
       if (
-        entry.source.skin === undefined &&
         entryShadowShaderId !== undefined &&
         (entryShadowShaderId !== 'forgeax::default-shadow-caster' ||
-          entryShadowRenderState !== undefined)
+          (entryShadowRenderState !== undefined && entry.source.skin === undefined))
       ) {
-        // On a cache miss (async build in flight / build failure), fall back
-        // to the default PSO so the caster still writes depth rather than
-        // dropping its draw.
+        // Pending or failed authored programs must not draw using a different
+        // caster. Retry preparation on the next frame with the same program.
         entryShadowPipeline =
           runtime.getMaterialShaderPipeline?.(
             entryShadowShaderId,
@@ -710,12 +714,65 @@ function recordShadowCasterDraws(
             undefined, // indexFormat
             undefined, // variantSet — shadow caster has no variant axes
             'shadow-caster', // passKind
-          ) ?? shadowPipeline;
+            undefined, // meshAttributes
+            1,
+            undefined, // colorFormatOverride
+            undefined, // shaderUvSetCount
+            undefined, // depthFormatOverride
+            undefined, // vertexLayout
+            entry.mesh.layoutProjection,
+            undefined, // shaderModuleMode
+            entry.source.skin === undefined ? 'pbr' : 'pbr-skin',
+            undefined, // additionalColorFormats
+            shadowDispatch?.vertexEntry,
+            shadowDispatch?.fragmentEntry,
+          ) ?? null;
+      }
+      if (entryShadowPipeline === null) {
+        complete = false;
+        continue;
       }
       if (entryShadowPipeline !== shadowLastPipeline && entryShadowPipeline !== null) {
         shadowPass.setPipeline(entryShadowPipeline);
         shadowLastPipeline = entryShadowPipeline;
       }
+      if (entryShadowShaderId !== undefined && entryShadowShaderId !== SHADOW_CASTER_SHADER_ID) {
+        materialDeps ??= {
+          runtime,
+          pipelineState,
+          world: c.world,
+          store: c.store,
+          materialSlice: STANDARD_PBR_UBO_SIZE,
+          videoHighPerfAvailable: probeVideoHighPerfUpload(runtime.device),
+          skylightResources: prepareMaterialSkylight(c).skylightResources,
+          resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
+          materialBgShared: c.frameState.materialBgShared,
+          materialBgAssemblyCache: c.materialBgAssemblyCache,
+          frameState: c.frameState,
+          bindGroupCounts: c.bindGroupCounts,
+        };
+        const materialSlot =
+          c.materialSlotIndices[i]?.[sm.materialSlot] ?? c.materialSlotIndices[i]?.[0];
+        if (materialSlot === undefined) {
+          throw new RhiError({
+            code: 'rhi-descriptor-invalid',
+            expected: 'a prepared material slot for each shadow submesh',
+            hint: 'repair material slot preparation before recording shadows',
+          });
+        }
+        const materialGroup = buildPerSubmeshMaterialBg(
+          materialDeps,
+          submeshMaterial,
+          entry.source.entityKey,
+          entry.world ?? c.world,
+          entryShadowShaderId,
+        );
+        shadowPass.setBindGroup(1, materialGroup, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
+      } else {
+        const materialGroup = ensureSpotShadowMaterialBg(c);
+        if (materialGroup === null) continue;
+        shadowPass.setBindGroup(1, materialGroup, [0]);
+      }
       for (const instanceDraw of shadowInstanceDraws) {
         shadowPass.setBindGroup(3, instanceDraw.instanceBindGroup);
         if (entry.mesh.indexed) {
@@ -726,6 +783,7 @@ function recordShadowCasterDraws(
       }
     }
   }
+  return complete;
 }
 
 /**

package/src/recovery/render-system-candidate.ts

@@ -639,7 +639,11 @@ export function createRenderSystemRecovery(
           seed.frame.lights.pointShadow.length > 0 ||
           seed.frame.lights.spot.some((spot) => spot.castShadow === true) ||
           (seed.frame.lights.lightViewProj?.length ?? 0) > 0,
-        splitLdrSprite: computeSplitLdrSprite(candidateValidated, camera.tonemap !== 'none'),
+        splitLdrSprite: computeSplitLdrSprite(
+          candidateValidated,
+          camera.tonemap !== 'none',
+          seed.frame.dispatch,
+        ),
         reflectionFallbackAvailable: candidateFrameState.reflectionFallbackDemand === true,
       });
       const candidatePostProcessIds = new Set<string>([

package/src/render-system-extract-tail.ts

@@ -15,6 +15,7 @@ import {
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { box3, frustum, type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 import { RhiError } from '@forgeax/engine-rhi';
 import { GlobalTransform, MorphWeights, Transform } from '@forgeax/engine-scene';
 import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
@@ -147,7 +148,8 @@ import {
   isEngineInjectedTextureField,
   materialColorParameterSchema,
   materialNormalScale,
-  materialParametersToParamSchema,
+  materialParamSchemaForMaterial,
+  materialProgramKeysForMaterial,
   materialTextureFields,
   materialTextureRef,
   pipelineRenderState,
@@ -174,6 +176,7 @@ export function extractFrames(
   pipelineState?: ExtractPipelineSurface | null,
   materialSnapshotCachesByWorld?: MaterialSnapshotCachesByWorld,
   options: {
+    readonly materialContext?: MaterialCookProgramContext;
     readonly cull?: 'normal' | 'none';
     readonly renderables?: 'full' | 'none';
     readonly renderableEntitiesByWorld?: readonly (ReadonlySet<number> | undefined)[];
@@ -251,6 +254,9 @@ export function extractFrames(
                   return cache;
                 })(),
             }),
+        ...(options.materialContext === undefined
+          ? {}
+          : { materialContext: options.materialContext }),
         cull: options.cull === 'none' ? 'none' : isCameraOwner ? 'self' : 'external',
         renderables: options.renderables ?? 'full',
         ...(options.renderableEntitiesByWorld?.[wi] === undefined
@@ -1559,6 +1565,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // extraction. Shared handles are immutable inputs for the frame, while
   // dispatch entries still need to be rebuilt for each entity.
   const materialSnapshotCache: MaterialSnapshotCache = new Map();
+  const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
   // (`row.get(X) !== undefined` edge sniff) replaces the prior
@@ -1927,7 +1934,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             layerVal,
             materialSnap.paramSnapshot,
             0,
-            materialSnap.materialShaderId,
+            materialSnap.materialProgramKeys,
           );
         }
       } else if (handleRaw === 0 || assets === undefined || assets === null) {
@@ -1956,7 +1963,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               layerVal,
               materialSnap.paramSnapshot,
               0,
-              materialSnap.materialShaderId,
+              materialSnap.materialProgramKeys,
             );
           }
         } else {
@@ -2020,7 +2027,26 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             }
             const resolved = resolvedResult.value;
             const allPasses = resolved.passes;
-            const firstPassShader = runtimeMaterialShaderIdForMaterial(asset, allPasses, assets);
+            const materialContext =
+              context.materialContext === undefined
+                ? undefined
+                : {
+                    ...context.materialContext,
+                    geometry: hasSkin ? ('skinned' as const) : context.materialContext.geometry,
+                  };
+            const materialProgramKeys = materialProgramKeysForMaterial(
+              asset,
+              assets,
+              materialContext,
+            );
+            const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(
+              allPasses,
+              undefined,
+            );
+            const firstPassShader = runtimeMaterialShaderIdForMaterial(
+              allPasses,
+              materialProgramKeys,
+            );
             const pv = materialValuesToLinearRuntime(
               resolved.values,
               materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assets),
@@ -2047,9 +2073,10 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               }
             }
 
-            const materialParamSchema = materialParametersToParamSchema(
+            const materialParamSchema = materialParamSchemaForMaterial(
               resolved.parameters ?? [],
-              firstPassShader,
+              authoredFirstPassShader,
+              allPasses,
             );
             // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w17 (D-5):
             // bidirectional Skin <-> pbr-skin material fail-fast at extract.
@@ -2338,6 +2365,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               }),
               normalScale: normalScalePv,
               materialShaderId: firstPassShader,
+              materialProgramKeys,
               materialHandle: handleRaw,
               renderState: pipelineRenderState(allPasses[0]?.renderState),
               paramSnapshot: paramSnap,
@@ -2399,7 +2427,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 layerVal,
                 paramSnap,
                 0,
-                firstPassShader,
+                materialProgramKeys,
               );
             }
           }
@@ -2610,15 +2638,22 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         if (assets !== undefined && assets !== null) {
           for (let mi = 1; mi < materialHandles.length; mi++) {
             const subHandle = materialHandles[mi] ?? 0;
-            const cachedSubmaterial = materialSnapshotCache.get(subHandle);
+            const subCache = hasSkin ? skinnedMaterialSnapshotCache : materialSnapshotCache;
+            const cachedSubmaterial = subCache.get(subHandle);
             materialsArr.push(
               cachedSubmaterial?.snapshot ??
                 resolveMaterialSnapshot(
                   subHandle,
                   world,
                   assets,
-                  materialSnapshotCache,
-                  persistentMaterialSnapshotCache,
+                  subCache,
+                  hasSkin ? undefined : persistentMaterialSnapshotCache,
+                  context.materialContext === undefined
+                    ? undefined
+                    : {
+                        ...context.materialContext,
+                        geometry: hasSkin ? 'skinned' : context.materialContext.geometry,
+                      },
                 ),
             );
           }
@@ -2628,8 +2663,14 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             const subHandle = materialHandles[mi] ?? 0;
             if (subHandle === handleRaw) continue;
             const subEntry =
-              materialSnapshotCache.get(subHandle) ??
-              readPersistentMaterialSnapshot(persistentMaterialSnapshotCache, subHandle, assets);
+              (hasSkin ? skinnedMaterialSnapshotCache : materialSnapshotCache).get(subHandle) ??
+              (hasSkin
+                ? undefined
+                : readPersistentMaterialSnapshot(
+                    persistentMaterialSnapshotCache,
+                    subHandle,
+                    assets,
+                  ));
             appendMaterialDispatchEntries(
               pendingDispatch,
               subEntry?.passes ?? (subHandle === 0 ? [DEFAULT_FORWARD_PASS] : []),
@@ -2639,7 +2680,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               layerVal,
               materialsArr[mi]?.paramSnapshot,
               0,
-              materialsArr[mi]?.materialShaderId,
+              materialsArr[mi]?.materialProgramKeys,
             );
           }
         }