@forgeax/engine-render 0.1.32 → 0.1.34

package/src/pipeline/standard-post.ts

@@ -5,8 +5,13 @@ 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 { RenderFeatureCapabilityMissingError, SceneDataUnavailableError } from '../errors/render';
+import {
+  BARREL_DISTORTION_FEATURE_IDENTITY,
+  BARREL_DISTORTION_POST_PROCESS_ID,
+} from '../features/barrel-distortion';
 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';
@@ -30,6 +35,7 @@ import {
   TYPED_BLOOM_PASS_NAMES,
   type TypedTemporalResolveTargets,
 } from '../typed-render-graph-primitives';
+import { renderExtentSize } from './render-extent';
 import {
   addAutoExposureExposurePass,
   addAutoExposureGraphPasses,
@@ -42,22 +48,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 => ({
@@ -65,6 +130,10 @@ const emptyBloomGraphInspection = (): StandardBloomGraphInspection => ({
   targetCount: 0,
   targetBytes: 0,
   passCount: 0,
+  levelCount: 0,
+  levelDimensions: [],
+  downsamplePassCount: 0,
+  upsamplePassCount: 0,
 });
 
 const invalidBloomGraphInspection = (): StandardBloomGraphInspection => ({
@@ -72,21 +141,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) {
@@ -96,7 +167,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. */
@@ -104,33 +224,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,
   };
 }
 
@@ -160,8 +372,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>,
@@ -179,14 +391,27 @@ 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,
+    barrelDistortion: topology.camera.barrelDistortion === true,
     fxaa: !clearOnly && topology.camera.antialias === 'fxaa',
     outputEncoding: 'explicit-oetf',
   });
+  if (
+    outputPlan.features.barrelDistortion &&
+    context.capabilities?.rgba16floatRenderable !== true
+  ) {
+    return err(
+      new RenderFeatureCapabilityMissingError(
+        BARREL_DISTORTION_FEATURE_IDENTITY,
+        0,
+        'rgba16floatRenderable',
+      ),
+    );
+  }
   const hdr =
     !clearOnly && (topology.camera.tonemap !== 'none' || topology.camera.antialias === 'taa');
   // Bloom is an HDR-domain effect and its recorders intentionally no-op when
@@ -202,7 +427,15 @@ export function addStandardPost(
   const rawOnly = !clearOnly && topology.surface.profile?.kind === 'raw-only';
   const outputDither = resolveOutputDither(topology.config);
   const motionBlur = !clearOnly && topology.temporal?.motionBlur === true;
-  const postEffects = clearOnly ? [] : (topology.config?.postEffects ?? []);
+  // The barrel declaration is supplied by the ordinary feature host so its
+  // shader stays prepared and recoverable, but Standard owns its one explicit
+  // linear-LDR stage below. Do not send that identity through the generic
+  // encoded tail, or storage-buffer lanes would sample the image twice.
+  const postEffects = clearOnly
+    ? []
+    : (topology.config?.postEffects ?? []).filter(
+        (identity) => identity !== BARREL_DISTORTION_POST_PROCESS_ID,
+      );
   const rawOnlyPostInput =
     rawOnly && topology.lane.storageBuffer && postEffects.length > 0
       ? target(context, 'standard-post-effects-input', {
@@ -220,6 +453,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) {
@@ -241,7 +501,7 @@ export function addStandardPost(
       return err(missingTemporalContributor(topology, 'forgeax::standard::taa-history'));
     }
     const resolveTargets: TypedTemporalResolveTargets = {
-      scene,
+      scene: postInput,
       depth,
       currentTemporal: sceneTemporal,
       ...(coverage === undefined ? {} : { coverage }),
@@ -262,26 +522,40 @@ 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.
+  const featureTargets = [
+    {
+      kind: 'scene-color' as const,
+      texture: scene.texture,
+      view: scene.view,
+      format: scene.format,
+      sampleCount: scene.sampleCount,
+    },
+    {
+      kind: 'scene-depth' as const,
+      texture: depth.texture,
+      view: depth.view,
+      format: depth.format,
+      sampleCount: depth.sampleCount,
+    },
+  ];
   if (!clearOnly) {
-    const featureTargets = [
-      {
-        kind: 'scene-color' as const,
-        texture: scene.texture,
-        view: scene.view,
-        format: scene.format,
-        sampleCount: scene.sampleCount,
-      },
-      {
-        kind: 'scene-depth' as const,
-        texture: depth.texture,
-        view: depth.view,
-        format: depth.format,
-        sampleCount: depth.sampleCount,
-      },
-    ];
     if (motionBlur) {
       if (postTemporal === undefined) {
         return err(
@@ -294,10 +568,16 @@ export function addStandardPost(
         domain: hdr ? 'linear-hdr' : 'linear-ldr',
       });
       if (!blurred.ok) return blurred;
-      const features = context.contributeFeatures(featureTargets, [postTemporal], {
-        'motion-input': postInput,
-        'motion-output': blurred.value,
-      });
+      const features = context.contributeFeatures(
+        featureTargets,
+        [postTemporal],
+        {
+          'motion-input': postInput,
+          'motion-output': blurred.value,
+        },
+        [],
+        { exclude: [BARREL_DISTORTION_FEATURE_IDENTITY] },
+      );
       if (!features.ok) return features;
       if (context.hasFeature?.('forgeax.motion-blur') === true) {
         postInput = blurred.value;
@@ -310,23 +590,14 @@ export function addStandardPost(
       const features = context.contributeFeatures(
         featureTargets,
         sceneTemporal === undefined ? [] : [sceneTemporal],
+        {},
+        [],
+        { exclude: [BARREL_DISTORTION_FEATURE_IDENTITY] },
       );
       if (!features.ok) return features;
     }
   }
 
-  // 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,
-      resources: autoExposure,
-      width: topology.surface.width,
-      height: topology.surface.height,
-    });
-    if (!added.ok) return added;
-  }
-
   if (outputPlan.features.dof) {
     const dof = addDepthOfFieldPasses(
       {
@@ -343,38 +614,30 @@ export function addStandardPost(
     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;
@@ -409,6 +672,7 @@ export function addStandardPost(
     outputPlan.features.lut ||
     outputPlan.features.exposure ||
     outputPlan.features.whiteBalance ||
+    outputPlan.features.barrelDistortion ||
     // A receipt-bound observation request is an explicit producer demand, not
     // a new authored color feature.  When a caller asks for the linear-LDR
     // domain on the ordinary ACES path, retain the same tone/output boundary
@@ -460,11 +724,42 @@ export function addStandardPost(
     postInput = lutOutput.value;
   }
 
-  if (rawOnly) {
+  // Debug geometry is world-space scene content. Insert it before the spatial
+  // warp so its lines and markers bend with the rendered world. Screen-space
+  // diagnostics remain on the final surface below when no warp is active.
+  const debugOverlayBeforeBarrel = outputPlan.features.barrelDistortion;
+  if (rawOnly || debugOverlayBeforeBarrel) {
     const overlay = addTypedDebugOverlayPass(context.graph, postInput);
     if (!overlay.ok) return overlay;
   }
 
+  if (outputPlan.features.barrelDistortion) {
+    const barrelOutput = target(context, 'standard-barrel-distortion', {
+      format: 'rgba16float',
+      size: 'surface',
+      domain: 'linear-ldr',
+    });
+    if (!barrelOutput.ok) return barrelOutput;
+    const barrel = context.contributeFeatures(
+      featureTargets,
+      [],
+      { 'barrel-input': postInput, 'barrel-output': barrelOutput.value },
+      [],
+      { include: [BARREL_DISTORTION_FEATURE_IDENTITY] },
+    );
+    if (!barrel.ok) return barrel;
+    if (context.hasFeature?.(BARREL_DISTORTION_FEATURE_IDENTITY) !== true) {
+      return err(
+        new RenderFeatureCapabilityMissingError(
+          BARREL_DISTORTION_FEATURE_IDENTITY,
+          0,
+          'rgba16floatRenderable',
+        ),
+      );
+    }
+    postInput = barrelOutput.value;
+  }
+
   if (hdr || linearLdr || fxaa || rawOnly || motionBlur) {
     if (fxaa) {
       const output = splitOutput
@@ -568,7 +863,7 @@ export function addStandardPost(
     if (!effects.ok) return effects;
   }
 
-  return rawOnly
+  return rawOnly || debugOverlayBeforeBarrel
     ? ok(undefined)
     : addTypedDebugOverlayPass(context.graph, surface.display ?? surface.storage);
 }

package/src/pipeline-builder.ts

@@ -135,7 +135,7 @@ export interface PipelineBuilderContext {
    */
   readonly vertexBuffers: readonly GPUVertexBufferLayout[];
   /** Explicit layout family selected by the renderer assembly. */
-  readonly layoutKind?: 'pbr-skin' | 'gpu-driven-skin' | undefined;
+  readonly layoutKind?: 'pbr-skin' | 'gpu-driven-skin' | 'gpu-driven-cluster-skin' | undefined;
   /** Pipeline label (for GPU debug captures); defaults to `pbr-pipeline-${id}`. */
   readonly label?: string | undefined;
   /**