@forgeax/engine-render 0.1.23 → 0.1.24

package/src/record/render-context.ts

@@ -20,7 +20,11 @@ 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 {
   MaterialRenderState,
   ParamSchemaEntry,
@@ -28,6 +32,7 @@ import type {
   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 +108,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,6 +150,8 @@ 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;
@@ -180,11 +199,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 +221,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 +383,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 +415,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 +523,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/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;