@forgeax/engine-render 0.1.30 → 0.1.32

package/src/features/depth-of-field/depth-of-field-assembly.ts

@@ -0,0 +1,100 @@
+import type { ManifestEntry } from '@forgeax/engine-types';
+import type {
+  PostProcessReadEntry,
+  PostProcessShaderEntry,
+} from '../../fullscreen-post-process-pass';
+import type { DepthOfFieldInspection } from '../../inspection-types';
+import { DEPTH_OF_FIELD_POST_PROCESS_IDS } from './depth-of-field-feature';
+
+export interface DepthOfFieldShaderSources {
+  readonly singleSample?: string;
+  readonly multisampled?: string;
+}
+
+export function dofInspection(inspection: DepthOfFieldInspection | undefined): {
+  readonly depthOfField?: DepthOfFieldInspection;
+} {
+  return inspection === undefined ? {} : { depthOfField: Object.freeze(inspection) };
+}
+
+type DepthOfFieldRead = string | PostProcessReadEntry;
+type DepthOfFieldPostProcessId = (typeof DEPTH_OF_FIELD_POST_PROCESS_IDS)[number];
+type DepthOfFieldVariantSuffix = '' | '.msaa';
+type DepthOfFieldRegistrar = {
+  readonly registerBuiltinPostProcess: (id: string, entry: PostProcessShaderEntry) => unknown;
+};
+
+const DEPTH_READ: PostProcessReadEntry = { key: 'scene-depth', sampleType: 'depth' };
+const DEPTH_OF_FIELD_READS: Readonly<
+  Record<DepthOfFieldPostProcessId, readonly DepthOfFieldRead[]>
+> = {
+  'forgeax.dof.coc': ['scene-color', 'scene-temporal', DEPTH_READ],
+  'forgeax.dof.prefilter': ['scene-color', 'dof-coc', DEPTH_READ],
+  'forgeax.dof.prefilter.metadata': ['scene-color', 'scene-temporal', 'dof-coc', DEPTH_READ],
+  'forgeax.dof.gather': [
+    'dof-prefilter',
+    'scene-temporal',
+    'dof-coc',
+    'dof-prefilter-metadata',
+    DEPTH_READ,
+  ],
+  'forgeax.dof.background': ['scene-color', 'scene-temporal', 'dof-coc', DEPTH_READ],
+  'forgeax.dof.composite': [
+    'scene-color',
+    'scene-temporal',
+    'dof-coc',
+    'dof-near',
+    'dof-far',
+    'dof-background',
+    DEPTH_READ,
+  ],
+};
+
+/** Register all DoF graph declarations against the active RenderSystem. */
+export function registerDepthOfFieldBuiltins(
+  renderSystem: DepthOfFieldRegistrar,
+  entries: DepthOfFieldShaderSources,
+): void {
+  const register = (
+    baseId: DepthOfFieldPostProcessId,
+    source: string,
+    suffix: DepthOfFieldVariantSuffix,
+  ): void => {
+    const id = `${baseId}${suffix}`;
+    renderSystem.registerBuiltinPostProcess(id, {
+      source,
+      params: { byteSize: 64, defaultValue: new Uint8Array(64) },
+      reads: DEPTH_OF_FIELD_READS[baseId],
+    });
+  };
+  if (entries.singleSample !== undefined) {
+    for (const id of DEPTH_OF_FIELD_POST_PROCESS_IDS) register(id, entries.singleSample, '');
+  }
+  if (entries.multisampled !== undefined) {
+    for (const id of DEPTH_OF_FIELD_POST_PROCESS_IDS) register(id, entries.multisampled, '.msaa');
+  }
+}
+
+/** Prewarm both DoF shader variants before publishing renderer readiness. */
+export async function prewarmDepthOfField(
+  manifestEntries: readonly ManifestEntry[],
+  prewarm: (entry: ManifestEntry | undefined, id: string) => Promise<void>,
+  register: (entries: DepthOfFieldShaderSources) => void,
+): Promise<void> {
+  let singleSample: ManifestEntry | undefined;
+  let multisampled: ManifestEntry | undefined;
+  for (const entry of manifestEntries) {
+    if (!entry.wgsl.includes('DepthOfFieldParams')) continue;
+    if (entry.wgsl.includes('texture_depth_multisampled_2d')) {
+      multisampled ??= entry;
+    } else {
+      singleSample ??= entry;
+    }
+  }
+  for (const id of DEPTH_OF_FIELD_POST_PROCESS_IDS) await prewarm(singleSample, id);
+  for (const id of DEPTH_OF_FIELD_POST_PROCESS_IDS) await prewarm(multisampled, `${id}.msaa`);
+  register({
+    ...(singleSample === undefined ? {} : { singleSample: singleSample.wgsl }),
+    ...(multisampled === undefined ? {} : { multisampled: multisampled.wgsl }),
+  });
+}

package/src/features/depth-of-field/depth-of-field-feature.ts

@@ -0,0 +1,295 @@
+import { type RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { DepthOfFieldSide } from '../../components/depth-of-field';
+import type { RenderExtent } from '../../pipeline/render-extent';
+import { renderExtentSize } from '../../pipeline/render-extent';
+import type { RenderPipelineFrame, RenderPipelineTarget } from '../../render-pipeline';
+import { createRenderPipelineTarget } from '../../render-pipeline';
+import { addTypedFullscreenPass } from '../../typed-render-graph-primitives';
+import type { DepthOfFieldParams } from './depth-of-field-params';
+
+export const DEPTH_OF_FIELD_FEATURE_IDENTITY = 'forgeax.depth-of-field';
+export const DEPTH_OF_FIELD_COC_ID = 'forgeax.dof.coc';
+export const DEPTH_OF_FIELD_PREFILTER_ID = 'forgeax.dof.prefilter';
+export const DEPTH_OF_FIELD_PREFILTER_METADATA_ID = 'forgeax.dof.prefilter.metadata';
+export const DEPTH_OF_FIELD_GATHER_ID = 'forgeax.dof.gather';
+export const DEPTH_OF_FIELD_BACKGROUND_ID = 'forgeax.dof.background';
+export const DEPTH_OF_FIELD_COMPOSITE_ID = 'forgeax.dof.composite';
+
+/** All declarations are registered together so the build catalog is finite. */
+export const DEPTH_OF_FIELD_POST_PROCESS_IDS = Object.freeze([
+  DEPTH_OF_FIELD_COC_ID,
+  DEPTH_OF_FIELD_PREFILTER_ID,
+  DEPTH_OF_FIELD_PREFILTER_METADATA_ID,
+  DEPTH_OF_FIELD_GATHER_ID,
+  DEPTH_OF_FIELD_BACKGROUND_ID,
+  DEPTH_OF_FIELD_COMPOSITE_ID,
+] as const);
+export const DEPTH_OF_FIELD_MSAA_POST_PROCESS_IDS = Object.freeze(
+  DEPTH_OF_FIELD_POST_PROCESS_IDS.map((id) => `${id}.msaa` as const),
+);
+
+export function depthOfFieldPostProcessId(id: string, multisampled: boolean): string {
+  return multisampled ? `${id}.msaa` : id;
+}
+
+export interface DepthOfFieldTopology {
+  readonly blurSide: DepthOfFieldSide;
+  readonly useNear: boolean;
+  readonly useFar: boolean;
+}
+
+export function depthOfFieldTopology(
+  params: DepthOfFieldParams | undefined,
+): DepthOfFieldTopology | undefined {
+  if (params === undefined || params.maxRadiusPixels <= 0) return undefined;
+  return {
+    blurSide: params.blurSide,
+    useNear: params.blurSide === 'near' || params.blurSide === 'both',
+    useFar: params.blurSide === 'far' || params.blurSide === 'both',
+  };
+}
+
+function target(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  label: string,
+  descriptor: Parameters<RenderGraphBuilder<RenderPipelineFrame>['createTexture']>[1],
+): Result<RenderPipelineTarget, RenderGraphError> {
+  return createRenderPipelineTarget(graph, label, descriptor);
+}
+
+function addPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  options: Parameters<typeof addTypedFullscreenPass>[1],
+): Result<void, RenderGraphError> {
+  return addTypedFullscreenPass(graph, options);
+}
+
+function sideParams(params: DepthOfFieldParams, side: 'near' | 'far'): DepthOfFieldParams {
+  return Object.freeze({ ...params, blurSide: side });
+}
+
+/**
+ * Project the built-in spatial DoF graph after the shared temporal/metering
+ * seam. The graph owns every intermediate; the renderer only supplies UBO
+ * bytes and the manifest-backed fullscreen programs at record time.
+ */
+export function addDepthOfFieldPasses(
+  context: {
+    readonly graph: RenderGraphBuilder<RenderPipelineFrame>;
+    readonly camera: {
+      readonly depthOfField?: DepthOfFieldParams | undefined;
+    };
+    readonly temporalTaa: boolean;
+    readonly msaaActive?: boolean;
+    /** Shared Standard pixel domains. DoF never invents a second extent. */
+    readonly extent?: RenderExtent;
+  },
+  input: RenderPipelineTarget,
+  depth: RenderPipelineTarget,
+  temporal?: RenderPipelineTarget,
+): Result<RenderPipelineTarget, RenderGraphError> {
+  const params = context.camera.depthOfField;
+  const topology = depthOfFieldTopology(params);
+  if (params === undefined || topology === undefined) return ok(input);
+
+  // The graph texture is the contract. Never select the multisampled shader
+  // from a camera flag while the bound depth target is single-sample.
+  const multisampled = depth.sampleCount === 4;
+  const graph = context.graph;
+  const extentSize =
+    context.extent === undefined
+      ? undefined
+      : renderExtentSize(context.extent, context.temporalTaa ? 'output' : 'internal');
+  const fullSize = extentSize ?? ('surface' as const);
+  const halfSize =
+    extentSize === undefined
+      ? ('half-surface' as const)
+      : {
+          width: Math.max(1, Math.ceil(extentSize.width / 2)),
+          height: Math.max(1, Math.ceil(extentSize.height / 2)),
+        };
+  const coc = target(graph, 'dof-coc', {
+    format: 'rgba16float',
+    size: fullSize,
+    domain: 'linear-hdr',
+  });
+  if (!coc.ok) return coc;
+  const cocPass = addPass(graph, {
+    name: 'dof-coc',
+    shader: depthOfFieldPostProcessId(DEPTH_OF_FIELD_COC_ID, multisampled),
+    fragmentEntryPoint: 'fs_coc',
+    input,
+    depth,
+    output: coc.value,
+    additionalReads: [
+      {
+        key: 'scene-temporal',
+        // No-TAA DoF deliberately aliases this optional input to current color;
+        // only the TAA route consumes the matching resolved temporal attachment.
+        target: context.temporalTaa && temporal !== undefined ? temporal : input,
+      },
+    ],
+  });
+  if (!cocPass.ok) return cocPass;
+
+  const near = topology.useNear
+    ? target(graph, 'dof-near', { format: 'rgba16float', size: halfSize })
+    : undefined;
+  if (near !== undefined && !near.ok) return near;
+  const far = topology.useFar
+    ? target(graph, 'dof-far', { format: 'rgba16float', size: halfSize })
+    : undefined;
+  if (far !== undefined && !far.ok) return far;
+  const background = topology.useNear
+    ? target(graph, 'dof-background', { format: 'rgba16float', size: halfSize })
+    : undefined;
+  if (background !== undefined && !background.ok) return background;
+
+  for (const side of ['near', 'far'] as const) {
+    const enabled = side === 'near' ? topology.useNear : topology.useFar;
+    if (!enabled) continue;
+    const prefilter = target(graph, `dof-prefilter-${side}`, {
+      format: 'rgba16float',
+      size: halfSize,
+    });
+    if (!prefilter.ok) return prefilter;
+    const blur = side === 'near' ? near : far;
+    if (blur === undefined || !blur.ok) {
+      return err(
+        new RenderGraphError({
+          code: 'resource-resolution-failed',
+          expected: `${side} DoF target is declared before its gather pass`,
+          hint: 'retain the last-known-good Standard graph and retry DoF admission',
+          detail: { resourceLabel: `dof-${side}` },
+        }),
+      );
+    }
+    const prefilterPass = addPass(graph, {
+      name: `dof-prefilter-${side}`,
+      shader: depthOfFieldPostProcessId(DEPTH_OF_FIELD_PREFILTER_ID, multisampled),
+      fragmentEntryPoint: side === 'near' ? 'fs_prefilter_near' : 'fs_prefilter_far',
+      input,
+      depth,
+      output: prefilter.value,
+      additionalReads: [{ key: 'dof-coc', target: coc.value }],
+    });
+    if (!prefilterPass.ok) return prefilterPass;
+    const prefilterMetadata = target(graph, `dof-prefilter-${side}-metadata`, {
+      format: 'rgba16float',
+      size: halfSize,
+    });
+    if (!prefilterMetadata.ok) return prefilterMetadata;
+    const metadataPass = addPass(graph, {
+      name: `dof-prefilter-${side}-metadata`,
+      shader: depthOfFieldPostProcessId(DEPTH_OF_FIELD_PREFILTER_METADATA_ID, multisampled),
+      fragmentEntryPoint:
+        side === 'near' ? 'fs_prefilter_metadata_near' : 'fs_prefilter_metadata_far',
+      input,
+      depth,
+      output: prefilterMetadata.value,
+      additionalReads: [
+        {
+          key: 'scene-temporal',
+          target: context.temporalTaa && temporal !== undefined ? temporal : input,
+        },
+        { key: 'dof-coc', target: coc.value },
+      ],
+    });
+    if (!metadataPass.ok) return metadataPass;
+    const gatherPass = addPass(graph, {
+      name: `dof-gather-${side}`,
+      shader: depthOfFieldPostProcessId(DEPTH_OF_FIELD_GATHER_ID, multisampled),
+      fragmentEntryPoint: side === 'near' ? 'fs_gather_near' : 'fs_gather_far',
+      input: prefilter.value,
+      depth,
+      output: blur.value,
+      additionalReads: [
+        {
+          key: 'scene-temporal',
+          target: context.temporalTaa && temporal !== undefined ? temporal : input,
+        },
+        { key: 'dof-coc', target: coc.value },
+        { key: 'dof-prefilter-metadata', target: prefilterMetadata.value },
+      ],
+    });
+    if (!gatherPass.ok) return gatherPass;
+  }
+
+  if (background?.ok) {
+    const backgroundPass = addPass(graph, {
+      name: 'dof-fill-background',
+      shader: depthOfFieldPostProcessId(DEPTH_OF_FIELD_BACKGROUND_ID, multisampled),
+      fragmentEntryPoint: 'fs_background',
+      input,
+      depth,
+      output: background.value,
+      additionalReads: [
+        {
+          key: 'scene-temporal',
+          target: context.temporalTaa && temporal !== undefined ? temporal : input,
+        },
+        { key: 'dof-coc', target: coc.value },
+      ],
+    });
+    if (!backgroundPass.ok) return backgroundPass;
+  }
+
+  const composite = target(graph, 'dof-composite', {
+    format: input.format,
+    size: fullSize,
+    domain: input.domain,
+  });
+  if (!composite.ok) return composite;
+  const nearInput = near?.ok === true ? near.value : input;
+  const farInput = far?.ok === true ? far.value : input;
+  const backgroundInput = background?.ok === true ? background.value : input;
+  const compositePass = addPass(graph, {
+    name: 'dof-composite',
+    shader: depthOfFieldPostProcessId(DEPTH_OF_FIELD_COMPOSITE_ID, multisampled),
+    fragmentEntryPoint: 'fs_composite',
+    input,
+    depth,
+    output: composite.value,
+    additionalReads: [
+      {
+        key: 'scene-temporal',
+        // The composite shader always owns the temporal-depth slot. Without
+        // TAA, the current input is the explicit alias for that slot.
+        target: context.temporalTaa && temporal !== undefined ? temporal : input,
+      },
+      { key: 'dof-coc', target: coc.value },
+      // Disabled sides alias the original input so their resources and gathers
+      // are absent while the fixed composite binding contract stays valid.
+      { key: 'dof-near', target: nearInput },
+      { key: 'dof-far', target: farInput },
+      { key: 'dof-background', target: backgroundInput },
+    ],
+  });
+  if (!compositePass.ok) return compositePass;
+  return ok(composite.value);
+}
+
+/** Return the bound pass names expected from an admitted DoF topology. */
+export function depthOfFieldPassNames(topology: DepthOfFieldTopology): readonly string[] {
+  const names = ['dof-coc'];
+  if (topology.useNear)
+    names.push(
+      'dof-prefilter-near',
+      'dof-prefilter-near-metadata',
+      'dof-gather-near',
+      'dof-fill-background',
+    );
+  if (topology.useFar)
+    names.push('dof-prefilter-far', 'dof-prefilter-far-metadata', 'dof-gather-far');
+  names.push('dof-composite');
+  return Object.freeze(names);
+}
+
+/** Encode params with a side-local optical declaration for future debug views. */
+export function depthOfFieldSideParams(
+  params: DepthOfFieldParams,
+  side: 'near' | 'far',
+): DepthOfFieldParams {
+  return sideParams(params, side);
+}

package/src/features/depth-of-field/depth-of-field-inspection.ts

@@ -0,0 +1,237 @@
+import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
+import type { DepthOfFieldInspection } from '../../inspection-types';
+import { depthOfFieldPassNames, depthOfFieldTopology } from './depth-of-field-feature';
+import {
+  DEFAULT_DEPTH_OF_FIELD_PARAMS,
+  type DepthOfFieldParams,
+  type DepthOfFieldRequestFailure,
+} from './depth-of-field-params';
+
+const DOF_FORMAT_BYTES: Readonly<Record<string, number>> = Object.freeze({
+  rgba16float: 8,
+  rgba8unorm: 4,
+});
+
+function resourceBytes(resource: CompiledRenderGraphInfo['resources'][number]): number {
+  if (resource.byteSize !== undefined) return resource.byteSize;
+  const descriptor = resource.descriptor;
+  if (descriptor.kind !== 'texture') return 0;
+  const texelBytes = DOF_FORMAT_BYTES[descriptor.format] ?? 0;
+  if (texelBytes === 0) return 0;
+  let bytes = 0;
+  for (let level = 0; level < descriptor.mipLevelCount; level += 1) {
+    bytes +=
+      Math.max(1, descriptor.width >> level) *
+      Math.max(1, descriptor.height >> level) *
+      descriptor.depthOrArrayLayers *
+      texelBytes;
+  }
+  return bytes * descriptor.sampleCount;
+}
+
+function textureExtent(
+  graph: CompiledRenderGraphInfo,
+  label: string,
+): { readonly width: number; readonly height: number } | undefined {
+  const resource = graph.resources.find(
+    (candidate) => candidate.kind === 'texture' && candidate.label === label,
+  );
+  if (resource?.descriptor.kind !== 'texture') return undefined;
+  return { width: resource.descriptor.width, height: resource.descriptor.height };
+}
+
+export interface DepthOfFieldGraphInspection {
+  readonly status: 'empty' | 'active' | 'invalid';
+  readonly outputExtent: { readonly width: number; readonly height: number };
+  readonly workExtent: { readonly width: number; readonly height: number };
+  readonly passCount: number;
+  readonly textureBytes: number;
+  readonly graphGeneration: number;
+}
+
+export interface DepthOfFieldAcceptedState {
+  readonly params: DepthOfFieldParams;
+  readonly graph: CompiledRenderGraphInfo;
+  readonly deviceGeneration: number;
+}
+
+const emptyExtent = Object.freeze({ width: 0, height: 0 });
+const OFF_PARAMS = Object.freeze({ ...DEFAULT_DEPTH_OF_FIELD_PARAMS, maxRadiusPixels: 0 });
+
+/** Inspect only the compiled graph facts owned by the DoF feature. */
+export function inspectDepthOfFieldGraph(
+  graph: CompiledRenderGraphInfo | undefined,
+  params: DepthOfFieldParams | undefined,
+): DepthOfFieldGraphInspection {
+  const topology = depthOfFieldTopology(params);
+  if (graph === undefined || topology === undefined) {
+    return {
+      status: 'empty',
+      outputExtent: emptyExtent,
+      workExtent: emptyExtent,
+      passCount: 0,
+      textureBytes: 0,
+      graphGeneration: graph?.generation ?? 0,
+    };
+  }
+  const expectedPasses = new Set(depthOfFieldPassNames(topology));
+  const passes = graph.passes.filter((pass) => expectedPasses.has(pass.name));
+  const dofResources = graph.resources.filter(
+    (resource) => resource.kind === 'texture' && resource.label.startsWith('dof-'),
+  );
+  const expectedResourceLabels = [
+    'dof-coc',
+    ...(topology.useNear
+      ? ['dof-near', 'dof-prefilter-near', 'dof-prefilter-near-metadata', 'dof-background']
+      : []),
+    ...(topology.useFar ? ['dof-far', 'dof-prefilter-far', 'dof-prefilter-far-metadata'] : []),
+    'dof-composite',
+  ];
+  const resourceLabels = new Set(dofResources.map((resource) => resource.label));
+  const completePasses =
+    passes.length === expectedPasses.size && passes.every((pass) => expectedPasses.has(pass.name));
+  const completeResources =
+    dofResources.length === expectedResourceLabels.length &&
+    expectedResourceLabels.every((label) => resourceLabels.has(label)) &&
+    dofResources.every((resource) => resourceBytes(resource) > 0);
+  const outputExtent = textureExtent(graph, 'dof-composite') ?? emptyExtent;
+  const workExtent = textureExtent(graph, topology.useNear ? 'dof-near' : 'dof-far') ?? emptyExtent;
+  return {
+    status: completePasses && completeResources ? 'active' : 'invalid',
+    outputExtent,
+    workExtent,
+    passCount: completePasses ? passes.length : 0,
+    textureBytes: completeResources
+      ? dofResources.reduce((bytes, resource) => bytes + resourceBytes(resource), 0)
+      : 0,
+    graphGeneration: graph.generation,
+  };
+}
+
+export function projectDepthOfFieldInspection(input: {
+  readonly params?: DepthOfFieldParams;
+  readonly graph?: CompiledRenderGraphInfo;
+  readonly deviceGeneration: number;
+  readonly error?: DepthOfFieldRequestFailure | undefined;
+  /** Explicit submit-bound state supplied by Renderer.inspect(). */
+  readonly accepted?: DepthOfFieldAcceptedState | undefined;
+  readonly lastSubmitFailed?: boolean | undefined;
+}): DepthOfFieldInspection {
+  const params = input.params ?? OFF_PARAMS;
+  const topology = input.error === undefined ? depthOfFieldTopology(input.params) : undefined;
+  const requested = {
+    focusDistance: params.focusDistance,
+    fStop: params.fStop,
+    sensorHeight: params.sensorHeight,
+    maxRadiusPixels: params.maxRadiusPixels,
+    quality: params.quality,
+    blurSide: params.blurSide,
+  } as const;
+  const enabled = input.error !== undefined || topology !== undefined;
+  const transactionBound = 'accepted' in input;
+  const accepted = input.accepted;
+  const acceptedTopology = depthOfFieldTopology(accepted?.params);
+  const acceptedGraph =
+    accepted === undefined ? undefined : inspectDepthOfFieldGraph(accepted.graph, accepted.params);
+  const acceptedValid =
+    accepted !== undefined &&
+    accepted.deviceGeneration === input.deviceGeneration &&
+    acceptedTopology !== undefined &&
+    acceptedGraph?.status === 'active';
+  const candidateGraph = inspectDepthOfFieldGraph(input.graph, input.params);
+  // Renderer.inspect() is transaction-bound: a compiled candidate is useful
+  // for diagnosis, but it is not the effective graph until submit succeeds.
+  // Direct callers that omit `accepted` retain the original structural
+  // projection semantics used by graph-only tests and tools.
+  const graph = transactionBound
+    ? acceptedValid
+      ? (acceptedGraph ?? candidateGraph)
+      : candidateGraph
+    : candidateGraph;
+  const status: DepthOfFieldInspection['status'] =
+    input.error?.code === 'depth-of-field-orthographic-unsupported'
+      ? 'unsupported'
+      : input.error !== undefined
+        ? 'invalid'
+        : !enabled
+          ? 'off'
+          : transactionBound
+            ? acceptedValid && !input.lastSubmitFailed && requestedEqual(requested, accepted.params)
+              ? 'active'
+              : input.lastSubmitFailed
+                ? 'invalid'
+                : candidateGraph.status === 'invalid'
+                  ? 'invalid'
+                  : 'reset'
+            : graph.status === 'active'
+              ? 'active'
+              : graph.status === 'invalid'
+                ? 'invalid'
+                : 'reset';
+  const effective = acceptedValid
+    ? {
+        focusDistance: accepted.params.focusDistance,
+        fStop: accepted.params.fStop,
+        sensorHeight: accepted.params.sensorHeight,
+        maxRadiusPixels: accepted.params.maxRadiusPixels,
+        quality: accepted.params.quality,
+        blurSide: accepted.params.blurSide,
+      }
+    : status === 'active'
+      ? requested
+      : undefined;
+  const effectiveParams = acceptedValid
+    ? accepted.params
+    : status === 'active'
+      ? params
+      : undefined;
+  return Object.freeze({
+    enabled,
+    status,
+    requested,
+    ...(effective === undefined ? {} : { effective }),
+    focalLength: effectiveParams?.focalLength ?? params.focalLength,
+    outputExtent: graph.outputExtent,
+    workExtent: graph.workExtent,
+    tapCount:
+      effectiveParams !== undefined
+        ? effectiveParams.quality === 'low'
+          ? 16
+          : effectiveParams.quality === 'medium'
+            ? 32
+            : 64
+        : 0,
+    passCount: graph.passCount,
+    textureBytes: graph.textureBytes,
+    transparentPolicy: 'opaque-depth-approximation',
+    graphGeneration: graph.graphGeneration,
+    deviceGeneration: input.deviceGeneration,
+    lastKnownGood: acceptedValid || status === 'active',
+    ...(input.error === undefined ? {} : { error: input.error }),
+    ...(input.error?.code === 'depth-of-field-orthographic-unsupported'
+      ? { fallbackReason: 'orthographic-unsupported' as const }
+      : input.error !== undefined
+        ? { fallbackReason: 'invalid-params' as const }
+        : status === 'off'
+          ? { fallbackReason: 'zero-radius' as const }
+          : status === 'reset'
+            ? { fallbackReason: 'shader-not-ready' as const }
+            : status === 'invalid'
+              ? { fallbackReason: 'candidate-failed' as const }
+              : {}),
+  });
+}
+
+function requestedEqual(
+  requested: DepthOfFieldInspection['requested'],
+  params: DepthOfFieldParams,
+): boolean {
+  return (
+    requested.focusDistance === params.focusDistance &&
+    requested.fStop === params.fStop &&
+    requested.sensorHeight === params.sensorHeight &&
+    requested.maxRadiusPixels === params.maxRadiusPixels &&
+    requested.quality === params.quality &&
+    requested.blurSide === params.blurSide
+  );
+}