@forgeax/engine-render 0.1.23 → 0.1.25

package/src/record/render-context.ts

@@ -20,14 +20,20 @@ import type {
   TextureView,
 } from '@forgeax/engine-rhi';
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
-import type { MaterialRuntimeArtifact, MaterialShaderArtifact } from '@forgeax/engine-shader';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  type MaterialRuntimeArtifact,
+  type MaterialShaderArtifact,
+} from '@forgeax/engine-shader';
 import type {
+  MaterialAsset,
   MaterialRenderState,
   ParamSchemaEntry,
   PassKind,
   PrimitiveTopology,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
 import type { MaterialRenderProjection } from '../assembly/material/assembly';
 import type { DeviceScope } from '../device/device-scope';
 import type { MeshGpuHandles } from '../device/gpu-residency';
@@ -103,6 +109,18 @@ export interface MaterialShaderPipelineEntry {
   readonly group2Contract: PipelineGroup2Contract;
 }
 
+/**
+ * Armed only for the first published recovery frame. Candidate preparation
+ * must make every pipeline and static residency lookup a cache hit before this
+ * guard is armed; a miss is a hard failure before queue submission.
+ */
+export interface RecoveryColdWorkGuard {
+  arm(): void;
+  notePipelineColdWork(): void;
+  noteUploadColdWork(): void;
+  finish(): void;
+}
+
 import type {
   RenderDebugOverlay,
   RenderPipelineContext,
@@ -133,9 +151,14 @@ export interface RenderSystemRuntime {
   /** Internal backend-fixture hook evaluated at the submit transaction edge. */
   readonly beforeSubmit?: ((device: RhiDevice) => RhiError | undefined) | undefined;
   readonly deviceScope: DeviceScope;
+  /** Resolve a recorder/backend wrapper before configuring the native surface. */
+  readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
   readonly errorRegistry: RhiErrorListenerRegistry;
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly healthRegistry: HealthListenerRegistry;
+  readonly getMaterialProjectionForPayload?: (
+    material: MaterialAsset,
+  ) => MaterialRenderProjection | undefined;
   readonly getMaterialProjection?: (materialGuid: string) => MaterialRenderProjection | undefined;
   readonly getMaterialArtifact?: (specializationKey: string) => MaterialRuntimeArtifact | undefined;
   /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
@@ -180,11 +203,17 @@ export interface RenderSystemRuntime {
     layoutKindOverride?: 'pbr' | 'pbr-skin',
     additionalColorFormats?: readonly GPUTextureFormat[],
   ) => MaterialShaderPipelineEntry | null;
+  /** Reflection-derived UV count included in the material PipelineSpec cache key. */
+  readonly getMaterialShaderUvSetCount?: (materialShaderId: string) => number | undefined;
   readonly getMaterialShaderBindingContract?: (
     materialShaderId: string,
   ) => 'group-0' | 'group-0-resource' | 'view-only' | 'view-and-scene-depth' | 'render-material';
   readonly getParamSchema?: (materialShaderId: string) => readonly ParamSchemaEntry[] | undefined;
-  readonly getMaterialBindGroupLayout?: (materialShaderId: string) => BindGroupLayout | undefined;
+  readonly getMaterialBindGroupLayout?: (
+    materialShaderId: string,
+    materialParamSchema?: readonly ParamSchemaEntry[],
+  ) => BindGroupLayout | undefined;
+  recoveryColdWorkGuard?: RecoveryColdWorkGuard | undefined;
   readonly metrics: EngineMetrics;
   readonly lookupPostProcess?: (
     id: string,
@@ -196,6 +225,8 @@ export interface RenderSystemRuntime {
     colorFormat: GPUTextureFormat,
     entry?: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
+  /** Candidate-owned post-process pipelines transferred at publication. */
+  readonly getRecoveryPostProcessPipelines?: () => ReadonlyMap<string, RhiRenderPipeline>;
   readonly clearPostProcessPipelineCache?: (id: string) => void;
   readonly invalidateShaderModule?: (label: string) => void;
   readonly dynamicTextureStore?: DynamicTextureStore | undefined;
@@ -356,6 +387,8 @@ export interface PipelineState {
   readonly skinPaletteAllocator: SkinPaletteAllocator | null;
   readonly defaultWhiteTextureView: TextureView;
   readonly defaultNormalTextureView: TextureView;
+  /** Missing anisotropy maps encode a neutral direction and unit strength. */
+  readonly defaultAnisotropyTextureView?: TextureView;
   readonly unlitPipelineHdr: RhiRenderPipeline | null;
   readonly shadowFallbackTextureView: TextureView;
   readonly shadowAtlasFallbackTextureView: TextureView;
@@ -386,6 +419,8 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly standardProfile?: StandardProfile | undefined;
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
+  /** Install a detached feature host only at the recovery publication boundary. */
+  readonly setFeatureHost?: ((host: RenderFeatureHost) => void) | undefined;
   readonly shaderModuleFactory?: PipelineBuilderShaderModuleFactory;
   readonly createShaderModule?: (
     device: import('@forgeax/engine-rhi').RhiDevice,
@@ -492,8 +527,8 @@ export type _InternalRenderPipelineContext = RenderPipelineContext & _StandardFo
 
 export type RecordProfileRunner = <T>(phase: RenderRecordPhase, action: () => T) => T;
 
-export const STANDARD_PBR_UBO_SIZE = 384;
-export const MATERIAL_PER_ENTITY_STRIDE = 512;
+export const STANDARD_PBR_UBO_SIZE = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA).uboLayout.totalBytes;
+export const MATERIAL_PER_ENTITY_STRIDE = Math.ceil(STANDARD_PBR_UBO_SIZE / 256) * 256;
 
 export type SwapChainFormatPair = {
   readonly storage: GPUTextureFormat;

package/src/record/shadow-pass.ts

@@ -8,14 +8,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,15 +20,15 @@ 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 {
   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';
@@ -253,13 +247,16 @@ function ensureTypedShadowViewBg(
 }
 
 interface ShadowDispatch {
+  readonly materialHandle: number;
   readonly materialShaderId: string;
   readonly renderState: MaterialRenderState | undefined;
+  readonly materialSlot: number | undefined;
+  readonly paramSnapshot: DispatchEntry['paramSnapshot'];
 }
 
 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) {
@@ -268,9 +265,20 @@ function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
         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, {
-        materialShaderId: entry.materialShaderId,
+        materialHandle: entry.materialHandle,
+        materialShaderId:
+          entry.materialShaderId === 'forgeax::default-standard-pbr'
+            ? SHADOW_CASTER_SHADER_ID
+            : entry.materialShaderId,
         renderState: entry.renderState,
+        materialSlot,
+        paramSnapshot: entry.paramSnapshot,
       });
     }
   }
@@ -640,89 +648,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).
@@ -772,10 +716,13 @@ function recordShadowCasterDraws(
         shadowPass.setPipeline(entryShadowPipeline);
         shadowLastPipeline = entryShadowPipeline;
       }
-      if (entry.mesh.indexed) {
-        shadowPass.drawIndexed(sm.indexCount, shadowInstanceCount, sm.indexOffset, 0, 0);
-      } else {
-        shadowPass.draw(sm.vertexCount, shadowInstanceCount, 0, 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);
+        }
       }
     }
   }

package/src/record/typed-frame-graph.ts

@@ -811,6 +811,7 @@ export interface RenderFeatureGraphCandidate {
 }
 
 const featureGraphStates = new WeakMap<RenderSystemInternals, RenderFeatureGraphRuntimeState>();
+const graphDeviceGenerations = new WeakMap<object, number>();
 
 interface TimingInstrumentationState {
   readonly instrumentation: RenderGraphPassInstrumentation<RenderPipelineFrame>;
@@ -1349,6 +1350,7 @@ export function ensureCompiledFrameGraph(
   volumetricFog?: ExtractedVolumetricFog,
   volumeTopologyCandidate = false,
   standardLighting?: StandardTopologyInputValue,
+  onRecoveryError?: (error: unknown) => void,
 ): CompiledRenderGraph<RenderPipelineFrame> | null {
   const requestedStandardLightingSignature = standardLightingTopologySignature(standardLighting);
   const lastKnownGood = (): CompiledRenderGraph<RenderPipelineFrame> | null =>
@@ -1361,6 +1363,7 @@ export function ensureCompiledFrameGraph(
   const featurePlans = featureGraphCandidate?.plans ?? getRenderFeatureGraphState(internals).plans;
   const projectedFeaturePlans = validateRenderFeaturePlans(featurePlans);
   if (!projectedFeaturePlans.ok) {
+    onRecoveryError?.(projectedFeaturePlans.error);
     reportRenderFeatureGraphError(internals, projectedFeaturePlans.error);
     featureGraphCandidate?.onRejected?.();
     return volumeTopologyCandidate ? null : lastKnownGood();
@@ -1383,6 +1386,7 @@ export function ensureCompiledFrameGraph(
     standardLighting,
   );
   if (!topologyResult.ok) {
+    onRecoveryError?.(topologyResult.error);
     internals.errorRegistry.fire(topologyResult.error);
     featureGraphCandidate?.onRejected?.();
     return volumeTopologyCandidate ? null : lastKnownGood();
@@ -1521,6 +1525,7 @@ export function ensureCompiledFrameGraph(
     topology,
   );
   if (!built.ok) {
+    onRecoveryError?.(built.error);
     internals.errorRegistry.fire(built.error);
     featureGraphCandidate?.onRejected?.();
     return volumeTopologyCandidate ? null : lastKnownGood();
@@ -1530,6 +1535,7 @@ export function ensureCompiledFrameGraph(
     surfaceSize: { width: surfaceWidth, height: surfaceHeight },
   });
   if (!compiled.ok) {
+    onRecoveryError?.(compiled.error);
     internals.errorRegistry.fire(compiled.error);
     featureGraphCandidate?.onRejected?.();
     return lastKnownGood();
@@ -1552,6 +1558,10 @@ export function ensureCompiledFrameGraph(
     getColorTargetTexture: (name) => compiledTargets.getColorTargetTexture(name),
     graphGeneration: frameState.graphGeneration,
   };
+  const deviceGeneration = internals.deviceScope?.generation;
+  if (deviceGeneration !== undefined) {
+    graphDeviceGenerations.set(compiled.value, deviceGeneration);
+  }
   gpuDriven?._commitResourceReplacement();
   if (featureGraphCandidate !== undefined && !postProcessAdmission.pending) {
     commitFeatureCandidate(internals, featureGraphCandidate);
@@ -1635,6 +1645,29 @@ export function executeCompiledFrameGraph(
       : legacyTimingInstrumentation;
   type PreparedCommand = { readonly command: CommandBuffer };
   let preparedCommand: PreparedCommand = { command: undefined as never };
+  const deviceScope = internals.deviceScope;
+  const graphDeviceGeneration = graphDeviceGenerations.get(graph);
+  if (
+    graphDeviceGeneration !== undefined &&
+    deviceScope !== undefined &&
+    graphDeviceGeneration !== deviceScope.generation
+  ) {
+    internals.errorRegistry.fire(
+      new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'the compiled frame graph belongs to the active device generation',
+        hint: 'discard the stale graph and rebuild it from the retained logical frame plan',
+        detail: {
+          error: {
+            code: 'stale-frame-graph-generation',
+            message: `graph=${graphDeviceGeneration}; current=${deviceScope.generation}`,
+          },
+        },
+      }),
+    );
+    return false;
+  }
+  const capturedGeneration = deviceScope?.generation;
   const transaction = executeRendererFrameTransaction<PreparedCommand>({
     build: () => ({ ok: true, value: { command: undefined as never } }),
     execute: () => {
@@ -1662,7 +1695,7 @@ export function executeCompiledFrameGraph(
         const graphAccess = frameState.perFrameGraph;
         const graphTexture = graphAccess?.getColorTargetTexture(graphCapture.name);
         const descriptor = graphAccess?.getColorTargetDescriptor(graphCapture.name);
-        const frameId = frameState.frameNumber - 1;
+        const frameId = frameState.frameNumber;
         const captureFailure = (message: string): void => {
           internals.errorRegistry.fire(
             new RhiError({
@@ -1865,6 +1898,17 @@ export function executeCompiledFrameGraph(
       timingCapture?.markSubmitted();
       return { ok: true, value: undefined };
     },
+    ...(capturedGeneration === undefined || deviceScope === undefined
+      ? {}
+      : {
+          generationFence: {
+            capturedGeneration,
+            // Read the owner at submit time. Recovery publishes a replacement
+            // scope synchronously between finish and submit; retaining the
+            // entry scope here would make that race invisible to the fence.
+            currentGeneration: () => internals.deviceScope?.generation ?? -1,
+          },
+        }),
     commit: () => {
       frameHooks?.onSubmitted?.();
       if (frameState.temporalFrameInput !== undefined) {

package/src/record/view-ubo.ts

@@ -164,9 +164,9 @@ export function writeViewUbo(
   const VIEW_PAYLOAD_FLOATS = 240;
   const viewPayload = new Float32Array(VIEW_PAYLOAD_FLOATS);
   for (let i = 0; i < 16; i++) viewPayload[i] = mainProjection[i] ?? 0;
-  viewPayload[16] = (light.direction[0] ?? 0) * light.intensity;
-  viewPayload[17] = (light.direction[1] ?? -1) * light.intensity;
-  viewPayload[18] = (light.direction[2] ?? 0) * light.intensity;
+  viewPayload[16] = light.direction[0] ?? 0;
+  viewPayload[17] = light.direction[1] ?? -1;
+  viewPayload[18] = light.direction[2] ?? 0;
   viewPayload[20] = light.color[0] ?? 0;
   viewPayload[21] = light.color[1] ?? 0;
   viewPayload[22] = light.color[2] ?? 0;