@forgeax/engine-render 0.1.7 → 0.1.20

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

@@ -1,3 +1,4 @@
+import { encodeMipmapLevel } from '@forgeax/engine-assets-runtime';
 import {
   type CompiledRenderGraph,
   type GraphResourceResolver,
@@ -10,8 +11,11 @@ import type {
   RhiCommandEncoder,
   Texture,
   TextureFormat,
+  TextureView,
 } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import { executeRendererFrameTransaction } from '../assembly/renderer-frame-transaction';
 import { type RenderError, RenderFeatureStageFailedError } from '../errors/render';
 import {
   getRenderFeaturePlanExecutionProjection,
@@ -24,19 +28,183 @@ import type {
   RenderFeatureGraphTargetResolver,
 } from '../features/render-graph-raster';
 import { isRenderFeatureTargetHandle } from '../features/targets';
+import {
+  buildFullscreenPostProcessPass,
+  createFullscreenBindGroup,
+  isTemporalFullscreenBinding,
+} from '../fullscreen-post-process-pass';
 import type { PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
-import { STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import { resolveVolumetricFogProfile, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
 import type { CameraSnapshot } from '../render-contract';
 import type {
   RenderPipelineFeatureTarget,
   RenderPipelineFrame,
   RenderPipelineTopology,
 } from '../render-pipeline';
-import type { ExtractedLights } from '../render-system-extract';
+import type { ExtractedLights, ExtractedVolumetricFog } from '../render-system-extract';
+import {
+  abortTemporalGpuSubmit,
+  commitTemporalGpuSubmit,
+  getTemporalGpuState,
+  hasPendingTemporalGpuSubmit,
+  retireTemporalGpuState,
+  retireTemporalGpuStateAfterFence,
+  temporalReadIndex,
+  temporalWriteIndex,
+} from '../temporal/gpu';
+import { isSceneDataTarget } from '../temporal/scene-data';
+import type { TransmissionDemand } from '../transmission/projection';
+import { hasVolumetricFogCapability } from '../volume/capability';
+import { deriveVolumetricFogExtent, deriveVolumetricFogResolvedExtent } from '../volume/resources';
 import { buildPerFrameBindGroups } from './frame-lighting';
-import type { RenderFrameState } from './frame-snapshot';
+import { getTextureIdentity, type RenderFrameState } from './frame-snapshot';
+import type { GpuTimingCapture } from './gpu-timing';
 import type { PipelineState, RenderSystemInternals } from './render-context';
-import { resolveSurfaceFormatPair } from './render-context';
+import { resolveSurfaceFormatPair, resolveSurfaceProfile } from './render-context';
+
+export interface TemporalGraphCapabilities {
+  readonly rgba16floatRender: boolean;
+  readonly rgba16floatSample: boolean;
+  readonly mrt: boolean;
+}
+
+export interface TemporalGraphRoster {
+  readonly enabled?: boolean;
+  readonly targets: readonly string[];
+  readonly passes: readonly string[];
+  readonly uploads: number;
+}
+
+function importTemporalHistoryTarget(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  label: string,
+  kind: 'color' | 'temporal',
+  role: 'read' | 'write',
+): import('../render-pipeline').RenderPipelineTarget {
+  const texture = graph.importTexture(
+    label,
+    {
+      format: 'rgba16float',
+      size: 'surface',
+      usage:
+        GPU_TEXTURE_USAGE_COPY_SRC |
+        GPU_TEXTURE_USAGE_COPY_DST |
+        GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+        GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    },
+    (frame) => {
+      const internal = frame as import('./render-context')._InternalRenderPipelineContext;
+      const state = getTemporalGpuState(
+        internal.frameState,
+        internal.runtime.device,
+        internal.runtime.deviceScope,
+        frame.targetW,
+        frame.targetH,
+      );
+      const index = role === 'read' ? temporalReadIndex(state) : temporalWriteIndex(state);
+      return (kind === 'color' ? state.color[index] : state.temporal[index]).texture;
+    },
+  );
+  if (!texture.ok) throw texture.error;
+  const view = graph.importView(
+    texture.value,
+    { label: `${label}.view`, dimension: '2d' },
+    (frame) => {
+      const internal = frame as import('./render-context')._InternalRenderPipelineContext;
+      const state = getTemporalGpuState(
+        internal.frameState,
+        internal.runtime.device,
+        internal.runtime.deviceScope,
+        frame.targetW,
+        frame.targetH,
+      );
+      const index = role === 'read' ? temporalReadIndex(state) : temporalWriteIndex(state);
+      return (kind === 'color' ? state.color[index] : state.temporal[index]).view;
+    },
+  );
+  if (!view.ok) throw view.error;
+  return { texture: texture.value, view: view.value, format: 'rgba16float', sampleCount: 1 };
+}
+
+function importTemporalHistoryTargets(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+): NonNullable<
+  import('../render-pipeline').RenderPipelineBuildContext<RenderPipelineFrame>['taaHistory']
+> {
+  return {
+    currentColor: importTemporalHistoryTarget(graph, 'taa-history-current-color', 'color', 'write'),
+    previousColor: importTemporalHistoryTarget(
+      graph,
+      'taa-history-previous-color',
+      'color',
+      'read',
+    ),
+    currentTemporal: importTemporalHistoryTarget(
+      graph,
+      'taa-history-current-temporal',
+      'temporal',
+      'write',
+    ),
+    previousTemporal: importTemporalHistoryTarget(
+      graph,
+      'taa-history-previous-temporal',
+      'temporal',
+      'read',
+    ),
+  };
+}
+
+export function shouldUseTemporalFrameTransaction(
+  antialias: CameraSnapshot['antialias'],
+  temporalDemand = false,
+): boolean {
+  return antialias === 'taa' || temporalDemand;
+}
+
+export function isMotionBlurTemporalDemand(
+  motionBlur: CameraSnapshot['motionBlur'] | undefined,
+): boolean {
+  return motionBlur?.shutterAngle !== undefined && motionBlur.shutterAngle > 0;
+}
+
+/**
+ * Derive the TAA topology from camera POD and backend capabilities. Both
+ * Standard lanes consume this declaration; the lane only affects lighting
+ * work and never creates a second temporal resolve.
+ */
+export function createTemporalGraphRoster(input: {
+  readonly antialias: 'none' | 'fxaa' | 'taa';
+  readonly lane: 'direct' | 'clustered';
+  readonly capabilities?: TemporalGraphCapabilities;
+}): TemporalGraphRoster {
+  if (input.antialias !== 'taa') return { targets: [], passes: [], uploads: 0 };
+  const capabilities = input.capabilities ?? {
+    rgba16floatRender: true,
+    rgba16floatSample: true,
+    mrt: true,
+  };
+  if (!capabilities.rgba16floatRender || !capabilities.rgba16floatSample || !capabilities.mrt) {
+    return { enabled: false, targets: [], passes: [], uploads: 0 };
+  }
+  return {
+    enabled: true,
+    targets: [
+      'standard-scene-temporal',
+      'taa-history-current-color',
+      'taa-history-previous-color',
+      'taa-history-current-temporal',
+      'taa-history-previous-temporal',
+    ],
+    passes: ['main', 'standard-scene-data', 'taa-resolve', 'output-transform'],
+    uploads: 1,
+  };
+}
 
 export interface RenderFeatureGraphRuntimeState {
   plans: readonly RenderFeaturePlannedFrame[];
@@ -66,6 +234,14 @@ export interface RenderFeatureGraphCandidate {
 
 const featureGraphStates = new WeakMap<RenderSystemInternals, RenderFeatureGraphRuntimeState>();
 
+type CompiledGraphTargetAccess = CompiledRenderGraph<RenderPipelineFrame> & {
+  readonly getColorTargetDescriptor: (
+    name: string,
+  ) => import('@forgeax/engine-render-graph').ResolvedColorTargetDescriptor | undefined;
+  readonly getColorTargetView: (name: string) => TextureView | undefined;
+  readonly getColorTargetTexture: (name: string) => Texture | undefined;
+};
+
 export function getRenderFeatureGraphState(
   internals: RenderSystemInternals,
 ): RenderFeatureGraphRuntimeState {
@@ -148,13 +324,16 @@ function topologyOf(
   frameState: RenderFrameState,
   pipelineState: PipelineState,
   camera: CameraSnapshot,
+  clearOnly: boolean,
   lights: ExtractedLights,
   width: number,
   height: number,
   shadowMapSize: number | undefined,
   gpuDriven: PreparedGpuDrivenFrame | undefined,
   featureGraphCandidate: RenderFeatureGraphCandidate | undefined,
-): RenderPipelineTopology {
+  transmissionDemand: TransmissionDemand | undefined,
+  volumetricFog: ExtractedVolumetricFog | undefined,
+): Result<RenderPipelineTopology, RhiError> {
   const cascadeCount = Math.max(1, Math.min(4, Math.round(lights.cascadeCount ?? 1))) as
     | 1
     | 2
@@ -165,6 +344,15 @@ function topologyOf(
     pipelineState.format as GPUTextureFormat,
     pipelineState.colorAttachmentFormat as GPUTextureFormat,
   );
+  const internal = internals.device as unknown as { readonly surfaceViewFormats?: boolean };
+  const surfaceProfile = resolveSurfaceProfile(surfaceFormats.storage, surfaceFormats.view, {
+    surfaceViewFormats:
+      internal.surfaceViewFormats ?? internals.device.caps.backendKind !== 'wgpu-webgl2',
+    rawAttachment:
+      surfaceFormats.storage === 'rgba8unorm' || surfaceFormats.storage === 'bgra8unorm',
+    floatRenderAttachment: internals.device.caps.rgba16floatRenderable,
+  });
+  if (!surfaceProfile.ok) return surfaceProfile;
   const featurePostEffects = [
     ...(featureGraphCandidate?.fullscreenEffects ??
       getRenderFeatureGraphState(internals).fullscreenEffects),
@@ -181,21 +369,42 @@ function topologyOf(
             ]),
           ],
         };
-  return {
+  const volumeCapability = hasVolumetricFogCapability(
+    internals.device.caps,
+    internals.volumetricFogShaders,
+  );
+  const selectedVolumeLight =
+    volumetricFog?.lightKind === 'spot'
+      ? lights.spot.find((light) => light.entity === volumetricFog.lightEntity)
+      : volumetricFog?.lightKind === 'point'
+        ? lights.point.find((light) => light.entity === volumetricFog.lightEntity)
+        : volumetricFog?.lightKind === 'directional' &&
+            lights.directional?.entity === volumetricFog.lightEntity
+          ? lights.directional
+          : volumetricFog?.lightKind === undefined
+            ? lights.directional
+            : undefined;
+  return ok({
     pipelineId: STANDARD_PIPELINE_ID,
     standardProfile: internals.standardProfile,
     config,
+    clearOnly,
     surface: {
       width,
       height,
       storageFormat: surfaceFormats.storage as TextureFormat,
-      viewFormat: surfaceFormats.view as TextureFormat,
+      viewFormat: surfaceProfile.value.viewFormat as TextureFormat,
+      profile: surfaceProfile.value,
     },
     camera: {
       tonemap: camera.tonemap,
       antialias: camera.antialias,
       bloom: camera.bloom,
     },
+    temporal: {
+      taa: camera.antialias === 'taa',
+      motionBlur: isMotionBlurTemporalDemand(camera.motionBlur),
+    },
     shadow: {
       mapSize: shadowMapSize ?? 1024,
       cascadeCount,
@@ -208,6 +417,47 @@ function topologyOf(
         ).length,
       ),
     },
+    volumetricFog:
+      volumetricFog?.status === 'available' &&
+      volumetricFog.densityAsset?.shape.viewDimension === '3d' &&
+      camera.tonemap !== 'none' &&
+      selectedVolumeLight !== undefined &&
+      volumeCapability
+        ? (() => {
+            const volumeProfile = resolveVolumetricFogProfile(internals.standardProfile ?? {});
+            return {
+              enabled: true,
+              format: volumetricFog.densityAsset.format,
+              extent: {
+                width: volumetricFog.densityAsset.shape.extent.width,
+                height: volumetricFog.densityAsset.shape.extent.height,
+                depth: volumetricFog.densityAsset.shape.extent.depth,
+              },
+              froxelExtent: deriveVolumetricFogExtent(
+                { width, height },
+                volumeProfile.depth,
+                volumeProfile.tileSize,
+              ),
+              resolvedExtent: deriveVolumetricFogResolvedExtent(
+                { width, height },
+                volumeProfile.tileSize,
+              ),
+              lightKind: volumetricFog.lightKind,
+              lightEntity: volumetricFog.lightEntity,
+              pointLightEntity: volumetricFog.pointLightEntity,
+              spotLightEntity: volumetricFog.spotLightEntity,
+              ...(volumetricFog.projector === undefined
+                ? {}
+                : {
+                    projector: {
+                      guid: volumetricFog.projector.guid,
+                      generation: volumetricFog.projector.generation,
+                      revision: volumetricFog.projector.revision,
+                    },
+                  }),
+            };
+          })()
+        : { enabled: false },
     lane: {
       compute: internals.device.caps.compute,
       storageBuffer: internals.device.caps.storageBuffer,
@@ -222,13 +472,44 @@ function topologyOf(
       preparedResourceKey: featureGraphCandidate?.preparedResourceKey ?? '',
     }),
     gpuDrivenTopologySignature: gpuDriven?.topologySignature ?? '',
-  };
+    transmissionDemand: transmissionDemand ?? {
+      activeCount: 0,
+      needsRoughMips: false,
+    },
+  });
 }
 
 function targetResolver(
   targets: readonly RenderPipelineFeatureTarget[],
+  semanticTargets: readonly import('../render-pipeline').RenderPipelineTarget[] = [],
+  namedTargets: Readonly<Record<string, import('../render-pipeline').RenderPipelineTarget>> = {},
 ): RenderFeatureGraphTargetResolver {
   return (resource) => {
+    const namedKey =
+      typeof resource === 'string'
+        ? resource
+        : isRenderFeatureTargetHandle(resource)
+          ? resource.name
+          : undefined;
+    if (namedKey !== undefined) {
+      const named = namedTargets[namedKey];
+      if (named !== undefined) {
+        return {
+          texture: named.texture,
+          view: named.view,
+          ...(named.resolveTarget === undefined ? {} : { resolveTarget: named.resolveTarget }),
+        };
+      }
+    }
+    if (isSceneDataTarget(resource)) {
+      const semantic = semanticTargets.find(
+        (candidate) =>
+          candidate.format === resource.format && candidate.sampleCount === resource.sampleCount,
+      );
+      return semantic === undefined
+        ? undefined
+        : { texture: semantic.texture, view: semantic.view };
+    }
     if (!isRenderFeatureTargetHandle(resource)) return undefined;
     const target = targets.find(
       (candidate) =>
@@ -262,6 +543,55 @@ function resolveTargetBindings(input: {
   const sceneDepth = descriptor?.values.sceneDepth;
   const sceneDepthBinding = descriptor?.values.sceneDepthBinding;
   if (pipeline === undefined) return undefined;
+  if (descriptor?.values.fullscreen === true && isTemporalFullscreenBinding(descriptor.values)) {
+    const shader = descriptor.values.shader;
+    if (typeof shader !== 'string') return undefined;
+    const entry = frame.runtime.lookupPostProcess?.(shader);
+    if (entry === undefined) return undefined;
+    const fullscreen = buildFullscreenPostProcessPass(
+      { device: frame.runtime.device, errorRegistry: frame.runtime.errorRegistry },
+      entry,
+      isRenderFeatureTargetHandle(descriptor.values.depth) &&
+        descriptor.values.depth.sampleCount === 4,
+    );
+    if (fullscreen === null || fullscreen.sampler === null) return undefined;
+    const inputTarget = input.resolveTarget(descriptor.values.input as never);
+    const temporalTarget = input.resolveTarget(descriptor.values.temporal as never);
+    if (inputTarget === undefined || temporalTarget === undefined) return undefined;
+    const inputView = input.resources.textureView(inputTarget.view);
+    const temporalView = input.resources.textureView(temporalTarget.view);
+    if (!inputView.ok || !temporalView.ok) return undefined;
+    const layout = pipeline.getBindGroupLayout?.(1);
+    if (layout === undefined) return undefined;
+    const depth = input.resolveTarget(descriptor.values.depth as never);
+    const depthView =
+      depth === undefined
+        ? undefined
+        : (() => {
+            const depthTexture = input.resources.texture(depth.texture);
+            if (!depthTexture.ok) return undefined;
+            const created = frame.runtime.device.createTextureView(depthTexture.value as Texture, {
+              aspect: 'depth-only',
+              dimension: '2d',
+            });
+            return created.ok ? created.value : undefined;
+          })();
+    if (depth !== undefined && (depthView === undefined || fullscreen.depthSampler === null)) {
+      return undefined;
+    }
+    return (
+      createFullscreenBindGroup(
+        frame.runtime.device,
+        layout,
+        inputView.value,
+        fullscreen.sampler,
+        frame.runtime.getPostProcessParamsBuffer?.(shader),
+        depthView ?? null,
+        fullscreen.depthSampler,
+        [{ binding: fullscreen.extraColorBindings[0] ?? 5, view: temporalView.value }],
+      ) ?? undefined
+    );
+  }
   if (sceneDepthBinding === 1) {
     const target = sceneDepth === undefined ? undefined : input.resolveTarget(sceneDepth);
     const depthView =
@@ -340,6 +670,32 @@ function retire(
     .catch(() => undefined);
 }
 
+/**
+ * Settle a volume topology candidate after the command buffer outcome is
+ * known. A graph that failed to encode, finish, or submit must never become
+ * the next frame's accepted graph: retire it and restore the prior graph (or
+ * leave the renderer without a graph when this was the first attempt).
+ */
+export function settleVolumetricFogGraphCandidate(
+  frameState: RenderFrameState,
+  submitted: boolean,
+): void {
+  const candidate = frameState.volumetricFogCandidateGraph ?? null;
+  if (candidate === null) return;
+  const previous = frameState.volumetricFogPreviousGraph ?? null;
+  const previousKey = frameState.volumetricFogPreviousGraphKey ?? null;
+  if (submitted) {
+    if (previous !== null && previous !== candidate) retire(frameState, previous);
+  } else {
+    if (candidate !== previous) retire(frameState, candidate);
+    frameState.compiledFrameGraph = previous;
+    frameState.compiledFrameGraphTopologyKey = previousKey;
+  }
+  frameState.volumetricFogPreviousGraph = null;
+  frameState.volumetricFogPreviousGraphKey = null;
+  frameState.volumetricFogCandidateGraph = null;
+}
+
 export function ensureCompiledFrameGraph(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
@@ -351,6 +707,10 @@ export function ensureCompiledFrameGraph(
   shadowMapSize: number | undefined,
   gpuDriven?: PreparedGpuDrivenFrame,
   featureGraphCandidate?: RenderFeatureGraphCandidate,
+  clearOnly = false,
+  transmissionDemand?: TransmissionDemand,
+  volumetricFog?: ExtractedVolumetricFog,
+  volumeTopologyCandidate = false,
 ): CompiledRenderGraph<RenderPipelineFrame> | null {
   const surfaceWidth = Math.max(1, width);
   const surfaceHeight = Math.max(1, height);
@@ -359,44 +719,66 @@ export function ensureCompiledFrameGraph(
   if (!projectedFeaturePlans.ok) {
     reportRenderFeatureGraphError(internals, projectedFeaturePlans.error);
     featureGraphCandidate?.onRejected?.();
-    return frameState.compiledFrameGraph;
+    return volumeTopologyCandidate ? null : frameState.compiledFrameGraph;
   }
-  const topology = topologyOf(
+  const topologyResult = topologyOf(
     internals,
     frameState,
     pipelineState,
     camera,
+    clearOnly,
     lights,
     surfaceWidth,
     surfaceHeight,
     shadowMapSize,
     gpuDriven,
     featureGraphCandidate,
+    transmissionDemand,
+    volumetricFog,
   );
+  if (!topologyResult.ok) {
+    internals.errorRegistry.fire(topologyResult.error);
+    featureGraphCandidate?.onRejected?.();
+    return volumeTopologyCandidate ? null : frameState.compiledFrameGraph;
+  }
+  const topology = topologyResult.value;
   const key = JSON.stringify(topology);
   if (frameState.compiledFrameGraph !== null && frameState.compiledFrameGraphTopologyKey === key) {
     if (featureGraphCandidate !== undefined) {
       commitFeatureCandidate(internals, featureGraphCandidate);
     }
+    // A candidate flag only describes a possible topology replacement. When
+    // the derived key is unchanged there is no replacement to stage: reuse the
+    // accepted graph so dynamic volume history/imported views can advance and
+    // a queue-submit failure can still publish the LKG diagnostic.
     return frameState.compiledFrameGraph;
   }
 
   const builder = new RenderGraphBuilder<RenderPipelineFrame>();
+  const taaHistory = camera.antialias === 'taa' ? importTemporalHistoryTargets(builder) : undefined;
   let projectedFeatures = false;
   let projectedGpuDriven = false;
   const built = frameState.activePipeline.build(
     {
       graph: builder,
+      capabilities: { rgba16floatRenderable: internals.device.caps.rgba16floatRenderable },
+      ...(taaHistory === undefined ? {} : { taaHistory }),
+      encodeTransmissionMip: ({ pass, resources, source }) => {
+        const sourceView = resources.textureView(source);
+        if (!sourceView.ok) throw sourceView.error;
+        const encoded = encodeMipmapLevel(internals.device, pass, sourceView.value, 'rgba16float');
+        if (!encoded.ok) throw encoded.error;
+      },
       projectGpuDriven: (target) => {
         if (projectedGpuDriven || gpuDriven === undefined) return ok(undefined);
         projectedGpuDriven = true;
         return gpuDriven.project(builder, target.format, target.sampleCount);
       },
-      contributeFeatures: (targets) => {
+      contributeFeatures: (targets, semanticTargets = [], namedTargets = {}) => {
         if (projectedFeatures) return ok(undefined);
         projectedFeatures = true;
         if (projectedFeaturePlans.value.length === 0) return ok(undefined);
-        const resolveTarget = targetResolver(targets);
+        const resolveTarget = targetResolver(targets, semanticTargets, namedTargets);
         const projected = projectPlanExecutions(builder, projectedFeaturePlans.value, {
           resolveTarget,
           resolveBindings: resolveTargetBindings,
@@ -404,13 +786,15 @@ export function ensureCompiledFrameGraph(
         });
         return projected.ok ? ok(undefined) : projected;
       },
+      hasFeature: (identity) =>
+        projectedFeaturePlans.value.some((execution) => execution.featureIdentity === identity),
     },
     topology,
   );
   if (!built.ok) {
     internals.errorRegistry.fire(built.error);
     featureGraphCandidate?.onRejected?.();
-    return frameState.compiledFrameGraph;
+    return volumeTopologyCandidate ? null : frameState.compiledFrameGraph;
   }
   const compiled = builder.compile({
     device: internals.device,
@@ -422,13 +806,26 @@ export function ensureCompiledFrameGraph(
     return frameState.compiledFrameGraph;
   }
   const previous = frameState.compiledFrameGraph;
+  if (volumeTopologyCandidate) {
+    frameState.volumetricFogPreviousGraph = previous;
+    frameState.volumetricFogPreviousGraphKey = frameState.compiledFrameGraphTopologyKey;
+    frameState.volumetricFogCandidateGraph = compiled.value;
+  }
   frameState.compiledFrameGraph = compiled.value;
   frameState.compiledFrameGraphTopologyKey = key;
+  const compiledTargets = compiled.value as CompiledGraphTargetAccess;
+  frameState.graphGeneration += 1;
+  frameState.perFrameGraph = {
+    getColorTargetDescriptor: (name) => compiledTargets.getColorTargetDescriptor(name),
+    getColorTargetView: (name) => compiledTargets.getColorTargetView(name),
+    getColorTargetTexture: (name) => compiledTargets.getColorTargetTexture(name),
+    graphGeneration: frameState.graphGeneration,
+  };
   gpuDriven?._commitResourceReplacement();
   if (featureGraphCandidate !== undefined) {
     commitFeatureCandidate(internals, featureGraphCandidate);
   }
-  if (previous !== null) retire(frameState, previous);
+  if (!volumeTopologyCandidate && previous !== null) retire(frameState, previous);
   return compiled.value;
 }
 
@@ -438,24 +835,301 @@ export function executeCompiledFrameGraph(
   frame: RenderPipelineFrame,
   encoder: RhiCommandEncoder,
   runPass?: import('@forgeax/engine-render-graph').RenderGraphPassRunner,
+  timingCapture?: GpuTimingCapture,
 ): boolean {
   const graph = frameState.compiledFrameGraph;
-  if (graph === null) return false;
-  const executed = graph.execute(frame, runPass);
-  if (!executed.ok) {
-    internals.errorRegistry.fire(executed.error);
-    return false;
-  }
-  const finished = encoder.finish();
-  if (!finished.ok) {
-    internals.errorRegistry.fire(finished.error);
-    return false;
-  }
-  const command: CommandBuffer = finished.value;
-  const submitted = internals.device.queue.submit([command]);
-  if (!submitted.ok) {
-    internals.errorRegistry.fire(submitted.error);
+  const rejectTemporalFrame = (): void => {
+    if (frameState.temporalFrameInput === undefined) return;
+    frameState.temporalFrameTransaction.commit({ accepted: false });
+    frameState.temporalFrameInput = undefined;
+  };
+  if (graph === null) {
+    timingCapture?.discard();
+    settleVolumetricFogGraphCandidate(frameState, false);
+    rejectTemporalFrame();
     return false;
   }
-  return true;
+  const timedRunPass =
+    timingCapture === undefined
+      ? runPass
+      : (
+          pass: import('@forgeax/engine-render-graph').RenderGraphPassExecution,
+          encode: () => void,
+        ) => {
+          timingCapture.beforePass(pass.name, encoder);
+          try {
+            if (runPass === undefined) encode();
+            else runPass(pass, encode);
+          } finally {
+            timingCapture.afterPass(pass.name, encoder);
+          }
+        };
+  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, timedRunPass);
+      if (!executed.ok) {
+        internals.errorRegistry.fire(executed.error);
+        return { ok: false, stage: 'execute' };
+      }
+      return { ok: true, value: undefined };
+    },
+    finish: () => {
+      const graphCapture = frameState.graphTargetCapture;
+      frameState.graphTargetCapture = undefined;
+      if (graphCapture !== undefined) {
+        const graphAccess = frameState.perFrameGraph;
+        const graphTexture = graphAccess?.getColorTargetTexture(graphCapture.name);
+        const descriptor = graphAccess?.getColorTargetDescriptor(graphCapture.name);
+        const frameId = frameState.frameNumber - 1;
+        const captureFailure = (message: string): void => {
+          internals.errorRegistry.fire(
+            new RhiError({
+              code: 'webgpu-runtime-error',
+              expected:
+                'the requested graph target is present in the current graph with a matching copy-readable descriptor',
+              hint: 'inspect the target name, graph generation/frame, texture identity, format, extent, and COPY_SRC usage',
+              detail: {
+                error: {
+                  code: 'graph-target-capture-failed',
+                  message,
+                },
+              },
+            }),
+          );
+        };
+        if (
+          graphAccess === undefined ||
+          graphAccess === null ||
+          graphTexture === undefined ||
+          descriptor === undefined
+        ) {
+          captureFailure(
+            JSON.stringify({
+              target: graphCapture.name,
+              graphGeneration: graphAccess?.graphGeneration,
+              frameId,
+              textureIdentity:
+                graphTexture === undefined ? undefined : getTextureIdentity(graphTexture),
+              reason: 'target-not-present-in-current-graph',
+            }),
+          );
+        } else if (
+          descriptor.size.width !== graphCapture.width ||
+          descriptor.size.height !== graphCapture.height
+        ) {
+          captureFailure(
+            JSON.stringify({
+              target: graphCapture.name,
+              graphGeneration: graphAccess.graphGeneration,
+              frameId,
+              textureIdentity: getTextureIdentity(graphTexture),
+              expectedFormat: graphCapture.expected.format,
+              actualFormat: descriptor.format,
+              expectedExtent: { width: graphCapture.width, height: graphCapture.height },
+              actualExtent: descriptor.size,
+              reason: 'extent-mismatch',
+            }),
+          );
+        } else if ((descriptor.usage & GPU_TEXTURE_USAGE_COPY_SRC) === 0) {
+          captureFailure(
+            JSON.stringify({
+              target: graphCapture.name,
+              graphGeneration: graphAccess.graphGeneration,
+              frameId,
+              textureIdentity: getTextureIdentity(graphTexture),
+              format: descriptor.format,
+              extent: descriptor.size,
+              usage: descriptor.usage,
+              reason: 'copy-src-usage-missing',
+            }),
+          );
+        } else if (
+          descriptor.format !== graphCapture.expected.format ||
+          descriptor.size.width !== graphCapture.expected.width ||
+          descriptor.size.height !== graphCapture.expected.height ||
+          (descriptor.usage & graphCapture.expected.usage) !== graphCapture.expected.usage
+        ) {
+          captureFailure(
+            JSON.stringify({
+              target: graphCapture.name,
+              graphGeneration: graphAccess.graphGeneration,
+              frameId,
+              textureIdentity: getTextureIdentity(graphTexture),
+              expected: graphCapture.expected,
+              actual: {
+                format: descriptor.format,
+                width: descriptor.size.width,
+                height: descriptor.size.height,
+                usage: descriptor.usage,
+              },
+              reason: 'descriptor-mismatch',
+            }),
+          );
+        } else if (
+          graphCapture.expected.identity !== undefined &&
+          (graphAccess.graphGeneration !== graphCapture.expected.identity.graphGeneration ||
+            graphCapture.expected.identity.frameId !== frameId ||
+            graphCapture.expected.identity.textureIdentity !== getTextureIdentity(graphTexture))
+        ) {
+          captureFailure(
+            JSON.stringify({
+              target: graphCapture.name,
+              graphGeneration: graphAccess.graphGeneration,
+              frameId,
+              textureIdentity: getTextureIdentity(graphTexture),
+              expectedIdentity: graphCapture.expected.identity,
+              reason: 'identity-mismatch',
+            }),
+          );
+        } else {
+          encoder.copyTextureToBuffer(
+            { texture: graphTexture as never },
+            {
+              buffer: graphCapture.buffer as never,
+              bytesPerRow: graphCapture.bytesPerRow,
+              rowsPerImage: graphCapture.height,
+            },
+            {
+              width: graphCapture.width,
+              height: graphCapture.height,
+              depthOrArrayLayers: 1,
+            },
+          );
+        }
+      }
+      const stagedGpuState = frameState.temporalGpuState;
+      if (stagedGpuState !== undefined && !hasPendingTemporalGpuSubmit(stagedGpuState)) {
+        internals.errorRegistry.fire(
+          new RhiError({
+            code: 'webgpu-runtime-error',
+            expected: 'TAA resolve stages a history write before submit',
+            hint: 'retry the frame after the temporal resolve pass has encoded successfully',
+          }),
+        );
+        return { ok: false, stage: 'finish' };
+      }
+      const resolved = timingCapture?.resolve(encoder);
+      if (resolved !== undefined && !resolved.ok) {
+        timingCapture?.discard();
+        return { ok: false, stage: 'finish' };
+      }
+      const finished = encoder.finish();
+      if (!finished.ok) {
+        timingCapture?.discard();
+        internals.errorRegistry.fire(finished.error);
+        return { ok: false, stage: 'finish' };
+      }
+      preparedCommand = { command: finished.value };
+      return { ok: true, value: undefined };
+    },
+    submit: () => {
+      const submitted = internals.device.queue.submit([preparedCommand.command]);
+      if (!submitted.ok) {
+        timingCapture?.discard();
+        internals.errorRegistry.fire(submitted.error);
+        return { ok: false, stage: 'submit' };
+      }
+      timingCapture?.markSubmitted();
+      return { ok: true, value: undefined };
+    },
+    commit: () => {
+      if (frameState.bloomFrameReceipts !== undefined) {
+        internals
+          .getPipelineState()
+          ?.perPassResources.commitBloomFrameReceipts?.(frameState.bloomFrameReceipts);
+        frameState.bloomFrameReceipts = undefined;
+      }
+      const stagedGpuState = frameState.temporalGpuState;
+      if (stagedGpuState !== undefined) {
+        if (commitTemporalGpuSubmit(stagedGpuState)) {
+          const previousGpuState = frameState.activeTemporalGpuState;
+          frameState.activeTemporalGpuState = stagedGpuState;
+          if (previousGpuState !== undefined && previousGpuState !== stagedGpuState) {
+            internals.clearPostProcessPipelineCache?.('forgeax.taa-resolve');
+            internals.invalidateShaderModule?.('post-process-forgeax.taa-resolve-module');
+            retireTemporalGpuStateAfterFence(
+              previousGpuState,
+              internals.device.queue,
+              frameState.retiringTemporalGpuStates,
+              (cause) => {
+                internals.errorRegistry.fire(
+                  new RhiError({
+                    code: 'webgpu-runtime-error',
+                    expected: 'submitted temporal resources remain valid until queue completion',
+                    hint: `temporal resource retirement failed: ${String(cause)}`,
+                  }),
+                );
+              },
+            );
+          }
+          frameState.temporalGpuState = undefined;
+        }
+      }
+      const stagedTemporalCommit = frameState.pendingTemporalCommit ?? { kind: 'none' as const };
+      if (stagedTemporalCommit.kind !== 'none') {
+        frameState.lastSuccessfulTemporalView = stagedTemporalCommit.view;
+      }
+      if (stagedTemporalCommit.kind === 'taa') {
+        frameState.successfulTemporalFrameIndex = stagedTemporalCommit.view.temporalFrameIndex + 1;
+      } else if (stagedTemporalCommit.kind === 'off') {
+        frameState.successfulTemporalFrameIndex = 0;
+      }
+      if (stagedTemporalCommit.kind === 'off') {
+        internals.clearPostProcessPipelineCache?.('forgeax.taa-resolve');
+        internals.invalidateShaderModule?.('post-process-forgeax.taa-resolve-module');
+        const activeGpuState = frameState.activeTemporalGpuState;
+        if (activeGpuState !== undefined) {
+          retireTemporalGpuStateAfterFence(
+            activeGpuState,
+            internals.device.queue,
+            frameState.retiringTemporalGpuStates,
+            (cause) => {
+              internals.errorRegistry.fire(
+                new RhiError({
+                  code: 'webgpu-runtime-error',
+                  expected: 'submitted temporal resources remain valid until queue completion',
+                  hint: `temporal resource retirement failed: ${String(cause)}`,
+                }),
+              );
+            },
+          );
+          frameState.activeTemporalGpuState = undefined;
+        }
+      }
+      frameState.pendingTemporalCommit = { kind: 'none' };
+      if (frameState.environmentGeneration !== undefined) {
+        frameState.environmentLifecycle?.publish(frameState.environmentGeneration);
+        frameState.environmentGeneration = undefined;
+      }
+    },
+    abort: (failure) => {
+      timingCapture?.discard();
+      frameState.bloomFrameReceipts = undefined;
+      if (frameState.environmentGeneration !== undefined) {
+        frameState.environmentLifecycle?.recordStageFailure(
+          failure.stage,
+          frameState.environmentGeneration,
+        );
+      }
+      if (frameState.temporalGpuState !== undefined) {
+        const stagedGpuState = frameState.temporalGpuState;
+        abortTemporalGpuSubmit(stagedGpuState);
+        if (stagedGpuState !== frameState.activeTemporalGpuState) {
+          retireTemporalGpuState(stagedGpuState);
+        }
+        frameState.temporalGpuState = undefined;
+      }
+      frameState.pendingTemporalCommit = { kind: 'none' };
+      if (frameState.environmentGeneration !== undefined) {
+        frameState.environmentLifecycle?.discard(frameState.environmentGeneration);
+        frameState.environmentGeneration = undefined;
+      }
+    },
+  });
+  settleVolumetricFogGraphCandidate(frameState, transaction.ok);
+  if (!transaction.ok) rejectTemporalFrame();
+  return transaction.ok;
 }