@forgeax/engine-render 0.1.33 → 0.1.34

package/src/pipeline/standard-pipeline.ts

@@ -6,9 +6,16 @@ import {
   RenderGraphError,
 } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import { CLOUD_LAYER_FEATURE_IDENTITY } from '../cloud/feature';
 import { addAtmosphereBackground } from '../environment/background';
 import { SceneDataUnavailableError, StandardProfileInvalidError } from '../errors/render';
 import type { FramePlan } from '../extract/environment';
+import { BARREL_DISTORTION_FEATURE_IDENTITY } from '../features/barrel-distortion';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import { DEFERRED_COLOR_FORMATS } from '../pipeline-spec';
 import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
@@ -16,12 +23,14 @@ import type {
   RenderPipeline,
   RenderPipelineBuildContext,
   RenderPipelineFrame,
+  RenderPipelineSurfaceMediumPair,
   RenderPipelineTopology,
 } from '../render-pipeline';
 import {
   createRenderPipelineTarget,
   importRenderPipelineSurface,
   type RenderPipelineTarget,
+  renderPipelineCloudHistoryTargets,
 } from '../render-pipeline';
 import { addSsrCompositionPass } from '../ssr/compose';
 import { addSsrSpatialPasses } from '../ssr/graph';
@@ -48,6 +57,10 @@ import {
 import { addTypedShadowPasses } from '../typed-shadow-passes';
 import { addAuthoredVolumetricFogPasses } from '../volume/passes';
 import { renderExtentSize } from './render-extent';
+import {
+  addSingleLayerMediumPasses,
+  addSingleLayerMediumRawDepthProducer,
+} from './single-layer-medium-passes';
 import type { StandardPipelineBuildContext } from './standard-build-context';
 import { buildStandardForwardLane } from './standard-forward-lane';
 import {
@@ -172,6 +185,10 @@ function buildStandardDeferredLane(
   if (!surface.ok) return surface;
   const internalSize =
     topology.extent === undefined ? 'surface' : renderExtentSize(topology.extent, 'internal');
+  const internalCopySize =
+    topology.extent === undefined
+      ? { width: topology.surface.width, height: topology.surface.height }
+      : renderExtentSize(topology.extent, 'internal');
   const buffers = importStandardClusterBuffers(graph, lighting);
   if (!buffers.ok) return buffers;
   const membership =
@@ -217,6 +234,28 @@ function buildStandardDeferredLane(
   if (!gbuffer2.ok) return gbuffer2;
   const scene = target(graph, 'hdrp-scene-color', { format: 'rgba16float', size: internalSize });
   if (!scene.ok) return scene;
+  const mediumTargets =
+    topology.singleLayerMedium === true
+      ? (() => {
+          const nearestLayer = target(graph, 'single-layer-medium-nearest-layer', {
+            format: scene.value.format,
+            size: internalSize,
+            // The color pass samples this target with a `texture_2d`; keep
+            // it single-sample even when a future deferred path is MSAA.
+            sampleCount: 1,
+            domain: 'linear-ldr',
+          });
+          if (!nearestLayer.ok) return nearestLayer;
+          const nearestDepth = target(graph, 'single-layer-medium-nearest-depth', {
+            format: 'depth24plus-stencil8',
+            size: internalSize,
+            sampleCount: 1,
+          });
+          if (!nearestDepth.ok) return nearestDepth;
+          return ok({ nearestLayer: nearestLayer.value, nearestDepth: nearestDepth.value });
+        })()
+      : ok(undefined);
+  if (!mediumTargets.ok) return mediumTargets;
   const reflectionFallback =
     topology.reflectionFallback?.enabled === true || topology.ssr?.status === 'admitted'
       ? target(graph, 'reflection-fallback-linear-hdr', {
@@ -270,6 +309,11 @@ function buildStandardDeferredLane(
     colorTargets: [gbuffer0.value, gbuffer1.value, gbuffer2.value],
     depth: depth.value,
     selector: { LightMode: ['Deferred'] },
+    // The G-buffer only admits opaque Standard materials. Medium Surface
+    // programs have no Deferred entry and acquire raw depth in their later
+    // paired color pass; filtering here also avoids assembling their bind
+    // groups before that producer exists.
+    recordMode: 'opaque',
     passKind: 'deferred',
     clearColor: [0, 0, 0, 0],
   });
@@ -301,6 +345,85 @@ function buildStandardDeferredLane(
     if (!skybox.ok) return skybox;
   }
 
+  const featureRasterWork =
+    context.hasFeatureRasterWork?.(CLOUD_LAYER_FEATURE_IDENTITY, 'scene') === true;
+  const cloudScene = featureRasterWork
+    ? target(graph, 'cloud-layer-scene-color', {
+        format: scene.value.format,
+        size: internalSize,
+        sampleCount: 1,
+        domain: 'linear-hdr',
+        usage:
+          GPU_TEXTURE_USAGE_COPY_SRC |
+          GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+          GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      })
+    : ok(undefined);
+  if (!cloudScene.ok) return cloudScene;
+  const cloudShadow =
+    featureRasterWork && context.cloudShadowResolution !== undefined
+      ? target(graph, 'cloud-layer-shadow', {
+          format: 'rgba16float',
+          size: {
+            width: context.cloudShadowResolution,
+            height: context.cloudShadowResolution,
+            depthOrArrayLayers: 1,
+          },
+          sampleCount: 1,
+          domain: 'linear-hdr',
+          usage:
+            GPU_TEXTURE_USAGE_COPY_SRC |
+            GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+            GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+        })
+      : ok(undefined);
+  if (!cloudShadow.ok) return cloudShadow;
+  const featureTargets = [
+    {
+      name: 'linear-hdr',
+      kind: 'scene-color',
+      texture: scene.value.texture,
+      view: scene.value.view,
+      format: scene.value.format,
+      sampleCount: 1,
+    },
+    {
+      kind: 'scene-depth',
+      texture: depth.value.texture,
+      view: depth.value.view,
+      format: depth.value.format,
+      sampleCount: 1,
+    },
+    ...(cloudShadow.value === undefined
+      ? []
+      : [
+          {
+            name: 'cloud-shadow',
+            kind: 'scene-color' as const,
+            texture: cloudShadow.value.texture,
+            view: cloudShadow.value.view,
+            format: cloudShadow.value.format,
+            sampleCount: 1 as const,
+          },
+        ]),
+    ...(context.cloudHistory === undefined
+      ? []
+      : renderPipelineCloudHistoryTargets(context.cloudHistory)),
+  ] as const;
+  // Cloud density and its spatial shadow must be produced before the opaque
+  // receiver pass. The composite is projected separately below, after the
+  // receiver has populated the scene target; declaration order is execution
+  // order for the typed graph.
+  const shadowFeatures = context.contributeFeatures(
+    featureTargets,
+    [],
+    cloudShadow.value === undefined ? {} : { 'cloud-shadow': cloudShadow.value },
+    [],
+    'scene',
+    ['cloud-layer-density-cache', 'cloud-layer-shadow'],
+  );
+  if (!shadowFeatures.ok) return shadowFeatures;
+
   // The lighting lane is the deferred Standard receiver. It deliberately
   // selects Forward passes for the same material handles that wrote the
   // G-buffer. Membership must not select the Deferred program/entries: those
@@ -329,14 +452,18 @@ function buildStandardDeferredLane(
       ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
       shadows.value.spot,
       ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+      ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
       ...(ssao === undefined ? [] : [ssao]),
     ],
     ...(shadows.value.directional === undefined
       ? {}
       : { directionalShadow: shadows.value.directional }),
     spotShadow: shadows.value.spot,
+    cloudShadow: cloudShadow.value,
     ...(ssao === undefined ? {} : { ssao }),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
+    ...(gpuDriven.value === undefined ? {} : { gpuDrivenFilter: 'deferred-opaque' as const }),
+    ...(topology.singleLayerMedium === true ? { recordMode: 'opaque' as const } : {}),
     passKind: 'forward',
     extraAccesses: buffers.value === null ? [] : standardClusterReadAccesses(buffers.value),
   });
@@ -359,7 +486,7 @@ function buildStandardDeferredLane(
     if (!coverage.ok) return coverage;
   }
 
-  const sceneOutput: RenderPipelineTarget = scene.value;
+  let sceneOutput: RenderPipelineTarget = scene.value;
   let secondaryReactivity: GraphTextureView | undefined;
   if (topology.ssr !== undefined) {
     const ssrView =
@@ -420,10 +547,18 @@ function buildStandardDeferredLane(
   }
 
   const transmissionDemand = transmissionDemandForTopology(topology);
+  const backdropDemand = {
+    activeCount: transmissionDemand.activeCount + (topology.singleLayerMedium === true ? 1 : 0),
+    needsRoughMips: transmissionDemand.needsRoughMips,
+  };
   const transmissionActive = resolveTransmissionBackdropTopology({
     demand: transmissionDemand,
     sourceSampleCount: scene.value.sampleCount,
   }).active;
+  const backdropActive = resolveTransmissionBackdropTopology({
+    demand: backdropDemand,
+    sourceSampleCount: scene.value.sampleCount,
+  }).active;
   const forwardExtraAccesses: GraphAccess[] =
     buffers.value === null ? [] : [...standardClusterReadAccesses(buffers.value)];
 
@@ -442,35 +577,158 @@ function buildStandardDeferredLane(
       ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
       shadows.value.spot,
       ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+      ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
       ...(ssao === undefined ? [] : [ssao]),
     ],
     ...(shadows.value.directional === undefined
       ? {}
       : { directionalShadow: shadows.value.directional }),
     spotShadow: shadows.value.spot,
+    cloudShadow: cloudShadow.value,
     ...(ssao === undefined ? {} : { ssao }),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
     passKind: 'forward',
     excludeSelector: { LightMode: ['Deferred'] },
-    ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
+    // Keep the deferred opaque lane separate from Surface medium passes.
+    recordMode: 'opaque' as const,
+    ...(gpuDriven.value === undefined ? {} : { gpuDrivenFilter: 'forward-only-opaque' as const }),
     ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
     extraAccesses: forwardExtraAccesses,
   });
   if (!forward.ok) return forward;
 
+  if (cloudScene.value !== undefined) {
+    const compositeFeatures = context.contributeFeatures(
+      featureTargets,
+      [],
+      {
+        'motion-input': scene.value,
+        'motion-output': cloudScene.value,
+        ...(cloudShadow.value === undefined ? {} : { 'cloud-shadow': cloudShadow.value }),
+        ...(context.cloudHistory === undefined
+          ? {}
+          : {
+              'cloud-history-radiance-current': context.cloudHistory.currentRadiance,
+              'cloud-history-radiance-previous': context.cloudHistory.previousRadiance,
+              'cloud-history-transmittance-current': context.cloudHistory.currentTransmittance,
+              'cloud-history-transmittance-previous': context.cloudHistory.previousTransmittance,
+              'cloud-history-depth-current': context.cloudHistory.currentDepth,
+              'cloud-history-depth-previous': context.cloudHistory.previousDepth,
+            }),
+      },
+      forwardExtraAccesses,
+      'scene',
+      // One half-resolution transport MRT produces radiance, transmittance and
+      // representative depth; the full-resolution resolve consumes that same
+      // frame and advances the ping-pong history on submit.
+      ['cloud-layer-transport', 'cloud-layer-resolve'],
+    );
+    if (!compositeFeatures.ok) return compositeFeatures;
+  }
+
+  if (cloudScene.value !== undefined) sceneOutput = cloudScene.value;
+
   const transmission = addTransmissionBackdropPasses({
     graph,
     source: sceneOutput,
-    demand: transmissionDemand,
-    copySize: { width: topology.surface.width, height: topology.surface.height },
+    demand: backdropDemand,
+    copySize: internalCopySize,
     encodeRoughMip: context.encodeTransmissionMip,
     includeConsumerPasses: false,
   });
   if (!transmission.ok) return transmission;
-  if (transmission.value.topology.active) {
-    const transmissionPass = addTypedScenePass(graph, {
+  if (topology.singleLayerMedium === true) {
+    const nearestTargets = mediumTargets.value;
+    const backdrop = transmission.value.backdrop?.view;
+    if (nearestTargets === undefined || backdrop === undefined) {
+      return err(
+        new RenderGraphError({
+          code: 'resource-descriptor-invalid',
+          expected: 'single-layer medium graph has nearest targets and an opaque backdrop',
+          hint: 'keep the shared transmission backdrop copy ahead of the Surface passes',
+          detail: {
+            resourceLabel: 'single-layer-medium',
+            field: 'backdrop',
+            expected: 'resolved graph texture view',
+            actual: 'missing',
+          },
+        }),
+      );
+    }
+    const rawDepth = addSingleLayerMediumRawDepthProducer({
+      graph,
+      sourceColor: sceneOutput,
+      sourceDepth: depth.value,
+      size: internalSize,
+    });
+    if (!rawDepth.ok) return rawDepth;
+    // Standard owns this producer fact. Deferred depth is single-sample, so
+    // the independent r32float copy is available to both medium passes.
+    const surfacePair: RenderPipelineSurfaceMediumPair = {
+      opaqueColor: backdrop,
+      rawDepth: { status: 'available', view: rawDepth.value.view },
+    };
+    const mediumPasses = addSingleLayerMediumPasses({
+      graph,
+      size: internalSize,
+      ...nearestTargets,
+      color: sceneOutput,
+      depth: depth.value,
+      sampled: [
+        gbuffer0.value,
+        gbuffer1.value,
+        gbuffer2.value,
+        ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
+        shadows.value.spot,
+        ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+        ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
+        ...(ssao === undefined ? [] : [ssao]),
+      ],
+      directionalShadow: shadows.value.directional,
+      spotShadow: shadows.value.spot,
+      cloudShadow: cloudShadow.value,
+      ssao,
+      extraAccesses: forwardExtraAccesses,
+      surfacePair,
+      ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
+    });
+    if (!mediumPasses.ok) return mediumPasses;
+  }
+  if (backdropActive) {
+    if (transmissionActive) {
+      const transmissionPass = addTypedScenePass(graph, {
+        environment: atmosphere.value,
+        name: 'transmission-forward',
+        color: sceneOutput,
+        depth: depth.value,
+        selector: { LightMode: ['Forward'] },
+        colorLoadOp: 'load',
+        depthLoadOp: 'load',
+        sampled: [
+          gbuffer0.value,
+          gbuffer1.value,
+          gbuffer2.value,
+          ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
+          shadows.value.spot,
+          ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+          ...(ssao === undefined ? [] : [ssao]),
+        ],
+        directionalShadow: shadows.value.directional,
+        spotShadow: shadows.value.spot,
+        ...(ssao === undefined ? {} : { ssao }),
+        passKind: 'forward',
+        recordMode: 'transmission',
+        // Inject the complete backdrop view so the Standard shader can select
+        // the producer's optional roughness mip level. mipViews[0] is only the
+        // copy destination view and intentionally exposes one level.
+        transmissionBackdrop: transmission.value.backdrop?.view,
+        extraAccesses: forwardExtraAccesses,
+      });
+      if (!transmissionPass.ok) return transmissionPass;
+    }
+    const transparentPass = addTypedScenePass(graph, {
       environment: atmosphere.value,
-      name: 'transmission-forward',
+      name: 'transparent',
       color: sceneOutput,
       depth: depth.value,
       selector: { LightMode: ['Forward'] },
@@ -483,21 +741,25 @@ function buildStandardDeferredLane(
         ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+        ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
         ...(ssao === undefined ? [] : [ssao]),
       ],
       directionalShadow: shadows.value.directional,
       spotShadow: shadows.value.spot,
+      cloudShadow: cloudShadow.value,
       ...(ssao === undefined ? {} : { ssao }),
       passKind: 'forward',
-      recordMode: 'transmission',
-      // Inject the complete backdrop view so the Standard shader can select
-      // the producer's optional roughness mip level. mipViews[0] is only the
-      // copy destination view and intentionally exposes one level.
-      transmissionBackdrop: transmission.value.backdrop?.view,
+      recordMode: 'transparent',
+      transparentDepthWrite: true,
       extraAccesses: forwardExtraAccesses,
     });
-    if (!transmissionPass.ok) return transmissionPass;
-
+    if (!transparentPass.ok) return transparentPass;
+  }
+  if (backdropActive) {
+    const temporal = addTransmissionBackdropTemporalPass(graph, sceneOutput);
+    if (!temporal.ok) return temporal;
+  }
+  if (!transmission.value.topology.active) {
     const transparentPass = addTypedScenePass(graph, {
       environment: atmosphere.value,
       name: 'transparent',
@@ -513,18 +775,19 @@ function buildStandardDeferredLane(
         ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+        ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
         ...(ssao === undefined ? [] : [ssao]),
       ],
       directionalShadow: shadows.value.directional,
       spotShadow: shadows.value.spot,
+      cloudShadow: cloudShadow.value,
       ...(ssao === undefined ? {} : { ssao }),
       passKind: 'forward',
       recordMode: 'transparent',
+      transparentDepthWrite: true,
       extraAccesses: forwardExtraAccesses,
     });
     if (!transparentPass.ok) return transparentPass;
-    const temporal = addTransmissionBackdropTemporalPass(graph, sceneOutput);
-    if (!temporal.ok) return temporal;
   }
   if (topology.volumetricFog?.enabled === true) {
     const depthSample = graph.view(depth.value.texture, {
@@ -541,11 +804,15 @@ function buildStandardDeferredLane(
       shadows.value.directional?.view,
       shadows.value.spot.view,
       buffers.value,
+      cloudShadow.value?.view,
     );
     if (!volume.ok) return volume;
   }
   // The volume-composite pass remains in linear HDR before tone mapping.
 
+  // Generic post features consume the final deferred scene target after cloud
+  // and volume producers. Keep the same clustered, shadow, and SSAO reads that
+  // the Standard receiver exposes to feature-owned lighting passes.
   const features = context.contributeFeatures(
     [
       {
@@ -561,18 +828,24 @@ function buildStandardDeferredLane(
         texture: depth.value.texture,
         view: depth.value.view,
         format: depth.value.format,
-        sampleCount: 1,
+        sampleCount: depth.value.sampleCount,
       },
     ],
     [],
     {},
     [
       ...forwardExtraAccesses,
-      ...[shadows.value.directional, shadows.value.spot, shadows.value.point].flatMap((target) =>
+      ...[
+        shadows.value.directional,
+        shadows.value.spot,
+        shadows.value.point,
+        cloudShadow.value,
+      ].flatMap((target) =>
         target === undefined ? [] : [{ resource: target.view, usage: 'sampled-read' as const }],
       ),
       ...(ssao === undefined ? [] : [{ resource: ssao.view, usage: 'sampled-read' as const }]),
     ],
+    { exclude: [BARREL_DISTORTION_FEATURE_IDENTITY] },
   );
   if (!features.ok) return features;
   const observation = addTypedFrameObservationPass(graph, sceneOutput, 'forgeax::standard');

package/src/pipeline/standard-post.ts

@@ -7,7 +7,11 @@ 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';
@@ -392,9 +396,22 @@ export function addStandardPost(
     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
@@ -410,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', {
@@ -514,23 +539,23 @@ export function addStandardPost(
   // 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(
@@ -543,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;
@@ -559,6 +590,9 @@ export function addStandardPost(
       const features = context.contributeFeatures(
         featureTargets,
         sceneTemporal === undefined ? [] : [sceneTemporal],
+        {},
+        [],
+        { exclude: [BARREL_DISTORTION_FEATURE_IDENTITY] },
       );
       if (!features.ok) return features;
     }
@@ -638,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
@@ -689,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
@@ -797,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;
   /**