@forgeax/engine-render 0.1.21 → 0.1.23

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

@@ -62,6 +62,7 @@ import type {
 } from '../render-pipeline';
 import type { ExtractedLights, ExtractedVolumetricFog } from '../render-system-extract';
 import { SHADOW_ATLAS_DEFAULT_FACE_SIZE, SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
+import type { SsrAdmissionResult } from '../ssr/admission';
 import type { RenderTarget } from '../targets/contracts';
 import type { RenderTargetPhysical } from '../targets/physical';
 import {
@@ -82,7 +83,7 @@ import { buildPerFrameBindGroups } from './frame-lighting';
 import { getTextureIdentity, type RenderFrameState } from './frame-snapshot';
 import type { GpuPassTimingPassIdentity } from './gpu-pass-timing/contract.js';
 import type { GpuPassTimingCapture, GpuPassTimingSession } from './gpu-pass-timing/session.js';
-import type { GpuTimingCapture, VolumeTimingTimestampWrites } from './gpu-timing';
+import type { GpuTimingCapture } from './gpu-timing';
 import { encodeMainPass } from './main-pass';
 import type {
   _InternalRenderPipelineContext,
@@ -104,6 +105,97 @@ export interface TemporalGraphRoster {
   readonly uploads: number;
 }
 
+export interface ReflectionFallbackGraphRoster {
+  readonly enabled: boolean;
+  readonly attachments: readonly string[];
+  readonly passes: readonly string[];
+  readonly bindings: readonly string[];
+  readonly historyCount: 0;
+  readonly temporalDemand: 0;
+}
+
+export interface ReflectionFallbackGraphCandidate {
+  readonly generation: number;
+  readonly source: 'probe' | 'skylight' | 'neutral';
+  readonly roster: ReflectionFallbackGraphRoster;
+}
+
+export interface SsrAdmissionGraphRoster {
+  readonly enabled: boolean;
+  readonly attachments: readonly string[];
+  readonly passes: readonly string[];
+  readonly bindings: readonly string[];
+  readonly historyCount: 0;
+  readonly temporalDemand: 0;
+}
+
+/**
+ * Admission is the sole switch for parent SSR graph work. A blocked result
+ * projects to an empty roster, so missing receipts cannot allocate or bind
+ * any SSR resource.
+ */
+export function createSsrAdmissionGraphRoster(
+  admission: Pick<SsrAdmissionResult, 'status'>,
+): SsrAdmissionGraphRoster {
+  if (admission.status !== 'admitted') {
+    return {
+      enabled: false,
+      attachments: [],
+      passes: [],
+      bindings: [],
+      historyCount: 0,
+      temporalDemand: 0,
+    };
+  }
+  return {
+    enabled: true,
+    attachments: ['ssr-reflection-admission'],
+    passes: ['ssr-m0-admission'],
+    bindings: ['ssr-reflection-admission'],
+    historyCount: 0,
+    temporalDemand: 0,
+  };
+}
+
+export type ReflectionFallbackGraphFailure = 'compile-failed' | 'encode-failed' | 'submit-failed';
+
+export function createReflectionFallbackGraphRoster(input: {
+  readonly fallbackDemand: boolean;
+}): ReflectionFallbackGraphRoster {
+  if (!input.fallbackDemand) {
+    return {
+      enabled: false,
+      attachments: [],
+      passes: [],
+      bindings: [],
+      historyCount: 0,
+      temporalDemand: 0,
+    };
+  }
+  return {
+    enabled: true,
+    attachments: ['reflection-fallback-linear-hdr'],
+    passes: ['standard-main'],
+    bindings: ['reflection-fallback-output'],
+    historyCount: 0,
+    temporalDemand: 0,
+  };
+}
+
+export function commitReflectionFallbackGraph(
+  candidate: ReflectionFallbackGraphCandidate,
+  result:
+    | { readonly ok: true }
+    | { readonly ok: false; readonly reason: ReflectionFallbackGraphFailure },
+): {
+  readonly visible: boolean;
+  readonly generation: number;
+  readonly source?: ReflectionFallbackGraphCandidate['source'];
+} {
+  if (!result.ok || !candidate.roster.enabled) return { visible: false, generation: 0 };
+  return { visible: true, generation: candidate.generation, source: candidate.source };
+}
+
 function importTemporalHistoryTarget(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   label: string,
@@ -730,16 +822,6 @@ const timingInstrumentationStates = new WeakMap<
   TimingInstrumentationState
 >();
 
-interface VolumeTimingInstrumentationState {
-  readonly instrumentation: RenderGraphPassInstrumentation<RenderPipelineFrame>;
-  setCapture(capture: GpuTimingCapture | undefined): void;
-}
-
-const volumeTimingInstrumentationStates = new WeakMap<
-  RenderSystemInternals,
-  VolumeTimingInstrumentationState
->();
-
 type CompiledGraphTargetAccess = CompiledRenderGraph<RenderPipelineFrame> & {
   readonly getColorTargetDescriptor: (
     name: string,
@@ -930,6 +1012,7 @@ function topologyOf(
     standardProfile: internals.standardProfile,
     config,
     clearOnly,
+    reflectionFallback: { enabled: frameState.reflectionFallbackDemand === true },
     surface: {
       width,
       height,
@@ -1262,6 +1345,7 @@ export function ensureCompiledFrameGraph(
   cubeCaptureState?: CubeCaptureGraphState,
   clearOnly = false,
   transmissionDemand?: TransmissionDemand,
+  occlusion?: import('../scene/visibility/occlusion-runtime').OcclusionFrameProjection,
   volumetricFog?: ExtractedVolumetricFog,
   volumeTopologyCandidate = false,
   standardLighting?: StandardTopologyInputValue,
@@ -1354,6 +1438,17 @@ export function ensureCompiledFrameGraph(
     : topologyResult.value;
   const key = JSON.stringify({
     topology,
+    // GPU-driven residency can become available after the first record pass
+    // (custom mesh handles are resolved into the per-frame projection).  The
+    // topology signature alone is intentionally stable across that lifecycle,
+    // so include the prepared projection's presence to invalidate a cached
+    // CPU-only graph when the GPU owner becomes ready, and vice versa.
+    gpuDrivenProjectionActive: gpuDriven !== undefined,
+    // Query reservations are frame-local transport state. The projection is
+    // renderer-owned and read dynamically by the compiled pass, so a page
+    // rotation must not invalidate the graph or its cached bind groups.
+    occlusionQuery:
+      occlusion === undefined ? undefined : { active: true, sampleCount: occlusion.sampleCount },
     cubeCaptureSlots: cubeCaptureState?.work.length ?? 0,
     reflectionProbeSlots: cubeCaptureState?.reflectionProbes?.work.map((work) => [
       work.probeIndex,
@@ -1385,6 +1480,7 @@ export function ensureCompiledFrameGraph(
       graph: builder,
       ...(standardLighting === undefined ? {} : { standardLighting }),
       capabilities: { rgba16floatRenderable: internals.device.caps.rgba16floatRenderable },
+      ...(occlusion === undefined ? {} : { occlusion }),
       ...(taaHistory === undefined ? {} : { taaHistory }),
       encodeTransmissionMip: ({ pass, resources, source }) => {
         const sourceView = resources.textureView(source);
@@ -1472,6 +1568,11 @@ export function executeCompiledFrameGraph(
   frame: RenderPipelineFrame,
   encoder: RhiCommandEncoder,
   runPass?: import('@forgeax/engine-render-graph').RenderGraphPassRunner,
+  frameHooks?: {
+    readonly afterGraphExecute?: () => Result<void, RhiError>;
+    readonly onSubmitted?: () => void;
+    readonly onAborted?: () => void;
+  },
   readbackFaces?: readonly number[],
   onSubmitted?: (completed: Promise<unknown>) => void,
   timingCapture?: GpuTimingCapture,
@@ -1494,6 +1595,8 @@ export function executeCompiledFrameGraph(
     rejectTemporalFrame();
     return false;
   }
+  const legacyTimingInstrumentation =
+    timingCapture === undefined ? undefined : createTimingInstrumentation(timingCapture);
   const timingHost = internals as RenderSystemInternals & {
     gpuPassTimingSession?: GpuPassTimingSession | undefined;
     gpuPassTimingCapture?: GpuPassTimingCapture | undefined;
@@ -1525,19 +1628,31 @@ export function executeCompiledFrameGraph(
       ? getTimingInstrumentationState(internals, passTimingCapture)
       : timingCapture === undefined
         ? undefined
-        : getVolumeTimingInstrumentationState(internals, timingCapture);
+        : undefined;
+  const graphInstrumentation =
+    passTimingCapture !== undefined
+      ? timingInstrumentationState?.instrumentation
+      : legacyTimingInstrumentation;
   type PreparedCommand = { readonly command: CommandBuffer };
   let preparedCommand: PreparedCommand = { command: undefined as never };
   const transaction = executeRendererFrameTransaction<PreparedCommand>({
     build: () => ({ ok: true, value: { command: undefined as never } }),
     execute: () => {
-      const executed = graph.execute(frame, runPass, timingInstrumentationState?.instrumentation);
+      const executed = graph.execute(frame, runPass, graphInstrumentation);
       timingInstrumentationState?.setCapture(undefined);
       if (!executed.ok) {
         passTimingCapture?.abort({ code: executed.error.code });
         internals.errorRegistry.fire(executed.error);
         return { ok: false, stage: 'execute' };
       }
+      const afterGraphExecute = frameHooks?.afterGraphExecute;
+      if (afterGraphExecute !== undefined) {
+        const recorded = afterGraphExecute();
+        if (!recorded.ok) {
+          internals.errorRegistry.fire(recorded.error);
+          return { ok: false, stage: 'execute' };
+        }
+      }
       return { ok: true, value: undefined };
     },
     finish: () => {
@@ -1664,6 +1779,43 @@ export function executeCompiledFrameGraph(
           );
         }
       }
+      const fallbackReadback = frameState.reflectionFallbackReadback;
+      frameState.reflectionFallbackReadback = undefined;
+      if (fallbackReadback !== undefined) {
+        const graphAccess = frameState.perFrameGraph;
+        const graphTexture = graphAccess?.getColorTargetTexture(fallbackReadback.name);
+        const descriptor = graphAccess?.getColorTargetDescriptor(fallbackReadback.name);
+        const matches =
+          graphAccess !== undefined &&
+          graphAccess !== null &&
+          graphTexture !== undefined &&
+          descriptor !== undefined &&
+          descriptor.format === fallbackReadback.expected.format &&
+          descriptor.size.width === fallbackReadback.expected.width &&
+          descriptor.size.height === fallbackReadback.expected.height &&
+          descriptor.sample === 1 &&
+          (descriptor.usage & fallbackReadback.expected.usage) ===
+            fallbackReadback.expected.usage &&
+          graphAccess.graphGeneration === fallbackReadback.expected.graphGeneration &&
+          frameState.frameNumber === fallbackReadback.expected.frameId &&
+          getTextureIdentity(graphTexture) === fallbackReadback.expected.textureIdentity;
+        if (matches && graphTexture !== undefined) {
+          encoder.copyTextureToBuffer(
+            { texture: graphTexture },
+            {
+              buffer: fallbackReadback.buffer,
+              bytesPerRow: fallbackReadback.bytesPerRow,
+              rowsPerImage: fallbackReadback.height,
+            },
+            {
+              width: fallbackReadback.width,
+              height: fallbackReadback.height,
+              depthOrArrayLayers: 1,
+            },
+          );
+          fallbackReadback.encoded = true;
+        }
+      }
       internals.encodeRenderTargetReadbacks?.(encoder, readbackFaces);
       const stagedGpuState = frameState.temporalGpuState;
       if (stagedGpuState !== undefined && !hasPendingTemporalGpuSubmit(stagedGpuState)) {
@@ -1696,6 +1848,13 @@ export function executeCompiledFrameGraph(
       return { ok: true, value: undefined };
     },
     submit: () => {
+      const injectedFailure = internals.beforeSubmit?.(internals.device);
+      if (injectedFailure !== undefined) {
+        passTimingCapture?.abort({ code: injectedFailure.code });
+        timingCapture?.discard();
+        internals.errorRegistry.fire(injectedFailure);
+        return { ok: false, stage: 'submit' };
+      }
       const submitted = internals.device.queue.submit([preparedCommand.command]);
       if (!submitted.ok) {
         passTimingCapture?.abort({ code: submitted.error.code });
@@ -1707,6 +1866,23 @@ export function executeCompiledFrameGraph(
       return { ok: true, value: undefined };
     },
     commit: () => {
+      frameHooks?.onSubmitted?.();
+      if (frameState.temporalFrameInput !== undefined) {
+        const temporal = frameState.temporalFrameTransaction.commit({ accepted: true });
+        if (temporal.ok) {
+          frameState.temporalFrame = temporal.value;
+        } else {
+          internals.errorRegistry.fire(
+            new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'the staged temporal frame to commit after queue submission',
+              hint: 'discard the temporal candidate and retry the next frame',
+              detail: { error: temporal.error },
+            }),
+          );
+        }
+        frameState.temporalFrameInput = undefined;
+      }
       if (passTimingCapture !== undefined) {
         const completion = internals.device.queue.onSubmittedWorkDone();
         timingHost.gpuPassTimingSubmittedWork = completion;
@@ -1783,6 +1959,7 @@ export function executeCompiledFrameGraph(
       onSubmitted?.(internals.device.queue.onSubmittedWorkDone());
     },
     abort: (failure) => {
+      frameHooks?.onAborted?.();
       passTimingCapture?.abort({ code: failure.stage });
       timingHost.gpuPassTimingCapture = undefined;
       timingHost.gpuPassTimingSubmittedWork = undefined;
@@ -1814,6 +1991,41 @@ export function executeCompiledFrameGraph(
   return transaction.ok;
 }
 
+function createTimingInstrumentation(
+  capture: GpuTimingCapture,
+): RenderGraphPassInstrumentation<RenderPipelineFrame> {
+  return {
+    begin: (pass): RenderGraphPassInstrumentationScope | undefined => {
+      // WebGPU has no portable timestamp boundary for a copy pass. Do not
+      // pretend a command-encoder marker exists; frame timing remains valid
+      // when at least one raster/compute pass is present.
+      if (pass.kind === 'copy') return undefined;
+      const writes = capture.beginPass(pass.name, pass.kind, pass.executionIndex);
+      if (writes === undefined) return undefined;
+      if (pass.kind === 'raster') {
+        return {
+          renderPassDescriptor: (descriptor) => {
+            if (descriptor.timestampWrites !== undefined) {
+              capture.markOwnerConflict(pass.name);
+              return descriptor;
+            }
+            return { ...descriptor, timestampWrites: writes };
+          },
+        };
+      }
+      return {
+        computePassDescriptor: (descriptor) => {
+          if (descriptor.timestampWrites !== undefined) {
+            capture.markOwnerConflict(pass.name);
+            return descriptor;
+          }
+          return { ...descriptor, timestampWrites: writes };
+        },
+      };
+    },
+  };
+}
+
 function getTimingInstrumentationState(
   internals: RenderSystemInternals,
   capture: GpuPassTimingCapture,
@@ -1912,73 +2124,3 @@ function getTimingInstrumentationState(
   timingInstrumentationStates.set(internals, state);
   return state;
 }
-
-function getVolumeTimingInstrumentationState(
-  internals: RenderSystemInternals,
-  capture: GpuTimingCapture,
-): VolumeTimingInstrumentationState {
-  const existing = volumeTimingInstrumentationStates.get(internals);
-  if (existing !== undefined) {
-    existing.setCapture(capture);
-    return existing;
-  }
-  let activeCapture: GpuTimingCapture | undefined = capture;
-  let activePassName: string | undefined;
-  let activeWrites: VolumeTimingTimestampWrites | undefined;
-  const rasterScope: RenderGraphPassInstrumentationScope = {
-    renderPassDescriptor: (descriptor) => {
-      const currentCapture = activeCapture;
-      const passName = activePassName;
-      const writes = activeWrites;
-      if (currentCapture === undefined || passName === undefined || writes === undefined) {
-        return descriptor;
-      }
-      if (descriptor.timestampWrites !== undefined) {
-        currentCapture.skipPass(passName);
-        activeWrites = undefined;
-        return descriptor;
-      }
-      return { ...descriptor, timestampWrites: writes };
-    },
-  };
-  const computeScope: RenderGraphPassInstrumentationScope = {
-    computePassDescriptor: (descriptor) => {
-      const currentCapture = activeCapture;
-      const passName = activePassName;
-      const writes = activeWrites;
-      if (currentCapture === undefined || passName === undefined || writes === undefined) {
-        return descriptor;
-      }
-      if (descriptor.timestampWrites !== undefined) {
-        currentCapture.skipPass(passName);
-        activeWrites = undefined;
-        return descriptor;
-      }
-      return { ...descriptor, timestampWrites: writes };
-    },
-  };
-  const instrumentation: RenderGraphPassInstrumentation<RenderPipelineFrame> = {
-    begin: (pass) => {
-      const currentCapture = activeCapture;
-      if (currentCapture === undefined) return undefined;
-      activePassName = pass.name;
-      activeWrites = currentCapture.recordPass(pass.name);
-      if (activeWrites === undefined) return undefined;
-      if (pass.kind === 'raster') return rasterScope;
-      if (pass.kind === 'compute') return computeScope;
-      currentCapture.skipPass(pass.name);
-      activeWrites = undefined;
-      return undefined;
-    },
-  };
-  const state: VolumeTimingInstrumentationState = {
-    instrumentation,
-    setCapture: (nextCapture) => {
-      activeCapture = nextCapture;
-      activePassName = undefined;
-      activeWrites = undefined;
-    },
-  };
-  volumeTimingInstrumentationStates.set(internals, state);
-  return state;
-}

package/src/record/view-ubo.ts

@@ -9,7 +9,6 @@
 import { mat4 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
-import type { FogFrame } from '../extract/environment';
 import type { PointsLinesStyle } from '../points-lines/snapshot';
 import type { CameraSnapshot } from '../render-contract';
 import type {
@@ -140,18 +139,11 @@ export function writeViewUbo(
   light: DirectionalLightSnapshot,
   lights: ExtractedLights,
   spotShadowSnapshots: readonly SpotLightSnapshot[],
-  fogOrTemporalOrOffset?: FogFrame | TemporalView | LegacyTemporalView | number,
-  temporal?: TemporalView,
+  temporalOrOffset?: TemporalView | LegacyTemporalView | number,
   projectorSpotIndex?: number,
 ): void {
-  const byteOffset = typeof fogOrTemporalOrOffset === 'number' ? fogOrTemporalOrOffset : 0;
-  const fogOrTemporal =
-    typeof fogOrTemporalOrOffset === 'number' ? undefined : fogOrTemporalOrOffset;
-  const isTemporal =
-    fogOrTemporal !== undefined &&
-    ('currentJitterUv' in fogOrTemporal || 'currentUnjitteredViewProjection' in fogOrTemporal);
-  const fog = isTemporal ? undefined : fogOrTemporal;
-  const resolvedTemporal = temporal ?? (isTemporal ? fogOrTemporal : undefined);
+  const byteOffset = typeof temporalOrOffset === 'number' ? temporalOrOffset : 0;
+  const resolvedTemporal = typeof temporalOrOffset === 'number' ? undefined : temporalOrOffset;
   // Compose worldViewProj once per frame (view * proj).
   const projMatrix = computeProjectionMatrix(camera);
   const viewMatrix = computeViewMatrix(camera);
@@ -216,6 +208,16 @@ export function writeViewUbo(
   viewPayload[228] = camera.near;
   viewPayload[229] = camera.far;
   viewPayload[230] = camera.projection === 'orthographic' ? 1 : 0;
+  const previousCameraPosition =
+    resolvedTemporal !== undefined && 'previousCameraPosition' in resolvedTemporal
+      ? resolvedTemporal.previousCameraPosition
+      : undefined;
+  if (previousCameraPosition !== undefined) {
+    viewPayload[232] = previousCameraPosition[0] ?? 0;
+    viewPayload[233] = previousCameraPosition[1] ?? 0;
+    viewPayload[234] = previousCameraPosition[2] ?? 0;
+    viewPayload[235] = 1;
+  }
   // splitPlanes at [108..123] (four vec4 lanes: split/world texel/depth span/reserved).
   if (lights.splitPlanes !== undefined) {
     for (let s = 0; s < 4; s++) {
@@ -248,7 +250,7 @@ export function writeViewUbo(
   // spot index, not by a negative shadow tile: a projector-only spot publishes
   // its matrix in lane 0 so the shader never samples a zero matrix. Shadowed
   // projector spots keep their shadow tile lane and carry the projector bit in
-  // the LightSlot identity word.
+  // the DirectLightSlot identity word.
   // Folded from the former standalone binding 9 UBO to keep the WebGL2
   // fallback fragment uniform-buffer count <= 11 (GLES 3.0).
   {
@@ -272,18 +274,6 @@ export function writeViewUbo(
     }
   }
 
-  // Fog is a resource-owner semantic carried by the shared View ABI. Keep the
-  // disabled payload zeroed and write only the selected frame facts so both
-  // direct and clustered lanes consume the same owner projection.
-  if (fog !== undefined) {
-    viewPayload[232] = fog.color[0] ?? 0;
-    viewPayload[233] = fog.color[1] ?? 0;
-    viewPayload[234] = fog.color[2] ?? 0;
-    viewPayload[235] = fog.density;
-    viewPayload[236] = fog.heightFalloff;
-    viewPayload[237] = fog.maxOpacity;
-  }
-
   const viewUploadResult = queue.writeBuffer(viewUniformBuffer, byteOffset, viewPayload);
   if (!viewUploadResult.ok) throw viewUploadResult.error;
 

package/src/reflection/inspection.ts

@@ -0,0 +1,67 @@
+import type {
+  ReflectionFallbackFailureStage,
+  ReflectionFallbackInspection,
+  ReflectionFallbackReceipt,
+  ReflectionFallbackRecoveryAction,
+} from '../inspection-types';
+
+export interface ReflectionFallbackFailureInput {
+  readonly stage: ReflectionFallbackFailureStage;
+  readonly code: string;
+  readonly expected: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+function recoveryFor(
+  receipt: ReflectionFallbackReceipt,
+  failure?: ReflectionFallbackFailureInput,
+): ReflectionFallbackRecoveryAction {
+  if (failure !== undefined) {
+    const code = failure.code.toLowerCase();
+    if (code.includes('device') || code.includes('format') || code.includes('capability')) {
+      return 'rebuild';
+    }
+    if (failure.stage === 'prepare' || failure.stage === 'filter') return 'recapture';
+    if (failure.stage === 'build' || failure.stage === 'encode') return 'rebuild';
+    if (failure.stage === 'finish' || failure.stage === 'submit') return 'retry';
+    // Completion failures may still retain a source-identical committed row;
+    // use it as LKG, otherwise retry the producer completion.
+    if (failure.stage === 'completion') {
+      if (receipt.source === 'probe' && (receipt.state === 'active' || receipt.state === 'lkg')) {
+        return 'use-LKG';
+      }
+      if (
+        receipt.source === 'skylight' &&
+        (receipt.state === 'active' || receipt.state === 'lkg')
+      ) {
+        return 'use-Skylight';
+      }
+      if (receipt.source === 'neutral' && receipt.state === 'neutral') return 'use-neutral';
+      return 'retry';
+    }
+  }
+  if (receipt.source === 'probe' && (receipt.state === 'active' || receipt.state === 'lkg')) {
+    return 'use-LKG';
+  }
+  if (receipt.source === 'skylight' || receipt.state === 'lkg') return 'use-Skylight';
+  return 'use-neutral';
+}
+
+/** Projects producer state and the latest closed failure into detached facts. */
+export function inspectReflectionFallback(
+  receipt: ReflectionFallbackReceipt,
+  failure?: ReflectionFallbackFailureInput,
+): ReflectionFallbackInspection {
+  return {
+    receipt,
+    recoveryAction: recoveryFor(receipt, failure),
+    ...(failure === undefined
+      ? {}
+      : {
+          failureStage: failure.stage,
+          failureCode: failure.code,
+          expected: failure.expected,
+          ...(failure.detail === undefined ? {} : { detail: failure.detail }),
+        }),
+  };
+}