@forgeax/engine-render 0.1.31 → 0.1.32

package/src/instances.ts

@@ -502,17 +502,23 @@ export class InstanceCollectionStore {
     if (!record.ok) return record;
     const value = record.value;
     value.lastSnapshotRevision = value.revision;
-    const result = {
-      ...this.info(value),
-      transforms: new Float32Array(value.transforms),
-      dirtyRanges: value.dirtyRanges.map((range) => ({ ...range })),
-    };
+    const result = this.detachedSnapshot(value);
     // Keep the current ranges stable for repeated reads by entities sharing
     // this collection. The next authoring mutation starts a fresh interval
     // set once this revision has been observed.
     return ok(result);
   }
 
+  /**
+   * Read a detached matrix view without advancing the render-consumption
+   * cursor. Inspection and picking may call this between authoring updates;
+   * the next renderer snapshot must still receive the complete dirty union.
+   */
+  peek(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionSnapshot> {
+    const record = this.live('inspect', id);
+    return record.ok ? ok(this.detachedSnapshot(record.value)) : record;
+  }
+
   release(id: InstanceCollectionId): InstanceCollectionResult<void> {
     const record = this.records.get(id);
     if (record === undefined) return err(missing('release', id));
@@ -569,6 +575,14 @@ export class InstanceCollectionStore {
     return record === undefined ? err(missing(operation, id)) : ok(record);
   }
 
+  private detachedSnapshot(record: CollectionRecord): InstanceCollectionSnapshot {
+    return {
+      ...this.info(record),
+      transforms: new Float32Array(record.transforms),
+      dirtyRanges: record.dirtyRanges.map((range) => ({ ...range })),
+    };
+  }
+
   private info(record: CollectionRecord): InstanceCollectionInfo {
     return Object.freeze({
       collectionId: record.id,

package/src/mesh-material-bindings.ts

@@ -112,6 +112,8 @@ export interface MeshMaterialBindingResidency {
 /** Public read-only observation of the bindings used by the last frame. */
 export interface MeshMaterialBindingObservation {
   readonly worldId: number;
+  /** Stable World identity for cross-world inspection; worldId is only a frame slot. */
+  readonly worldIdentity?: string;
   readonly entityKey: number;
   readonly bindings: readonly ResolvedMeshMaterialBinding[];
   readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
@@ -143,6 +145,7 @@ const EMPTY_RESIDENCY: MeshMaterialBindingResidency = Object.freeze({
  */
 export function projectMeshMaterialBindingObservation(input: {
   readonly worldId: number;
+  readonly worldIdentity?: string;
   readonly entityKey: number;
   readonly bindings: readonly ResolvedMeshMaterialBinding[];
   readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
@@ -168,6 +171,7 @@ export function projectMeshMaterialBindingObservation(input: {
   });
   return {
     worldId: input.worldId,
+    ...(input.worldIdentity === undefined ? {} : { worldIdentity: input.worldIdentity }),
     entityKey: input.entityKey,
     bindings: Object.freeze([...input.bindings]),
     diagnostics: Object.freeze([...input.diagnostics]),

package/src/pipeline/standard-output/graph.ts

@@ -26,6 +26,7 @@ function requestedStages(input: StandardOutputRequest): StandardOutputLogicalSta
   const stages: StandardOutputLogicalStage[] = [];
   if (input.temporal) stages.push('temporal');
   if (input.meter) stages.push('meter');
+  if (input.dof === true) stages.push('dof');
   if (input.bloom) stages.push('bloom');
   if (input.exposure || input.whiteBalance) stages.push('exposure-white-balance');
   stages.push('tone');
@@ -43,6 +44,7 @@ function physicalStages(
       case 'temporal':
       case 'meter':
       case 'bloom':
+      case 'dof':
       case 'exposure-white-balance':
         return { name, input: LINEAR_HDR_DOMAIN, output: LINEAR_HDR_DOMAIN };
       case 'tone':
@@ -68,6 +70,7 @@ export function createStandardOutputPlan(input: StandardOutputRequest): Standard
       temporal: input.temporal,
       meter: input.meter,
       bloom: input.bloom,
+      dof: input.dof === true,
       exposure: input.exposure,
       whiteBalance: input.whiteBalance,
       lut: input.lut,

package/src/pipeline/standard-output/types.ts

@@ -3,6 +3,7 @@ import type { ColorValueDomain } from '@forgeax/engine-render-graph';
 export const STANDARD_OUTPUT_LOGICAL_STAGES = [
   'temporal',
   'meter',
+  'dof',
   'bloom',
   'exposure-white-balance',
   'tone',
@@ -26,6 +27,8 @@ export interface StandardOutputRequest {
   readonly temporal: boolean;
   readonly meter: boolean;
   readonly bloom: boolean;
+  /** Built-in spatial DoF stage; false keeps the path exact-zero. */
+  readonly dof?: boolean;
   readonly exposure: boolean;
   readonly whiteBalance: boolean;
   readonly lut: boolean;
@@ -44,7 +47,7 @@ export interface StandardOutputPlan {
   readonly features: Readonly<
     Pick<
       StandardOutputRequest,
-      'temporal' | 'meter' | 'bloom' | 'exposure' | 'whiteBalance' | 'lut' | 'fxaa'
+      'temporal' | 'meter' | 'bloom' | 'dof' | 'exposure' | 'whiteBalance' | 'lut' | 'fxaa'
     >
   >;
   readonly outputEncoding: StandardOutputEncoding;

package/src/pipeline/standard-post.ts

@@ -7,6 +7,7 @@ import { RenderGraphError } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { addTypedDebugOverlayPass } from '../debug-draw-glue';
 import { SceneDataUnavailableError } from '../errors/render';
+import { addDepthOfFieldPasses } from '../features/depth-of-field/depth-of-field-feature';
 import { addMotionBlurPass } from '../features/motion-blur/motion-blur-feature';
 import { GPU_TEXTURE_USAGE_COPY_SRC } from '../gpu-texture-usage';
 import type {
@@ -179,6 +180,7 @@ export function addStandardPost(
     temporal: !clearOnly && topology.camera.antialias === 'taa',
     meter: topology.output?.autoExposure === true,
     bloom: !clearOnly && topology.camera.bloom === 'on' && topology.camera.tonemap !== 'none',
+    dof: !clearOnly && topology.camera.depthOfField !== undefined,
     exposure: topology.output?.autoExposure === true,
     whiteBalance: topology.output?.whiteBalance === true,
     lut: topology.output?.colorLut === true,
@@ -313,8 +315,8 @@ export function addStandardPost(
     }
   }
 
-  // Meter the temporally resolved color before Bloom. This preserves the
-  // Standard order: temporal -> meter -> bloom -> exposure/WB -> tone -> LUT.
+  // Meter the temporally resolved color before DoF/Bloom. This preserves the
+  // Standard order: temporal -> motion -> meter -> DoF -> bloom -> output.
   if (outputPlan.features.exposure && autoExposure !== undefined) {
     const added = addAutoExposureGraphPasses(context, {
       source: postInput,
@@ -325,6 +327,23 @@ export function addStandardPost(
     if (!added.ok) return added;
   }
 
+  if (outputPlan.features.dof) {
+    const dof = addDepthOfFieldPasses(
+      {
+        graph: context.graph,
+        camera: context.camera ?? {},
+        temporalTaa: topology.temporal?.taa === true,
+        msaaActive: depth.sampleCount === 4,
+        ...(topology.extent === undefined ? {} : { extent: topology.extent }),
+      },
+      postInput,
+      depth,
+      topology.temporal?.taa === true ? postTemporal : undefined,
+    );
+    if (!dof.ok) return dof;
+    postInput = dof.value;
+  }
+
   if (bloomActive) {
     const composited = target(
       context,

package/src/plugin.ts

@@ -2,6 +2,7 @@ import type { Component, World } from '@forgeax/engine-ecs';
 import type { Plugin } from '@forgeax/engine-plugin';
 import { Atmosphere } from './components/atmosphere';
 import { Camera } from './components/camera';
+import { DepthOfField } from './components/depth-of-field';
 import { DirectionalLight } from './components/directional-light';
 import { DynamicResolution } from './components/dynamic-resolution';
 import { Instances } from './components/instances';
@@ -33,6 +34,7 @@ const RENDER_COMPONENTS: readonly Component[] = [
   Camera,
   DirectionalLight,
   DynamicResolution,
+  DepthOfField,
   Instances,
   Layer,
   LightProbe,

package/src/record/frame-snapshot.ts

@@ -4,7 +4,10 @@
 import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadVersion } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
-import type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';
+import type {
+  CompiledRenderGraphInfo,
+  ResolvedColorTargetDescriptor,
+} from '@forgeax/engine-render-graph';
 import type {
   BindGroup,
   BindGroupLayout,
@@ -17,6 +20,7 @@ import type { ClusterBinScratch } from '../cluster-binner';
 import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
 import type { EnvironmentGeneration } from '../environment/generation';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
+import type { DepthOfFieldParams } from '../features/depth-of-field/depth-of-field-params';
 import type { GpuBuffer } from '../gpu-resource';
 import type { InstanceCollectionStore } from '../instances';
 import type { IblBindingInspection } from '../mesh-material-bindings';
@@ -452,6 +456,27 @@ export interface RenderFrameState {
   compiledFrameGraphTopologyKey: string | null;
   /** Monotonic generation of successfully promoted compiled graphs. */
   compiledFrameGraphGeneration: number;
+  /**
+   * DoF graph candidate staged until the surrounding frame transaction
+   * submits. The previous graph, access projection, generation, and lighting
+   * signature are restored together when encoding or submission aborts.
+   */
+  depthOfFieldPreviousGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
+  depthOfFieldPreviousGraphKey: string | null;
+  depthOfFieldPreviousPerFrameGraph?: RenderFrameState['perFrameGraph'];
+  depthOfFieldPreviousGraphGeneration: number;
+  depthOfFieldPreviousStandardLightingGraphSignature: string;
+  depthOfFieldCandidateGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
+  /** DoF graph/params detached at the same successful-submit boundary. */
+  depthOfFieldAccepted?:
+    | {
+        readonly params: DepthOfFieldParams;
+        readonly graph: CompiledRenderGraphInfo;
+        readonly deviceGeneration: number;
+      }
+    | undefined;
+  /** A DoF candidate was present when the frame failed to submit. */
+  depthOfFieldLastSubmitFailed?: boolean | undefined;
   /**
    * Last-known-good graph held while a volume topology candidate is tested.
    * The candidate is promoted only after its command buffer is submitted;

package/src/record/frame.ts

@@ -34,6 +34,14 @@ import {
   RendererOperationError,
 } from '../errors/render';
 import { gpuDrivenDrawKey, gpuDrivenSourceDrawItemIndex } from '../extract/gpu-driven';
+import {
+  DEPTH_OF_FIELD_MSAA_POST_PROCESS_IDS,
+  DEPTH_OF_FIELD_POST_PROCESS_IDS,
+} from '../features/depth-of-field/depth-of-field-feature';
+import {
+  packDepthOfFieldParams,
+  resolveDepthOfFieldFrameParams,
+} from '../features/depth-of-field/depth-of-field-params';
 import type { GpuDrivenProduction, PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
 import type { ShadowViewIdentity } from '../gpu-driven/shadow-views';
 import { GpuBuffer } from '../gpu-resource';
@@ -323,6 +331,7 @@ import {
   executeCompiledFrameGraph,
   getRenderFeatureGraphState,
   type RenderFeatureGraphCandidate,
+  settleDepthOfFieldGraphCandidate,
   settleVolumetricFogGraphCandidate,
 } from './typed-frame-graph';
 import {
@@ -1671,8 +1680,17 @@ export function recordFrame(
         }),
       );
     }
-    const camera = activeCameras[0];
-    if (!camera) return false;
+    const requestedCamera = activeCameras[0];
+    if (!requestedCamera) return false;
+    const frameDepthOfField = resolveDepthOfFieldFrameParams(
+      requestedCamera.depthOfField,
+      requestedCamera.depthOfFieldError,
+      frameState.depthOfFieldAccepted?.params,
+    );
+    const camera: CameraSnapshot =
+      frameDepthOfField === undefined || frameDepthOfField === requestedCamera.depthOfField
+        ? requestedCamera
+        : { ...requestedCamera, depthOfField: frameDepthOfField };
     frameState.ssrRequested = camera.screenSpaceReflection !== undefined;
     const pipelineState = internals.getPipelineState();
     if (pipelineState === null) return false;
@@ -2643,6 +2661,20 @@ export function recordFrame(
       motionBlurView.setUint32(12, temporalView?.historyValid === true ? 0 : 1, true);
       framePostProcessParams.set('forgeax.motion-blur', motionBlurParams);
     }
+    if (camera.depthOfField !== undefined) {
+      const dofParams = packDepthOfFieldParams(camera.depthOfField, {
+        outputHeight: targetH,
+        near: camera.near,
+        far: camera.far,
+        useTemporalDepth: camera.antialias === 'taa' && temporalView !== undefined,
+      });
+      for (const id of [
+        ...DEPTH_OF_FIELD_POST_PROCESS_IDS,
+        ...DEPTH_OF_FIELD_MSAA_POST_PROCESS_IDS,
+      ]) {
+        framePostProcessParams.set(id, dofParams);
+      }
+    }
 
     const passCtx: _InternalRenderPipelineContext = {
       assets: internals.assets,
@@ -2925,11 +2957,12 @@ export function recordFrame(
       frameState.ssrHistoryOwner?.abortFrame(frameState.ssrHistoryCandidate, 'submit');
       frameState.ssrHistoryCandidate = undefined;
     }
-    // Volume topology replacements are provisional until the queue submission
-    // succeeds. This runs for every early-return path as well, so a swapchain,
-    // encoder, or graph failure cannot leave a non-submitted candidate as the
-    // next frame's accepted graph.
+    // DoF and volume topology replacements are provisional until the queue
+    // submission succeeds. This runs for every early-return path as well, so a
+    // swapchain, encoder, or graph failure cannot leave a non-submitted
+    // candidate as the next frame's accepted graph.
     settleVolumetricFogGraphCandidate(frameState, submitted);
+    settleDepthOfFieldGraphCandidate(frameState, submitted);
     if (volumeInspectionReady && (submitted || volumeSubmissionAttempted)) {
       updateVolumetricFogInspection(
         frameState,

package/src/record/main-pass.ts

@@ -676,11 +676,7 @@ export function recordMainPass(
           hint: 'publish the current frame view/light/shadow bind group before GPU raster',
         });
       }
-      if (
-        gpuDrivenStandardPbrFrameResources === undefined ||
-        gpuDrivenStandardPbrFrameResources.materialBindGroups.length === 0 ||
-        gpuDrivenStandardPbrFrameResources.materialBindGroups.some((group) => group === undefined)
-      ) {
+      if (gpuDrivenStandardPbrFrameResources === undefined) {
         throw new RhiError({
           code: 'rhi-not-available',
           expected: 'complete main-pass Standard PBR material bind-group receipt',

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

@@ -23,6 +23,8 @@ 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 { depthOfFieldTopology } from '../features/depth-of-field/depth-of-field-feature';
+import { resolveDepthOfFieldFrameParams } from '../features/depth-of-field/depth-of-field-params';
 import {
   getRenderFeaturePlanExecutionProjection,
   hasSubmissionSensitiveFeatures,
@@ -1419,6 +1421,7 @@ function topologyOf(
             : undefined;
   const preparedLut =
     frameState.pendingStandardLutGpuResources ?? frameState.standardLutGpuResources;
+  const depthOfField = depthOfFieldTopology(camera.depthOfField);
   return ok({
     pipelineId: STANDARD_PIPELINE_ID,
     standardProfile: internals.standardProfile,
@@ -1438,6 +1441,7 @@ function topologyOf(
       tonemap: camera.tonemap,
       antialias: camera.antialias,
       bloom: camera.bloom,
+      ...(depthOfField === undefined ? {} : { depthOfField }),
     },
     atmosphere: !clearOnly && frameState.environmentFrame?.source.kind === 'atmosphere',
     output: {
@@ -1754,18 +1758,66 @@ export function settleVolumetricFogGraphCandidate(
   if (candidate === null) return;
   const previous = frameState.volumetricFogPreviousGraph ?? null;
   const previousKey = frameState.volumetricFogPreviousGraphKey ?? null;
+  // A frame can replace both the volume and DoF topology at once. DoF owns
+  // the shared compiled graph's full projection (per-frame resolver,
+  // generation, and lighting signature), so let it settle the graph exactly
+  // once while volume clears only its own candidate marker.
+  const sharedWithDepthOfField = frameState.depthOfFieldCandidateGraph === candidate;
   if (submitted) {
-    if (previous !== null && previous !== candidate) retire(frameState, previous);
+    if (!sharedWithDepthOfField && previous !== null && previous !== candidate) {
+      retire(frameState, previous);
+    }
   } else {
-    if (candidate !== previous) retire(frameState, candidate);
-    frameState.compiledFrameGraph = previous;
-    frameState.compiledFrameGraphTopologyKey = previousKey;
+    if (!sharedWithDepthOfField) {
+      if (candidate !== previous) retire(frameState, candidate);
+      frameState.compiledFrameGraph = previous;
+      frameState.compiledFrameGraphTopologyKey = previousKey;
+    }
   }
   frameState.volumetricFogPreviousGraph = null;
   frameState.volumetricFogPreviousGraphKey = null;
   frameState.volumetricFogCandidateGraph = null;
 }
 
+/**
+ * Settle a DoF graph replacement at the same submit barrier as the frame.
+ * Graph compilation publishes a candidate for the current record pass, but a
+ * failed encode/finish/submit must restore every graph-owned LKG projection
+ * before the next frame can inspect or reuse it.
+ */
+export function settleDepthOfFieldGraphCandidate(
+  frameState: RenderFrameState,
+  submitted: boolean,
+): void {
+  const candidate = frameState.depthOfFieldCandidateGraph;
+  if (candidate === null || candidate === undefined) return;
+  // Sparse synthetic frame states used by graph tests predate the explicit
+  // transaction fields. Treat omitted pending values as the empty LKG rather
+  // than passing undefined into retirement or restoring an invalid key.
+  const previous = frameState.depthOfFieldPreviousGraph ?? null;
+  if (submitted) {
+    if (previous !== null && previous !== candidate) retire(frameState, previous);
+  } else {
+    if (candidate !== previous) retire(frameState, candidate);
+    frameState.compiledFrameGraph = previous;
+    frameState.compiledFrameGraphTopologyKey = frameState.depthOfFieldPreviousGraphKey ?? null;
+    if (frameState.depthOfFieldPreviousPerFrameGraph === undefined) {
+      delete frameState.perFrameGraph;
+    } else {
+      frameState.perFrameGraph = frameState.depthOfFieldPreviousPerFrameGraph;
+    }
+    frameState.graphGeneration = frameState.depthOfFieldPreviousGraphGeneration ?? 0;
+    frameState.standardLightingGraphSignature =
+      frameState.depthOfFieldPreviousStandardLightingGraphSignature ?? '';
+  }
+  frameState.depthOfFieldPreviousGraph = null;
+  frameState.depthOfFieldPreviousGraphKey = null;
+  frameState.depthOfFieldPreviousPerFrameGraph = undefined;
+  frameState.depthOfFieldPreviousGraphGeneration = 0;
+  frameState.depthOfFieldPreviousStandardLightingGraphSignature = '';
+  frameState.depthOfFieldCandidateGraph = null;
+}
+
 export function ensureCompiledFrameGraph(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
@@ -1791,6 +1843,18 @@ export function ensureCompiledFrameGraph(
   const featureMetrics = mutableFeatureGraphInspection(internals);
   featureMetrics.ensureCalls += 1;
   const requestedStandardLightingSignature = standardLightingTopologySignature(standardLighting);
+  const frameDepthOfField = resolveDepthOfFieldFrameParams(
+    camera.depthOfField,
+    camera.depthOfFieldError,
+    frameState.depthOfFieldAccepted?.params,
+  );
+  // A rejected authoring request remains visible on the source camera, while
+  // an accepted graph continues to receive its own params until a valid
+  // replacement or explicit component removal is submitted.
+  const graphCamera: CameraSnapshot =
+    frameDepthOfField === undefined || frameDepthOfField === camera.depthOfField
+      ? camera
+      : { ...camera, depthOfField: frameDepthOfField };
   const lastKnownGood = (): CompiledRenderGraph<RenderPipelineFrame> | null =>
     frameState.compiledFrameGraph !== null &&
     !hasSubmissionSensitiveFeatures(getRenderFeatureGraphState(internals).plans) &&
@@ -1825,7 +1889,7 @@ export function ensureCompiledFrameGraph(
     internals,
     frameState,
     pipelineState,
-    camera,
+    graphCamera,
     clearOnly,
     lights,
     surfaceWidth,
@@ -2032,6 +2096,7 @@ export function ensureCompiledFrameGraph(
   const built = frameState.activePipeline.build(
     {
       graph: builder,
+      camera: { depthOfField: graphCamera.depthOfField },
       observationCaptureDomains: internals.observationCaptureDomains,
       ...(autoExposureResources?.ok === true
         ? { standardOutput: { autoExposure: autoExposureResources.value } }
@@ -2172,10 +2237,32 @@ export function ensureCompiledFrameGraph(
     return lastKnownGood();
   }
   const previous = frameState.compiledFrameGraph;
+  const depthOfFieldReplacement =
+    (frameState.depthOfFieldCandidateGraph === null ||
+      frameState.depthOfFieldCandidateGraph === undefined) &&
+    (topologyResult.value.camera.depthOfField !== undefined ||
+      frameState.depthOfFieldAccepted !== undefined);
   if (volumeTopologyCandidate) {
     frameState.volumetricFogPreviousGraph = previous;
     frameState.volumetricFogPreviousGraphKey = frameState.compiledFrameGraphTopologyKey;
     frameState.volumetricFogCandidateGraph = compiled.value;
+    if (depthOfFieldReplacement) {
+      frameState.depthOfFieldPreviousGraph = previous;
+      frameState.depthOfFieldPreviousGraphKey = frameState.compiledFrameGraphTopologyKey;
+      frameState.depthOfFieldPreviousPerFrameGraph = frameState.perFrameGraph;
+      frameState.depthOfFieldPreviousGraphGeneration = frameState.graphGeneration;
+      frameState.depthOfFieldPreviousStandardLightingGraphSignature =
+        frameState.standardLightingGraphSignature;
+      frameState.depthOfFieldCandidateGraph = compiled.value;
+    }
+  } else if (depthOfFieldReplacement) {
+    frameState.depthOfFieldPreviousGraph = previous;
+    frameState.depthOfFieldPreviousGraphKey = frameState.compiledFrameGraphTopologyKey;
+    frameState.depthOfFieldPreviousPerFrameGraph = frameState.perFrameGraph;
+    frameState.depthOfFieldPreviousGraphGeneration = frameState.graphGeneration;
+    frameState.depthOfFieldPreviousStandardLightingGraphSignature =
+      frameState.standardLightingGraphSignature;
+    frameState.depthOfFieldCandidateGraph = compiled.value;
   }
   frameState.compiledFrameGraph = compiled.value;
   frameState.compiledFrameGraphTopologyKey = key;
@@ -2209,7 +2296,9 @@ export function ensureCompiledFrameGraph(
   } else if (featureGraphCandidate !== undefined) {
     recordRenderFeatureCandidateEvent(internals, featureGraphCandidate, 'abandoned');
   }
-  if (!volumeTopologyCandidate && previous !== null) retire(frameState, previous);
+  if (!volumeTopologyCandidate && !depthOfFieldReplacement && previous !== null) {
+    retire(frameState, previous);
+  }
   return compiled.value;
 }
 
@@ -2245,6 +2334,7 @@ export function executeCompiledFrameGraph(
     frameState.pendingAutoExposureState = undefined;
     frameState.pendingStandardLutState = undefined;
     settleVolumetricFogGraphCandidate(frameState, false);
+    settleDepthOfFieldGraphCandidate(frameState, false);
     rejectTemporalFrame();
     return false;
   }
@@ -2308,6 +2398,8 @@ export function executeCompiledFrameGraph(
         },
       }),
     );
+    settleVolumetricFogGraphCandidate(frameState, false);
+    settleDepthOfFieldGraphCandidate(frameState, false);
     return false;
   }
   const capturedGeneration = deviceScope?.generation;
@@ -3000,6 +3092,8 @@ export function executeCompiledFrameGraph(
       frameState.pendingAtmospherePublish?.();
       frameState.pendingAtmospherePublish = undefined;
       onSubmitted?.(internals.device.queue.onSubmittedWorkDone());
+      settleVolumetricFogGraphCandidate(frameState, true);
+      settleDepthOfFieldGraphCandidate(frameState, true);
     },
     abort: (failure) => {
       frameState.pendingAtmospherePublish = undefined;
@@ -3038,9 +3132,15 @@ export function executeCompiledFrameGraph(
         frameState.environmentLifecycle?.discard(frameState.environmentGeneration);
         frameState.environmentGeneration = undefined;
       }
+      settleVolumetricFogGraphCandidate(frameState, false);
+      settleDepthOfFieldGraphCandidate(frameState, false);
     },
   });
+  // The callbacks above settle the normal transaction path. Keep this guard
+  // for synthetic callers and any future early transaction result that does
+  // not enter a callback.
   settleVolumetricFogGraphCandidate(frameState, transaction.ok);
+  settleDepthOfFieldGraphCandidate(frameState, transaction.ok);
   if (!transaction.ok) rejectTemporalFrame();
   return transaction.ok;
 }

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

@@ -232,6 +232,12 @@ export function createRenderSystemRecovery(
       directionalShadowCacheRecorded: false,
       compiledFrameGraph: null,
       compiledFrameGraphTopologyKey: null,
+      depthOfFieldPreviousGraph: null,
+      depthOfFieldPreviousGraphKey: null,
+      depthOfFieldPreviousPerFrameGraph: undefined,
+      depthOfFieldPreviousGraphGeneration: 0,
+      depthOfFieldPreviousStandardLightingGraphSignature: '',
+      depthOfFieldCandidateGraph: null,
       volumetricFogPreviousGraph: null,
       volumetricFogPreviousGraphKey: null,
       volumetricFogCandidateGraph: null,

package/src/render-contract.ts

@@ -31,10 +31,15 @@ import type { EnvironmentInspection } from './environment/inspection.js';
 import type { GpuDrivenPreparationError } from './errors/gpu-driven.js';
 import type { RecoveryOutcome, RecoveryPhase } from './errors/recover.js';
 import type { RenderError } from './errors/render.js';
+import type {
+  DepthOfFieldParams,
+  DepthOfFieldRequestFailure,
+} from './features/depth-of-field/depth-of-field-params.js';
 import type { RenderFeature, RenderFeatureDiagnostics } from './features/types.js';
 import type { PostProcessShaderEntry } from './fullscreen-post-process-pass.js';
 import type {
   BloomInspection,
+  DepthOfFieldInspection,
   DirectionalShadowInspection,
   LightInspection,
   LodOcclusionInspection,
@@ -171,6 +176,10 @@ export interface CameraSnapshot {
   readonly screenSpaceReflection?: ScreenSpaceReflectionData;
   /** Renderer-owned temporal projection used by Standard's TAA producer. */
   readonly temporal?: TemporalView;
+  /** Active-camera depth-of-field parameters, present only when demanded. */
+  readonly depthOfField?: DepthOfFieldParams;
+  /** Structured DoF validation facts; invalid requests remain inspectable. */
+  readonly depthOfFieldError?: DepthOfFieldRequestFailure;
   /** Active-camera motion blur parameters, present only when demanded. */
   readonly motionBlur?: {
     readonly shutterAngle: number;
@@ -776,6 +785,8 @@ export interface RenderInspection {
   readonly temporalTarget?: TemporalTargetInspection;
   /** Renderer-owned Motion Blur facts; absent when no component is active. */
   readonly motionBlur?: MotionBlurInspection;
+  /** Renderer-owned Depth of Field facts; absent when no component is active. */
+  readonly depthOfField?: DepthOfFieldInspection;
   /** Bounded renderer-owned LOD/occlusion facts; absent before a candidate frame. */
   readonly lodOcclusion?: LodOcclusionInspection;
 }

package/src/render-graph-primitives.ts

@@ -577,6 +577,7 @@ function dispatchFullscreenPass(
   graphDepthView?: TextureView,
   paramsOverride?: Uint8Array,
   fragmentEntryPoint?: string,
+  msaaActive = false,
 ): void {
   if (shader === 'fxaa') {
     if (resolveCtx === undefined) {
@@ -643,7 +644,7 @@ function dispatchFullscreenPass(
   const built = buildFullscreenPostProcessPass(
     { device: ctx.runtime.device, errorRegistry: ctx.runtime.errorRegistry },
     entry,
-    ctx.msaaActive,
+    msaaActive,
   );
   if (built === null) return;
 
@@ -842,6 +843,8 @@ export function encodeFullscreenPass(
     readonly depthView?: TextureView | undefined;
     readonly paramsOverride?: Uint8Array | undefined;
     readonly fragmentEntryPoint?: string | undefined;
+    /** The depth target's actual sample count, when this typed pass reads depth. */
+    readonly msaaActive?: boolean | undefined;
   },
 ): void {
   dispatchFullscreenPass(
@@ -858,5 +861,9 @@ export function encodeFullscreenPass(
     input.depthView,
     input.paramsOverride,
     input.fragmentEntryPoint,
+    // Legacy callers rely on the frame context's MSAA state. Typed callers
+    // pass the actual depth target sample count explicitly so a single-sample
+    // view can never select the multisampled shader by camera policy alone.
+    input.msaaActive ?? ctx.msaaActive,
   );
 }

package/src/render-pipeline.ts

@@ -37,6 +37,7 @@ import type {
 } from '@forgeax/engine-rhi';
 import { ok, type Result } from '@forgeax/engine-types';
 import type { Tonemap } from './components/camera';
+import type { DepthOfFieldSide } from './components/depth-of-field';
 import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type { RenderError } from './errors/render';
 import type { RenderFeatureTargetKind } from './features/targets';
@@ -234,7 +235,16 @@ export interface RenderPipelineTopology {
   };
   /** Renderer-owned immutable dimensions for Standard graph consumers. */
   readonly extent?: RenderExtent;
-  readonly camera: Pick<RenderPipelineContext['camera'], 'tonemap' | 'antialias' | 'bloom'>;
+  readonly camera: Pick<RenderPipelineContext['camera'], 'tonemap' | 'antialias' | 'bloom'> & {
+    /** Shape-only DoF admission; optical values remain per-frame UBO data. */
+    readonly depthOfField?:
+      | {
+          readonly blurSide: DepthOfFieldSide;
+          readonly useNear: boolean;
+          readonly useFar: boolean;
+        }
+      | undefined;
+  };
   /** Frame-stable Standard output policy; no raw RHI handles enter topology. */
   readonly output?: {
     readonly autoExposure: boolean;
@@ -475,6 +485,12 @@ export interface GpuDrivenStandardPbrFrameResources {
 
 export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame> {
   readonly graph: RenderGraphBuilder<FrameCtx>;
+  /** Per-frame camera values consumed by optical fullscreen features. */
+  readonly camera?: {
+    readonly depthOfField?:
+      | import('./features/depth-of-field/depth-of-field-params').DepthOfFieldParams
+      | undefined;
+  };
   /** Optional Standard-only output-domain coverage producer input. */
   readonly targetCoverage?: import('./temporal/target-coverage-attachment').TargetCoverageAttachment;
   /** Explicit receipt-bound color domains requested for this frame. */