@forgeax/engine-render 0.1.31 → 0.1.33

package/src/pipeline/standard-post.ts

@@ -5,8 +5,10 @@ import type {
 } from '@forgeax/engine-render-graph';
 import { RenderGraphError } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import { standardBloomAdmitted } from '../bloom-admission';
 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 {
@@ -29,6 +31,7 @@ import {
   TYPED_BLOOM_PASS_NAMES,
   type TypedTemporalResolveTargets,
 } from '../typed-render-graph-primitives';
+import { renderExtentSize } from './render-extent';
 import {
   addAutoExposureExposurePass,
   addAutoExposureGraphPasses,
@@ -41,22 +44,81 @@ interface StandardPostSurface {
   readonly storage: RenderPipelineTarget;
 }
 
+export const STANDARD_BLOOM_MAX_LEVELS = 5;
+
 /** One authored Bloom contract drives declaration and compiled-graph validation. */
 export const STANDARD_BLOOM_TARGET_SPEC = {
-  composited: { label: 'bloom-composited', format: 'rgba16float', size: 'surface' },
-  bright: { label: 'bloom-bright', format: 'rgba16float', size: 'half-surface' },
-  blurH: { label: 'bloom-blur-h', format: 'rgba16float', size: 'half-surface' },
-  blurV: { label: 'bloom-blur-v', format: 'rgba16float', size: 'half-surface' },
-} as const satisfies Record<
-  'composited' | 'bright' | 'blurH' | 'blurV',
-  Pick<GraphTextureDescriptor, 'format' | 'size'> & { readonly label: string }
->;
+  composited: { label: 'bloom-composited', format: 'rgba16float' },
+  downsamplePrefix: 'bloom-downsample-',
+  upsamplePrefix: 'bloom-upsample-',
+} as const;
+
+export interface StandardBloomLevelDimensions {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Derive the bounded ceil-halving output pyramid, including D0. */
+export function deriveStandardBloomLevels(
+  outputWidth: number,
+  outputHeight: number,
+): readonly StandardBloomLevelDimensions[] {
+  const levels: StandardBloomLevelDimensions[] = [];
+  let width = Math.max(1, Math.ceil(outputWidth / 2));
+  let height = Math.max(1, Math.ceil(outputHeight / 2));
+  for (let level = 0; level < STANDARD_BLOOM_MAX_LEVELS; level += 1) {
+    levels.push({ width, height });
+    if (width === 1 && height === 1) break;
+    width = Math.max(1, Math.ceil(width / 2));
+    height = Math.max(1, Math.ceil(height / 2));
+  }
+  return levels;
+}
+
+export interface StandardBloomTargetSpecs {
+  readonly composited: GraphTextureDescriptor & { readonly label: string };
+  readonly downsample: readonly (GraphTextureDescriptor & { readonly label: string })[];
+  readonly upsample: readonly (GraphTextureDescriptor & { readonly label: string })[];
+  readonly levels: readonly StandardBloomLevelDimensions[];
+}
+
+function standardBloomTargetSpecs(
+  outputWidth: number,
+  outputHeight: number,
+): StandardBloomTargetSpecs {
+  const levels = deriveStandardBloomLevels(outputWidth, outputHeight);
+  return {
+    composited: {
+      label: STANDARD_BLOOM_TARGET_SPEC.composited.label,
+      format: STANDARD_BLOOM_TARGET_SPEC.composited.format,
+      size: { width: outputWidth, height: outputHeight },
+      domain: 'linear-hdr',
+    },
+    downsample: levels.map((size, level) => ({
+      label: `${STANDARD_BLOOM_TARGET_SPEC.downsamplePrefix}${level}`,
+      format: 'rgba16float' as const,
+      size,
+      domain: 'linear-hdr' as const,
+    })),
+    upsample: levels.slice(0, -1).map((size, level) => ({
+      label: `${STANDARD_BLOOM_TARGET_SPEC.upsamplePrefix}${level}`,
+      format: 'rgba16float' as const,
+      size,
+      domain: 'linear-hdr' as const,
+    })),
+    levels,
+  };
+}
 
 export interface StandardBloomGraphInspection {
   readonly status: 'empty' | 'valid' | 'invalid';
   readonly targetCount: number;
   readonly targetBytes: number;
   readonly passCount: number;
+  readonly levelCount: number;
+  readonly levelDimensions: readonly StandardBloomLevelDimensions[];
+  readonly downsamplePassCount: number;
+  readonly upsamplePassCount: number;
 }
 
 const emptyBloomGraphInspection = (): StandardBloomGraphInspection => ({
@@ -64,6 +126,10 @@ const emptyBloomGraphInspection = (): StandardBloomGraphInspection => ({
   targetCount: 0,
   targetBytes: 0,
   passCount: 0,
+  levelCount: 0,
+  levelDimensions: [],
+  downsamplePassCount: 0,
+  upsamplePassCount: 0,
 });
 
 const invalidBloomGraphInspection = (): StandardBloomGraphInspection => ({
@@ -71,21 +137,23 @@ const invalidBloomGraphInspection = (): StandardBloomGraphInspection => ({
   targetCount: 0,
   targetBytes: 0,
   passCount: 0,
+  levelCount: 0,
+  levelDimensions: [],
+  downsamplePassCount: 0,
+  upsamplePassCount: 0,
 });
 
-function textureBytes(
-  resource: CompiledRenderGraphInfo['resources'][number],
-  expected: (typeof STANDARD_BLOOM_TARGET_SPEC)[keyof typeof STANDARD_BLOOM_TARGET_SPEC],
-): number {
+type CompiledBloomResource = CompiledRenderGraphInfo['resources'][number];
+
+function textureBytes(resource: CompiledBloomResource): number | undefined {
   const descriptor = resource.descriptor;
   if (
+    resource.kind !== 'texture' ||
     descriptor === undefined ||
     descriptor.kind !== 'texture' ||
-    descriptor.format !== expected.format ||
-    !('size' in descriptor) ||
-    descriptor.size !== expected.size
+    descriptor.format !== 'rgba16float'
   )
-    return 0;
+    return undefined;
   const texelBytes = 8;
   let bytes = 0;
   for (let level = 0; level < descriptor.mipLevelCount; level += 1) {
@@ -95,7 +163,56 @@ function textureBytes(
       descriptor.depthOrArrayLayers *
       texelBytes;
   }
-  return bytes * descriptor.sampleCount;
+  const descriptorBytes = bytes * descriptor.sampleCount;
+  return resource.byteSize === descriptorBytes && descriptorBytes > 0 ? descriptorBytes : undefined;
+}
+
+function resourceSize(
+  resource: CompiledBloomResource,
+): { readonly width: number; readonly height: number } | undefined {
+  const descriptor = resource.descriptor;
+  if (resource.kind !== 'texture' || descriptor.kind !== 'texture') return undefined;
+  if (typeof descriptor.size === 'string') return undefined;
+  if (
+    resource.extent === undefined ||
+    resource.extent.width !== descriptor.width ||
+    resource.extent.height !== descriptor.height ||
+    resource.extent.depthOrArrayLayers !== descriptor.depthOrArrayLayers
+  ) {
+    return undefined;
+  }
+  if (
+    descriptor.format !== 'rgba16float' ||
+    descriptor.domain !== 'linear-hdr' ||
+    descriptor.width <= 0 ||
+    descriptor.height <= 0 ||
+    descriptor.depthOrArrayLayers !== 1 ||
+    descriptor.mipLevelCount !== 1 ||
+    descriptor.sampleCount !== 1 ||
+    resource.dimension !== '2d' ||
+    descriptor.size.width !== descriptor.width ||
+    descriptor.size.height !== descriptor.height ||
+    textureBytes(resource) === undefined
+  ) {
+    return undefined;
+  }
+  return { width: descriptor.width, height: descriptor.height };
+}
+
+function hasPassAccesses(
+  pass: CompiledRenderGraphInfo['passes'][number] | undefined,
+  accesses: readonly { readonly resource: string; readonly usage: string }[],
+): boolean {
+  return (
+    pass !== undefined &&
+    pass.kind === 'raster' &&
+    pass.accesses.length === accesses.length &&
+    accesses.every(
+      (access, index) =>
+        pass.accesses[index]?.resource === access.resource &&
+        pass.accesses[index]?.usage === access.usage,
+    )
+  );
 }
 
 /** Derive Bloom target/pass facts solely from the compiled Standard graph. */
@@ -103,33 +220,125 @@ export function inspectStandardBloomGraph(
   graph: CompiledRenderGraphInfo | undefined,
 ): StandardBloomGraphInspection {
   if (graph === undefined) return emptyBloomGraphInspection();
-  type BloomTargetSpec =
-    (typeof STANDARD_BLOOM_TARGET_SPEC)[keyof typeof STANDARD_BLOOM_TARGET_SPEC];
-  const targetSpec = new Map<string, BloomTargetSpec>(
-    Object.values(STANDARD_BLOOM_TARGET_SPEC).map((entry) => [entry.label, entry] as const),
+  const composited = graph.resources.filter(
+    (resource) => resource.label === STANDARD_BLOOM_TARGET_SPEC.composited.label,
   );
-  const targets = graph.resources.flatMap((resource) => {
-    const expected = targetSpec.get(resource.label);
-    return expected === undefined ? [] : [{ resource, expected }];
-  });
-  const passNames = new Set<string>(Object.values(TYPED_BLOOM_PASS_NAMES));
-  const passes = graph.passes.filter((pass) => passNames.has(pass.name));
+  const downsample = graph.resources
+    .filter((resource) => resource.label.startsWith(STANDARD_BLOOM_TARGET_SPEC.downsamplePrefix))
+    .sort((a, b) => a.label.localeCompare(b.label, undefined, { numeric: true }));
+  const upsample = graph.resources
+    .filter((resource) => resource.label.startsWith(STANDARD_BLOOM_TARGET_SPEC.upsamplePrefix))
+    .sort((a, b) => a.label.localeCompare(b.label, undefined, { numeric: true }));
+  const targets = [...composited, ...downsample, ...upsample];
+  const passes = graph.passes
+    .filter(
+      (pass) =>
+        pass.name === TYPED_BLOOM_PASS_NAMES.composite ||
+        pass.name.startsWith(`${TYPED_BLOOM_PASS_NAMES.downsample}-`) ||
+        pass.name.startsWith(`${TYPED_BLOOM_PASS_NAMES.upsample}-`),
+    )
+    .sort((left, right) => left.executionIndex - right.executionIndex);
   if (targets.length === 0 && passes.length === 0) return emptyBloomGraphInspection();
+  if (composited.length !== 1) return invalidBloomGraphInspection();
+  const compositedResource = composited[0];
+  if (compositedResource === undefined) return invalidBloomGraphInspection();
+  const compositedSize = resourceSize(compositedResource);
+  if (compositedSize === undefined) return invalidBloomGraphInspection();
+
+  const expected = standardBloomTargetSpecs(compositedSize.width, compositedSize.height);
+  const expectedDownsampleLabels = expected.downsample.map((entry) => entry.label);
+  const expectedUpsampleLabels = expected.upsample.map((entry) => entry.label);
+  const orderedDownsample = downsample.sort((left, right) =>
+    left.label.localeCompare(right.label, undefined, { numeric: true }),
+  );
+  const orderedUpsample = upsample.sort((left, right) =>
+    left.label.localeCompare(right.label, undefined, { numeric: true }),
+  );
   const completeTargetSet =
-    targets.length === Object.values(STANDARD_BLOOM_TARGET_SPEC).length &&
-    targets.every(({ resource, expected }) => textureBytes(resource, expected) > 0);
-  const completePassSet = passes.length === Object.values(TYPED_BLOOM_PASS_NAMES).length;
-  if (!completeTargetSet || !completePassSet) {
+    targets.length === 1 + expectedDownsampleLabels.length + expectedUpsampleLabels.length &&
+    orderedDownsample.length === expectedDownsampleLabels.length &&
+    orderedUpsample.length === expectedUpsampleLabels.length &&
+    orderedDownsample.every(
+      (resource, level) => resource.label === expectedDownsampleLabels[level],
+    ) &&
+    orderedUpsample.every((resource, level) => resource.label === expectedUpsampleLabels[level]) &&
+    orderedDownsample.every(
+      (resource, level) =>
+        resourceSize(resource)?.width === expected.levels[level]?.width &&
+        resourceSize(resource)?.height === expected.levels[level]?.height,
+    ) &&
+    orderedUpsample.every(
+      (resource, level) =>
+        resourceSize(resource)?.width === expected.levels[level]?.width &&
+        resourceSize(resource)?.height === expected.levels[level]?.height,
+    );
+  const expectedPassNames = [
+    ...expectedDownsampleLabels,
+    ...[...expectedUpsampleLabels].reverse(),
+    TYPED_BLOOM_PASS_NAMES.composite,
+  ];
+  const completePassSet =
+    passes.length === expected.levels.length + expected.upsample.length + 1 &&
+    passes.every((pass, index) => pass.name === expectedPassNames[index]);
+  const sceneLabel = passes[0]?.accesses[0]?.resource;
+  const passTopology =
+    completePassSet &&
+    sceneLabel !== undefined &&
+    !sceneLabel.startsWith(STANDARD_BLOOM_TARGET_SPEC.downsamplePrefix) &&
+    !sceneLabel.startsWith(STANDARD_BLOOM_TARGET_SPEC.upsamplePrefix) &&
+    sceneLabel !== STANDARD_BLOOM_TARGET_SPEC.composited.label &&
+    graph.resources.some((resource) => resource.label === sceneLabel) &&
+    orderedDownsample.every((_, level) =>
+      hasPassAccesses(passes[level], [
+        {
+          resource: level === 0 ? sceneLabel : `bloom-downsample-${level - 1}`,
+          usage: 'sampled-read',
+        },
+        { resource: `bloom-downsample-${level}`, usage: 'color-attachment' },
+      ]),
+    ) &&
+    orderedUpsample.every((_, level) => {
+      const passIndex = expected.levels.length + expected.upsample.length - 1 - level;
+      return hasPassAccesses(passes[passIndex], [
+        { resource: `bloom-downsample-${level}`, usage: 'sampled-read' },
+        {
+          resource:
+            level === expected.levels.length - 2
+              ? `bloom-downsample-${level + 1}`
+              : `bloom-upsample-${level + 1}`,
+          usage: 'sampled-read',
+        },
+        { resource: `bloom-upsample-${level}`, usage: 'color-attachment' },
+      ]);
+    }) &&
+    hasPassAccesses(passes.at(-1), [
+      { resource: sceneLabel, usage: 'sampled-read' },
+      {
+        resource: expected.levels.length === 1 ? 'bloom-downsample-0' : 'bloom-upsample-0',
+        usage: 'sampled-read',
+      },
+      { resource: STANDARD_BLOOM_TARGET_SPEC.composited.label, usage: 'color-attachment' },
+    ]);
+  if (!completeTargetSet || !passTopology) {
+    return invalidBloomGraphInspection();
+  }
+  const levelDimensions = orderedDownsample.flatMap((resource) => {
+    const size = resourceSize(resource);
+    return size === undefined ? [] : [size];
+  });
+  if (levelDimensions.length !== orderedDownsample.length) {
     return invalidBloomGraphInspection();
   }
+  const targetBytes = targets.reduce((bytes, resource) => bytes + (textureBytes(resource) ?? 0), 0);
   return {
     status: 'valid',
     targetCount: targets.length,
-    targetBytes: targets.reduce(
-      (bytes, target) => bytes + textureBytes(target.resource, target.expected),
-      0,
-    ),
+    targetBytes,
     passCount: passes.length,
+    levelCount: orderedDownsample.length,
+    levelDimensions,
+    downsamplePassCount: orderedDownsample.length,
+    upsamplePassCount: orderedUpsample.length,
   };
 }
 
@@ -159,8 +368,8 @@ function missingTemporalContributor(
 /**
  * Build the one Standard post chain shared by direct and clustered lighting.
  * Bloom is admitted before any Bloom target is declared, keeping the disabled
- * path exact-zero while preserving the existing half-resolution four-pass
- * implementation for the enabled path.
+ * path exact-zero while building one bounded five-level HDR
+ * downsample/tent-upsample pyramid for the enabled path.
  */
 export function addStandardPost(
   context: RenderPipelineBuildContext<RenderPipelineFrame>,
@@ -178,7 +387,8 @@ export function addStandardPost(
     lane: topology.standardProfile?.renderPath === 'deferred' ? 'clustered' : 'direct',
     temporal: !clearOnly && topology.camera.antialias === 'taa',
     meter: topology.output?.autoExposure === true,
-    bloom: !clearOnly && topology.camera.bloom === 'on' && topology.camera.tonemap !== 'none',
+    bloom: !clearOnly && standardBloomAdmitted(topology.camera),
+    dof: !clearOnly && topology.camera.depthOfField !== undefined,
     exposure: topology.output?.autoExposure === true,
     whiteBalance: topology.output?.whiteBalance === true,
     lut: topology.output?.colorLut === true,
@@ -218,6 +428,33 @@ export function addStandardPost(
   const finalPresent = surface.storage;
   let postInput = scene;
   let postTemporal = sceneTemporal;
+  if (!clearOnly && topology.analyticFog === true) {
+    if (depth.sampleCount !== 1)
+      return err(
+        new RenderGraphError({
+          code: 'resource-resolution-failed',
+          expected: 'analytic fog receives single-sample scene depth',
+          hint: 'select FXAA, TAA or no AA for analytic fog',
+          detail: { resourceLabel: 'scene-depth' },
+        }),
+      );
+    const fogged = target(context, 'analytic-fog-color', {
+      format: 'rgba16float',
+      size:
+        topology.extent === undefined ? 'surface' : renderExtentSize(topology.extent, 'internal'),
+      domain: hdr ? 'linear-hdr' : 'linear-ldr',
+    });
+    if (!fogged.ok) return fogged;
+    const fog = addTypedFullscreenPass(context.graph, {
+      name: 'analytic-fog',
+      shader: 'forgeax.analytic-fog',
+      input: postInput,
+      depth,
+      output: fogged.value,
+    });
+    if (!fog.ok) return fog;
+    postInput = fogged.value;
+  }
 
   const autoExposure = context.standardOutput?.autoExposure;
   if (outputPlan.features.exposure && autoExposure === undefined) {
@@ -239,7 +476,7 @@ export function addStandardPost(
       return err(missingTemporalContributor(topology, 'forgeax::standard::taa-history'));
     }
     const resolveTargets: TypedTemporalResolveTargets = {
-      scene,
+      scene: postInput,
       depth,
       currentTemporal: sceneTemporal,
       ...(coverage === undefined ? {} : { coverage }),
@@ -260,6 +497,20 @@ export function addStandardPost(
     postTemporal = history.currentTemporal;
   }
 
+  // Meter the temporally resolved color before lens-domain filters. Motion
+  // Blur and Bloom must consume a single exposure decision for this frame;
+  // running the meter after either filter makes the measured luminance depend
+  // on the authored streak radius and changes the exposure feedback loop.
+  if (outputPlan.features.exposure && autoExposure !== undefined) {
+    const added = addAutoExposureGraphPasses(context, {
+      source: postInput,
+      resources: autoExposure,
+      width: topology.surface.width,
+      height: topology.surface.height,
+    });
+    if (!added.ok) return added;
+  }
+
   // Feature projection and the built-in fallback share one target contract.
   // The projection runs after TAA so Motion Blur consumes the resolved color,
   // then both paths feed the same linear float target into Bloom/Output.
@@ -313,49 +564,46 @@ export function addStandardPost(
     }
   }
 
-  // Meter the temporally resolved color before Bloom. This preserves the
-  // Standard order: temporal -> meter -> bloom -> exposure/WB -> tone -> LUT.
-  if (outputPlan.features.exposure && autoExposure !== undefined) {
-    const added = addAutoExposureGraphPasses(context, {
-      source: postInput,
-      resources: autoExposure,
-      width: topology.surface.width,
-      height: topology.surface.height,
-    });
-    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,
-      STANDARD_BLOOM_TARGET_SPEC.composited.label,
-      STANDARD_BLOOM_TARGET_SPEC.composited,
-    );
+    const outputWidth = topology.extent?.outputWidth ?? topology.surface.width;
+    const outputHeight = topology.extent?.outputHeight ?? topology.surface.height;
+    const bloomSpecs = standardBloomTargetSpecs(outputWidth, outputHeight);
+    const composited = target(context, bloomSpecs.composited.label, bloomSpecs.composited);
     if (!composited.ok) return composited;
-    const bright = target(
-      context,
-      STANDARD_BLOOM_TARGET_SPEC.bright.label,
-      STANDARD_BLOOM_TARGET_SPEC.bright,
-    );
-    if (!bright.ok) return bright;
-    const blurH = target(
-      context,
-      STANDARD_BLOOM_TARGET_SPEC.blurH.label,
-      STANDARD_BLOOM_TARGET_SPEC.blurH,
-    );
-    if (!blurH.ok) return blurH;
-    const blurV = target(
-      context,
-      STANDARD_BLOOM_TARGET_SPEC.blurV.label,
-      STANDARD_BLOOM_TARGET_SPEC.blurV,
-    );
-    if (!blurV.ok) return blurV;
+    const downsample: RenderPipelineTarget[] = [];
+    for (const spec of bloomSpecs.downsample) {
+      const level = target(context, spec.label, spec);
+      if (!level.ok) return level;
+      downsample.push(level.value);
+    }
+    const upsample: RenderPipelineTarget[] = [];
+    for (const spec of bloomSpecs.upsample) {
+      const level = target(context, spec.label, spec);
+      if (!level.ok) return level;
+      upsample.push(level.value);
+    }
     const bloom = addTypedBloomPasses(context.graph, {
       scene: postInput,
       composited: composited.value,
-      bright: bright.value,
-      blurH: blurH.value,
-      blurV: blurV.value,
+      downsample,
+      upsample,
+      levelDimensions: bloomSpecs.levels,
     });
     if (!bloom.ok) return bloom;
     postInput = composited.value;

package/src/pipeline-spec.ts

@@ -562,8 +562,8 @@ export interface PassKindAttachmentPolicy {
  * 4. `'point-shadow-caster'` — HDRP point-shadow caster: depth-only
  * 5. `'skybox'` — fullscreen skybox: color-only clear/store
  * 6. `'tonemap'` — HDR→LDR tonemap fullscreen: color-only clear/store
- * 7. `'bloom-bright'` / `'bloom-blur'` — bloom downsample/blur: color-only
- *    clear/store
+ * 7. `'bloom-downsample'` / `'bloom-upsample'` — multiscale Bloom pyramid:
+ *    color-only clear/store
  * 8. `'bloom-composite'` — bloom add-back: color-only load/store (NOT clear)
  * 9. `'fxaa'` — fullscreen FXAA: color-only clear/store
  * 10. `'post-process'` — generic fullscreen primitive (SSAO, render-graph
@@ -633,7 +633,7 @@ export const passKindPolicyTable: Readonly<Record<string, PassKindAttachmentPoli
     },
     defaultDepthOps: undefined,
   },
-  'bloom-bright': {
+  'bloom-downsample': {
     shape: 'color-only',
     defaultColorOps: {
       loadOp: 'clear',
@@ -642,7 +642,7 @@ export const passKindPolicyTable: Readonly<Record<string, PassKindAttachmentPoli
     },
     defaultDepthOps: undefined,
   },
-  'bloom-blur': {
+  'bloom-upsample': {
     shape: 'color-only',
     defaultColorOps: {
       loadOp: 'clear',
@@ -1220,7 +1220,7 @@ export function buildSpecConstTable(
     // has sampleCount=4. Both use empty vertexLayout (fullscreen triangle, no
     // attributes) and cullMode='none' (forward cull for fullscreen-quad passthrough).
     //
-    // Shadow-probe / fxaa / bloom 4-stage / SSAO 2-stage are lazy-build — not in
+    // Shadow-probe / fxaa / Bloom 10-pass / SSAO 2-stage are lazy-build — not in
     // SPEC_CONST_TABLE (R-D4 decision: only entries that are always-present on
     // every boot).
 

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/points-lines/__tests__/view-ubo.unit.test.ts

@@ -25,7 +25,8 @@ function camera(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1,
     bloomIntensity: 1,
-    bloomBlurRadius: 4,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: [0, 0, 0, 1],
   };
 }

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -70,7 +70,8 @@ function camera(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1,
     bloomIntensity: 1,
-    bloomBlurRadius: 4,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: [0, 0, 0, 1],
   };
 }

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,7 +20,9 @@ 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 { MotionBlurExecutionReceipt } from '../inspection-types';
 import type { InstanceCollectionStore } from '../instances';
 import type { IblBindingInspection } from '../mesh-material-bindings';
 import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
@@ -378,7 +383,8 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1.0,
     bloomIntensity: 1.0,
-    bloomBlurRadius: 4.0,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: ZERO_CAMERA_CLEAR_FALLBACK,
   };
 }
@@ -403,6 +409,8 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  */
 export interface RenderFrameState {
   frameNumber: number;
+  /** Last successful Motion Blur compute execution; failed submits retain the prior receipt. */
+  motionBlurExecution?: MotionBlurExecutionReceipt;
   /** Final-submit Standard IBL binding-chain receipt for this frame. */
   iblBindingInspection?: IblBindingInspection;
   /** Demand for the frame-local Standard fallback MRT. */
@@ -452,6 +460,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;