@forgeax/engine-render 0.1.24 → 0.1.26

package/src/record/shadow-pass.ts

@@ -1,3 +1,4 @@
+import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import {
   type BindGroup,
   type BindGroupEntry,
@@ -8,14 +9,8 @@ import {
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, PassSelector } from '@forgeax/engine-types';
-import { GpuBuffer } from '../gpu-resource';
-import {
-  GPU_BUFFER_USAGE_COPY_DST,
-  GPU_BUFFER_USAGE_STORAGE,
-  GPU_BUFFER_USAGE_UNIFORM,
-} from '../gpu-usage';
+import type { GpuBuffer } from '../gpu-resource';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
-import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import {
   buildPbrMaterialUserRegionEntries,
   createPbrSkinMeshBindGroupEntries,
@@ -26,18 +21,23 @@ import {
 import { COOKIE_MATRIX_BYTES } from '../prepare/extended-lighting/resources';
 import type { DispatchEntry, ExtractedLights } from '../render-system-extract';
 import { matchPass } from '../systems/pass-selector';
-import { worldEntityKey } from './frame-snapshot';
-import { resolveGeometryInstancesBindGroup } from './main-pass-geometry';
+import {
+  resolveGeometryInstanceBuffer,
+  resolveGeometryInstancesBindGroup,
+} from './main-pass-geometry';
+import {
+  buildPerSubmeshMaterialBg,
+  type PerSubmeshMaterialBgDeps,
+  prepareMaterialSkylight,
+} from './main-pass-material';
 import {
   getOrCreateFromChain,
-  MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
   MESH_SSBO_BYTES,
   MESH_UBO_FULL_ARRAY_BYTES,
-  packInstanceStorageBuffer,
 } 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;
@@ -253,13 +253,15 @@ function ensureTypedShadowViewBg(
 }
 
 interface ShadowDispatch {
+  readonly vertexEntry: string | undefined;
+  readonly fragmentEntry: string | undefined;
   readonly materialShaderId: string;
   readonly renderState: MaterialRenderState | undefined;
 }
 
 type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, ShadowDispatch>>;
 
-function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
+export function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
   const shaders = new Map<number, Map<number, ShadowDispatch>>();
   for (const entry of c.dispatch) {
     if (entry.tags.LightMode === 'ShadowCaster' && entry.materialShaderId !== undefined) {
@@ -269,7 +271,12 @@ function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
         shaders.set(entry.renderableIndex, byMaterial);
       }
       byMaterial.set(entry.materialHandle, {
-        materialShaderId: entry.materialShaderId,
+        vertexEntry: entry.vertexEntry,
+        fragmentEntry: entry.fragmentEntry,
+        materialShaderId:
+          entry.materialShaderId === 'forgeax::default-standard-pbr'
+            ? SHADOW_CASTER_SHADER_ID
+            : entry.materialShaderId,
         renderState: entry.renderState,
       });
     }
@@ -371,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,
@@ -385,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(
@@ -569,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
@@ -583,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];
@@ -593,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;
@@ -640,89 +656,25 @@ function recordShadowCasterDraws(
       shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
     }
 
-    // C1 + C2 (w12): per-entity instance buffer + instanceCount
-    let shadowInstanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
-    let shadowInstanceCount = 1;
-    const shadowInst = entry.source.instances;
-    if (shadowInst?.instanceCount === 0) continue;
-    if (shadowInst !== undefined) {
-      const uniformFallback = runtime.device.caps.storageBuffer === false;
-      // Over-cap uniform fallback can't fit the per-instance window — bind
-      // identity and let the shader collapse (same semantics as the main
-      // pass). Otherwise build/upload the per-entity instance buffer: storage
-      // by default, uniform when the device lacks storage buffers.
-      if (uniformFallback && shadowInst.instanceCount > MAX_UNIFORM_INSTANCES) {
-        shadowInstanceCount = shadowInst.instanceCount;
-        shadowInstanceBuffer = pipelineState.identityInstanceBuffer;
-      } else {
-        const bufUsage = uniformFallback
-          ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST
-          : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
-        const instancePayload = uniformFallback
-          ? shadowInst.transforms
-          : packInstanceStorageBuffer(shadowInst.transforms);
-        const requestedBytes = instancePayload.byteLength;
-        const cached = c.frameState.instanceBuffers.get(
-          worldEntityKey(entry.source.worldId, shadowInst.cacheKey),
-        );
-        let active: InstanceBufferCacheEntry | null = null;
-        if (
-          cached !== undefined &&
-          cached.uploadedArchVersion === shadowInst.archVersion &&
-          cached.uploadedByteLength === requestedBytes
-        ) {
-          active = cached;
-        } else if (requestedBytes > 0) {
-          const bufRes = runtime.device.createBuffer({
-            size: requestedBytes,
-            usage: bufUsage,
-            mappedAtCreation: false,
-          });
-          if (!bufRes.ok) {
-            runtime.errorRegistry.fire(bufRes.error);
-          } else {
-            // feat-20260619 M4 / F12: destroy the old cached buffer
-            // before replacing it with the new one (D-6).
-            if (cached !== undefined && !cached.buffer.isDestroyed) {
-              const r = cached.buffer.destroy();
-              if (!r.ok) runtime.errorRegistry.fire(r.error);
-            }
-            const newBuffer = new GpuBuffer(runtime.device, bufRes.value);
-            active = {
-              buffer: newBuffer,
-              uploadedArchVersion: shadowInst.archVersion,
-              uploadedByteLength: requestedBytes,
-            };
-            c.frameState.instanceBuffers.set(
-              worldEntityKey(entry.source.worldId, shadowInst.cacheKey),
-              active,
-            );
-          }
-        }
-        if (active !== null) {
-          const writeRes = runtime.device.queue.writeBuffer(
-            active.buffer.handle,
-            0,
-            instancePayload,
-          );
-          if (!writeRes.ok) {
-            runtime.errorRegistry.fire(writeRes.error);
-          } else {
-            shadowInstanceBuffer = active.buffer.handle;
-            shadowInstanceCount = Math.max(1, shadowInst.instanceCount);
-          }
-        }
-      }
-    }
+    // Main and shadow passes share one instance residency owner and upload receipt.
+    const shadowInstanceDraws = resolveGeometryInstanceBuffer(
+      c,
+      entry,
+      [
+        {
+          instanceBuffer: pipelineState.identityInstanceBuffer,
+          instanceBindGroup: resolveGeometryInstancesBindGroup(
+            c,
+            pipelineState.identityInstanceBuffer,
+          ),
+          instanceCount: 1,
+          probeOffset: -1,
+        },
+      ],
+      false,
+    );
+    if (shadowInstanceDraws === null) continue;
 
-    // Bind per-entity instances BG for @group(3) (or fallback identity).
-    // D-4: write end of the HDRP shadow-instances producer/consumer pair.
-    // outerKey = worldEntityKey(entry.source.worldId, entry.source.entityKey),
-    // handle = shadowInstanceBuffer; the HDRP main pass read end (:3820 below)
-    // must look up the same (compositeKey, instBuffer) leaf or the shadow
-    // instances silently drop.
-    const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);
-    shadowPass.setBindGroup(3, shadowInstancesBg);
     // feat-20260608 M4 / w16: per-submesh shadow draw loop.
     // Only draw submeshes whose topology is triangle-list or triangle-strip
     // (line-list / point-list submeshes cast no shadow and are skipped).
@@ -742,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,
@@ -766,19 +714,76 @@ 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 (entry.mesh.indexed) {
-        shadowPass.drawIndexed(sm.indexCount, shadowInstanceCount, sm.indexOffset, 0, 0);
+      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 {
-        shadowPass.draw(sm.vertexCount, shadowInstanceCount, 0, 0);
+        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) {
+          shadowPass.drawIndexed(sm.indexCount, instanceDraw.instanceCount, sm.indexOffset, 0, 0);
+        } else {
+          shadowPass.draw(sm.vertexCount, instanceDraw.instanceCount, 0, 0);
+        }
       }
     }
   }
+  return complete;
 }
 
 /**

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

@@ -28,6 +28,7 @@ import {
   postProcessShaderEntrySignature,
 } from '../fullscreen-post-process-pass';
 import { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import { disposeInstanceBufferChunks, disposeInstanceBuffers } from '../instance-buffer-cache';
 import { inspectStandardLighting } from '../pipeline/standard-lighting/inspection';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import { inspectPointShadow } from '../point-shadow-inspection';
@@ -35,6 +36,7 @@ import type { PreparedGraphicsResolver } from '../prepare/prepared-graphics-reso
 import { validateRenderables } from '../record/frame';
 import { prepareFrameLighting } from '../record/frame-lighting';
 import type { RenderFrameState, ValidatedRenderable } from '../record/frame-snapshot';
+import { resolveGeometryInstanceBuffer } from '../record/main-pass-geometry';
 import { computeSplitLdrSprite } from '../record/main-pass-sprite-draws';
 import {
   prepareRecoveryPipelineReadiness,
@@ -121,7 +123,7 @@ export interface RenderSystemRecoveryOwner {
   setLastSuccessfulFrameSeed(seed: RecoveryFrameSeed): void;
   prepareRecoveryGraphCandidate(
     runtime: RecoveryGraphCandidateRuntime,
-  ): RecoveryGraphCandidatePreparation;
+  ): Promise<RecoveryGraphCandidatePreparation>;
   submitCandidateSetup(
     candidate: RecoveryGraphCandidate,
     isValid: () => boolean,
@@ -225,6 +227,8 @@ export function createRenderSystemRecovery(
       currentDirectionalShadowView: null,
       currentSpotShadowView: null,
       instanceBuffers: new Map(),
+      instanceBufferChunks: new Map(),
+      instanceResidency: new Map(),
       morphBuffers: new Map(),
       hdrpClusterBinScratch: createClusterBinScratch(),
       hdrpClusterGridScratch: null,
@@ -313,9 +317,9 @@ export function createRenderSystemRecovery(
     candidate.release();
   };
 
-  const prepareRecoveryGraphCandidate = (
+  const prepareRecoveryGraphCandidate = async (
     runtime: RecoveryGraphCandidateRuntime,
-  ): RecoveryGraphCandidatePreparation => {
+  ): Promise<RecoveryGraphCandidatePreparation> => {
     const seed = lastSuccessfulFrameSeed;
     if (seed === undefined) return { kind: 'no-seed' };
     const camera = seed.frame.cameras[0];
@@ -382,6 +386,13 @@ export function createRenderSystemRecovery(
       candidateGpuDrivenScene = undefined;
       candidatePointsLines?.release();
       candidatePointsLines = undefined;
+      disposeInstanceBuffers(candidateFrameState.instanceBuffers, runtime.internals.errorRegistry);
+      if (candidateFrameState.instanceBufferChunks !== undefined) {
+        disposeInstanceBufferChunks(
+          candidateFrameState.instanceBufferChunks,
+          runtime.internals.errorRegistry,
+        );
+      }
       candidateGpuStore.destroyAll();
     };
     const markPublished = (): void => {
@@ -403,10 +414,17 @@ export function createRenderSystemRecovery(
       if (!gpuScene.ok) return failed('candidate GPU scene preparation failed', gpuScene.error);
       candidateGpuDrivenScene = gpuScene.value;
       if (candidateGpuDrivenScene.state !== undefined) {
-        candidateGpuDrivenProduction = GpuDrivenProduction.forDevice(
+        const production = await GpuDrivenProduction.forRecoveryDevice(
           runtime.internals.device,
           gpuDrivenShaderFactory,
+          (descriptor) =>
+            internals.createShaderModule === undefined
+              ? Promise.resolve(gpuDrivenShaderFactory.createShaderModule(descriptor))
+              : internals.createShaderModule(runtime.internals.device, descriptor),
         );
+        if (!production.ok)
+          return failed('candidate GPU-driven shader preparation failed', production.error);
+        candidateGpuDrivenProduction = production.value;
         const prepared = candidateGpuDrivenProduction.prepare({
           scene: candidateGpuDrivenScene.state,
           camera,
@@ -578,6 +596,25 @@ export function createRenderSystemRecovery(
       if (candidateValidated.length !== seed.frame.renderables.length) {
         return failed('candidate validation did not retain every LKG-visible renderable');
       }
+      for (const entry of candidateValidated) {
+        if (entry.source.instances === undefined) continue;
+        const prepared = resolveGeometryInstanceBuffer(
+          {
+            runtime: runtime.internals,
+            pipelineState: runtime.pipelineState,
+            frameState: candidateFrameState,
+            bindGroupCounts: { createBindGroup: 0, keys: [] },
+          },
+          entry,
+          [],
+          false,
+        );
+        if (prepared === null) return failed('candidate instance preparation failed');
+      }
+      // These uploads belong to recovery preparation, never to a rendered frame.
+      for (const [id, residency] of candidateFrameState.instanceResidency ?? []) {
+        candidateFrameState.instanceResidency?.set(id, { ...residency, frameNumber: -1 });
+      }
       const lighting = prepareFrameLighting(
         runtime.internals,
         candidateFrameState,
@@ -602,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-contract.ts

@@ -42,6 +42,7 @@ import type {
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types';
+import type { InstanceCollectionInspection } from './instances';
 import type { SsrAdmissionIdentity } from './ssr/identity';
 import type {
   RenderTarget,
@@ -294,6 +295,7 @@ export interface SpotLightProjectorFrameContext {
  * leases, receipts, inspection PODs, and recovery Result values.
  */
 export interface Renderer {
+  /** Renderer-owned authoring and update path for large instance collections. */
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
@@ -509,6 +511,8 @@ export interface RenderInspection {
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
+  /** Renderer-owned large-instance residency and upload facts. */
+  readonly instanceCollections: readonly InstanceCollectionInspection[];
   readonly renderScene: RenderSceneInspection;
   readonly reflectionProbes: ReflectionProbeInspection;
   /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */