@forgeax/engine-render 0.1.33 → 0.1.35

package/src/pbr-pipeline.ts

@@ -6,7 +6,7 @@
 //     material BGL grows from the derived user region by appending the 7
 //     Skylight resources via `mergeSkylightIntoMaterialBgl`. The
 //     unlit pipeline keeps its 7-entry material BGL (no Skylight binding
-//     7..13 contamination) so unlit demos don't carry IBL state.
+//     7..12 contamination) so unlit demos don't carry IBL state.
 //   - charter P4: same pipeline layout shape drives Skylight present +
 //     absent paths -- AI users do not branch on Skylight existence.
 //   - feat-20260520-skylight-ibl-cubemap M4 / t59 (round-4): the
@@ -209,8 +209,8 @@ export function buildPbrMaterialUserRegionEntries(
 //                (group(0) bindings 3..7); this kind is the seam for
 //                each per-material shadow override surface a future feat
 //                wires onto group(1).
-//   - 'ibl'      the 7 IBL / Skylight entries (irradiance / prefilter
-//                cube + brdfLut 2d + 3 samplers + intensity uniform).
+//   - 'ibl'      the 6 IBL / Skylight entries (irradiance / prefilter
+//                cube + brdfLut 2d + 2 samplers + intensity uniform).
 //                Used by `buildPbrPipelineLayouts` after the user-region
 //                user paramSchema entries are emitted.
 //   - 'lightmap' the 4 emissive + occlusion entries (sampler + texture
@@ -224,7 +224,7 @@ export function buildPbrMaterialUserRegionEntries(
 //                placeholders because their shaders do not read these slots.
 export type InjectionKind = keyof typeof INJECTION_KIND_LENGTHS;
 
-const IBL_INJECTION_LENGTH = 7;
+const IBL_INJECTION_LENGTH = 6;
 const LIGHTMAP_INJECTION_LENGTH = 4;
 const SHADOW_INJECTION_LENGTH = 2;
 const TRANSMISSION_INJECTION_LENGTH = 2;
@@ -283,16 +283,10 @@ export function appendInjection(
           visibility: GPU_SHADER_STAGE_FRAGMENT,
           texture: { sampleType: 'float', viewDimension: '2d' },
         },
-        // binding start+5: brdfLutSampler
+        // binding start+5: uniform { intensity: f32 }
         {
           binding: start + 5,
           visibility: GPU_SHADER_STAGE_FRAGMENT,
-          sampler: { type: 'filtering' },
-        },
-        // binding start+6: uniform { intensity: f32 }
-        {
-          binding: start + 6,
-          visibility: GPU_SHADER_STAGE_FRAGMENT,
           buffer: { type: 'uniform' },
         },
       ];
@@ -350,6 +344,51 @@ export function appendInjection(
   }
 }
 
+/**
+ * Append the renderer-owned inputs required by the Engine single-layer
+ * medium template. They intentionally live after the normal IBL and
+ * transmission injections so authored parameter schemas remain the only
+ * source of the prefix. The raw-depth texture is an r32float producer
+ * resource and therefore uses the unfilterable-float/non-filtering pair.
+ */
+export function appendSingleLayerMediumInjection(
+  bgl: readonly GPUBindGroupLayoutEntry[],
+): GPUBindGroupLayoutEntry[] {
+  const start = bgl.length;
+  return [
+    {
+      binding: start,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      sampler: { type: 'non-filtering' },
+    },
+    {
+      binding: start + 1,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    },
+    {
+      binding: start + 2,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      sampler: { type: 'filtering' },
+    },
+    {
+      binding: start + 3,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: 'float', viewDimension: '2d' },
+    },
+    {
+      binding: start + 4,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      sampler: { type: 'non-filtering' },
+    },
+    {
+      binding: start + 5,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    },
+  ];
+}
+
 // Closed-set length sentinels — the map is the membership owner.
 export const INJECTION_KIND_LENGTHS = {
   shadow: SHADOW_INJECTION_LENGTH,
@@ -581,6 +620,7 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
     },
   ];
   const extendedLighting = caps.extendedLighting ?? true;
+  const lowLimitCloudBindings = extendedLighting === false && caps.projectorAvailable === false;
   if (extendedLighting) {
     entries.push(
       {
@@ -633,6 +673,23 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
     visibility: GPU_SHADER_STAGE_VERTEX,
     buffer: { type: 'uniform', hasDynamicOffset: true },
   });
+  // Cloud direct-solar transport is a renderer-owned view resource. The
+  // minimum 16-texture profile has no spare sampled texture lane; its shader
+  // variant returns the direct-sun fallback without declaring this pair.
+  if (!lowLimitCloudBindings) {
+    entries.push(
+      {
+        binding: 16,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d' },
+      },
+      {
+        binding: 17,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' },
+      },
+    );
+  }
   return entries;
 }
 
@@ -959,6 +1016,32 @@ export function buildGpuDrivenPbrInstancesBindGroupLayout(
   return result.value;
 }
 
+/**
+ * Build the slot-3 layout used by direct single-layer-medium draws.
+ *
+ * Direct Surface draws retain their ordinary instance transforms at binding
+ * zero, but consume the same producer-owned ProbeBlend, dynamic page, frame
+ * rows, and shared time resources as the scene-index lane. Binding six is the
+ * per-draw frame-row base; it keeps a local instance index independent from
+ * the renderer's compact scene-index address.
+ */
+export function buildSurfaceDirectInstancesBindGroupLayout(
+  device: PbrPipelineDevice,
+  caps: PbrCaps,
+): BindGroupLayout {
+  if (!caps.storageBuffer) {
+    throw new Error('Direct Surface instances layout requires storage-buffer capability');
+  }
+  const result = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: 'pbr-surface-direct-instances',
+      caps,
+    }),
+  );
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
 /** Build the four-slot rigid scene-index pipeline layout. */
 export function buildGpuDrivenPbrPipelineLayout(
   device: PbrPipelineDevice,
@@ -1030,13 +1113,13 @@ export function pbrSkinMeshDynamicOffsets(
 
 /**
  * Build a stand-alone 7-entry unlit material BGL. Round-4 D-5 keeps unlit
- * material BG isolated from Skylight binding 7..13 -- unlit demos do not
+ * material BG isolated from Skylight binding 7..12 -- unlit demos do not
  * pay for IBL state. The unlit pipeline still binds material at slot 1,
  * just with a 7-entry layout.
  *
  * Note: at the moment the runtime still routes both unlit + standard
  * through a single 14-entry pipeline layout; the unlit material BG
- * carries fallback identity resources at binding 7..13. This factory is
+ * carries fallback identity resources at binding 7..12. This factory is
  * exported as a future-proof seam for the moment when unlit demos own
  * their own pipeline layout (t57 (e) test pins the contract today so the
  * eventual split has a green target).
@@ -1152,7 +1235,7 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *
  * Three groups by derivation source:
  * 1. Shader-derived (paramSchema reflection + injection chain):
- *    - `'pbr-material-merged'` — derived user region + Skylight 7 + transmission 2
+ *    - `'pbr-material-merged'` — derived user region + Skylight 6 + transmission 2
  *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
  *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
  * 2. Caps-driven literal shapes (no shader):
@@ -1185,13 +1268,15 @@ export type BglKind =
   | 'pbr-mesh-array'
   | 'pbr-instances'
   | 'pbr-gpu-driven-instances'
+  | 'pbr-surface-direct-instances'
   | 'pbr-skin-mesh-array'
   | 'unlit-material'
   | 'hdrp-7-slot'
   | 'fullscreen-post'
   | 'fullscreen-post-with-params'
   | 'fullscreen-post-with-scene-depth'
-  | 'fullscreen-post-with-scene-depth-msaa';
+  | 'fullscreen-post-with-scene-depth-msaa'
+  | 'fullscreen-post-with-paired-msaa';
 
 /**
  * Output shape of {@link buildBindGroupLayoutDescriptor}: matches the RHI
@@ -1434,7 +1519,7 @@ export function buildBindGroupLayoutDescriptor(
         entries: [
           {
             binding: 0,
-            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+            visibility: GPU_SHADER_STAGE_VERTEX,
             buffer: { type: meshBufType, hasDynamicOffset: false },
           },
           {
@@ -1443,7 +1528,7 @@ export function buildBindGroupLayoutDescriptor(
             // the shared visible bind group can serve both the Standard PBR
             // (binding(2)) and depth-only shadow (binding(1)) consumers.
             binding: 1,
-            visibility: GPU_SHADER_STAGE_VERTEX,
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
             buffer: { type: meshBufType, hasDynamicOffset: false },
           },
           {
@@ -1451,6 +1536,71 @@ export function buildBindGroupLayoutDescriptor(
             visibility: GPU_SHADER_STAGE_VERTEX,
             buffer: { type: meshBufType, hasDynamicOffset: false },
           },
+          {
+            // Generic Surface dynamic pages are read by authored Surface
+            // accessors. The binding is present for every scene-index group
+            // so Standard and custom Surface batches share one owner shape.
+            binding: 3,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: meshBufType, hasDynamicOffset: false },
+          },
+          {
+            // Frame time, explicit event ranges, and paired background/depth
+            // facts use separate read-only pages. This keeps live state out
+            // of the material row and leaves skin's address lane untouched.
+            binding: 4,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: meshBufType, hasDynamicOffset: false },
+          },
+          {
+            // Frame time is one frame-global fact. Keeping it outside the
+            // member row prevents a stable frame from issuing one 4-byte
+            // queue write for every visible Surface member.
+            binding: 5,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: 'uniform', hasDynamicOffset: false },
+          },
+        ],
+      };
+    }
+    case 'pbr-surface-direct-instances': {
+      return {
+        label: 'pbr-surface-direct-instances-bgl',
+        entries: [
+          {
+            binding: 0,
+            // Direct instance transforms are consumed only by vs_main. Keep
+            // them out of the fragment-stage storage budget; Surface already
+            // needs the retained ProbeBlend/page/frame records there and the
+            // portable WebGPU limit is eight storage buffers per stage.
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+          },
+          {
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: true },
+          },
+          {
+            binding: 3,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+          },
+          {
+            binding: 4,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+          },
+          {
+            binding: 5,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: 'uniform', hasDynamicOffset: false },
+          },
+          {
+            binding: 6,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: 'uniform', hasDynamicOffset: false },
+          },
         ],
       };
     }
@@ -1482,11 +1632,11 @@ export function buildBindGroupLayoutDescriptor(
     }
     case 'pbr-material-merged': {
       // Material BGL: per-shader user-region (derive(paramSchema).bglEntries)
-      // + IBL injection (7) + transmission injection (2). The user-region
+      // + IBL injection (6) + transmission injection (2). The user-region
       // size is the only variable; injection start = userRegion.length so a
       // custom schema shifts IBL/transmission by its sampler/texture pairs.
-      // The built-in standard-PBR schema is 17 + 7 + 2 = 26 entries;
-      // clearcoat texture pairs are derived from the effective root schema.
+      // The built-in standard-PBR user region has 15 entries;
+      // scene rows follow injection, and physical texture pairs follow the effective root schema.
       //
       // Schema source priority (D-1): explicit materialParamSchema option >
       // registry lookup of spec.shader.id > built-in standard-PBR fallback.
@@ -1504,9 +1654,18 @@ export function buildBindGroupLayoutDescriptor(
       const userRegion = buildPbrMaterialUserRegionEntries(userRegionSchema);
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
       const afterTransmission = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const engineRegion =
+        options.caps?.transmissionBackdrop === false &&
+        spec.shader.id !== 'forgeax::single-layer-medium'
+          ? afterIbl
+          : afterTransmission;
+      const afterSurfaceMedium =
+        spec.shader.id === 'forgeax::single-layer-medium'
+          ? [...engineRegion, ...appendSingleLayerMediumInjection(engineRegion)]
+          : engineRegion;
       const merged = [
-        ...(options.caps?.transmissionBackdrop === false ? afterIbl : afterTransmission),
-        ...appendTextureInjection(afterTransmission, physicalFields),
+        ...afterSurfaceMedium,
+        ...appendTextureInjection(afterSurfaceMedium, physicalFields),
       ];
       // Scene-index Standard variants consume one producer-owned material row
       // after the complete fixed physical range.  Keeping it at binding 46
@@ -1518,16 +1677,21 @@ export function buildBindGroupLayoutDescriptor(
           buffer: { type: 'read-only-storage', hasDynamicOffset: false },
         });
       }
+      const entries = [
+        ...merged,
+        ...(spec.shader.id === 'forgeax::single-layer-medium'
+          ? []
+          : [
+              {
+                binding: 47,
+                visibility: GPU_SHADER_STAGE_FRAGMENT,
+                texture: { sampleType: 'float' as const, viewDimension: 'cube' as const },
+              },
+            ]),
+      ];
       return {
         label: 'pbr-material-skylight-bgl',
-        entries: [
-          ...merged,
-          {
-            binding: 47,
-            visibility: GPU_SHADER_STAGE_FRAGMENT,
-            texture: { sampleType: 'float', viewDimension: 'cube' },
-          },
-        ],
+        entries,
       };
     }
     case 'unlit-material': {
@@ -1630,6 +1794,42 @@ export function buildBindGroupLayoutDescriptor(
         ],
       };
     }
+    case 'fullscreen-post-with-paired-msaa': {
+      return {
+        label: 'fullscreen-post-with-paired-msaa-bgl',
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            texture: {
+              sampleType: 'unfilterable-float',
+              viewDimension: '2d',
+              multisampled: true,
+            },
+          },
+          {
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            sampler: { type: 'filtering' },
+          },
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: 'uniform' },
+          },
+          {
+            binding: 3,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            texture: { sampleType: 'depth', viewDimension: '2d', multisampled: true },
+          },
+          {
+            binding: 4,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            sampler: { type: 'non-filtering' },
+          },
+        ],
+      };
+    }
   }
 }
 

package/src/pipeline/single-layer-medium-passes.ts

@@ -0,0 +1,267 @@
+import {
+  type GraphAccess,
+  type GraphTextureDescriptor,
+  type RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type {
+  RenderPipelineFrame,
+  RenderPipelineGpuDrivenProjection,
+  RenderPipelineSurfaceMediumPair,
+  RenderPipelineTarget,
+} from '../render-pipeline';
+import { createRenderPipelineTarget } from '../render-pipeline';
+import { addTypedFullscreenPass, addTypedScenePass } from '../typed-render-graph-primitives';
+
+/** Stable renderer-owned post-process identity for the independent depth copy. */
+export const SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID =
+  'forgeax.single-layer-medium-raw-depth' as const;
+export const SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID =
+  'forgeax.single-layer-medium-msaa-paired-color' as const;
+export const SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID =
+  'forgeax.single-layer-medium-msaa-raw-depth' as const;
+
+export interface SingleLayerMediumMsaaPair {
+  readonly color: RenderPipelineTarget;
+  readonly depth: RenderPipelineTarget;
+}
+
+export interface SingleLayerMediumRawDepthProducerInput {
+  readonly graph: RenderGraphBuilder<RenderPipelineFrame>;
+  /** Resource/pass prefix; defaults to the opaque scene producer identity. */
+  readonly label?: string | undefined;
+  /** The already-resolved opaque color keeps the fullscreen primitive's input ABI complete. */
+  readonly sourceColor: RenderPipelineTarget;
+  /** The opaque depth pass output. It is sampled only by the copy producer. */
+  readonly sourceDepth: RenderPipelineTarget;
+  /** Must match the Standard scene depth extent (surface or internal resolution). */
+  readonly size: GraphTextureDescriptor['size'];
+}
+
+/**
+ * Produce an independent, single-sample raw-depth texture for Surface media.
+ *
+ * The graph source is the completed opaque depth pass and the destination is
+ * an r32float color target. This intermediate is the only place that samples
+ * the hardware depth view; medium materials bind the independent result while
+ * writing the scene depth attachment. MSAA is rejected at the producer seam
+ * until the backend has an explicit depth resolve policy.
+ */
+export function addSingleLayerMediumRawDepthProducer(
+  input: SingleLayerMediumRawDepthProducerInput,
+): Result<RenderPipelineTarget, RenderGraphError> {
+  const label = input.label ?? 'single-layer-medium-raw-depth';
+  if (input.sourceDepth.sampleCount !== 1) {
+    return err(
+      new RenderGraphError({
+        code: 'resource-descriptor-invalid',
+        expected: 'single-layer medium raw-depth producer has a single-sample source depth',
+        hint: 'select a resolved 1x depth producer; MSAA depth resolve is not admitted yet',
+        detail: {
+          resourceLabel: label,
+          field: 'sourceDepth.sampleCount',
+          expected: '1',
+          actual: String(input.sourceDepth.sampleCount),
+        },
+      }),
+    );
+  }
+
+  const rawDepth = createRenderPipelineTarget(input.graph, label, {
+    format: 'r32float',
+    size: input.size,
+    sampleCount: 1,
+  });
+  if (!rawDepth.ok) return rawDepth;
+
+  const producer = addTypedFullscreenPass(input.graph, {
+    name: `${label}-producer`,
+    shader: SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+    input: input.sourceColor,
+    output: rawDepth.value,
+    depth: input.sourceDepth,
+  });
+  if (!producer.ok) return producer;
+  return ok(rawDepth.value);
+}
+
+/**
+ * Resolve a four-sample color/depth pair by selecting the nearest depth sample
+ * and the color at that exact sample index. This is deliberately separate
+ * from WebGPU's averaging color resolve, which cannot preserve the opaque or
+ * nearest-water sample associated with the selected depth.
+ */
+export function addSingleLayerMediumMsaaPairProducer(input: {
+  readonly graph: RenderGraphBuilder<RenderPipelineFrame>;
+  readonly label: string;
+  readonly sourceColor: RenderPipelineTarget;
+  readonly sourceDepth: RenderPipelineTarget;
+  readonly size: GraphTextureDescriptor['size'];
+}): Result<SingleLayerMediumMsaaPair, RenderGraphError> {
+  if (input.sourceColor.sampleCount !== 4 || input.sourceDepth.sampleCount !== 4) {
+    return err(
+      new RenderGraphError({
+        code: 'resource-descriptor-invalid',
+        expected: 'single-layer medium paired MSAA producer has 4x color and depth inputs',
+        hint: 'route 1x inputs through the single-sample raw-depth producer',
+        detail: {
+          resourceLabel: input.label,
+          field: 'source.sampleCount',
+          expected: 'color=4,depth=4',
+          actual: `color=${input.sourceColor.sampleCount},depth=${input.sourceDepth.sampleCount}`,
+        },
+      }),
+    );
+  }
+  const color = createRenderPipelineTarget(input.graph, `${input.label}-color`, {
+    format: input.sourceColor.format,
+    size: input.size,
+    sampleCount: 1,
+    ...(input.sourceColor.domain === undefined ? {} : { domain: input.sourceColor.domain }),
+  });
+  if (!color.ok) return color;
+  const depth = createRenderPipelineTarget(input.graph, `${input.label}-depth`, {
+    format: 'r32float',
+    size: input.size,
+    sampleCount: 1,
+  });
+  if (!depth.ok) return depth;
+  const colorProducer = addTypedFullscreenPass(input.graph, {
+    name: `${input.label}-color-producer`,
+    shader: SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID,
+    input: input.sourceColor,
+    output: color.value,
+    depth: input.sourceDepth,
+  });
+  if (!colorProducer.ok) return colorProducer;
+  const depthProducer = addTypedFullscreenPass(input.graph, {
+    name: `${input.label}-depth-producer`,
+    shader: SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID,
+    input: input.sourceColor,
+    output: depth.value,
+    depth: input.sourceDepth,
+  });
+  if (!depthProducer.ok) return depthProducer;
+  return ok({ color: color.value, depth: depth.value });
+}
+
+/** Inputs shared by the two graph passes owned by the Surface model. */
+export interface SingleLayerMediumPassInput {
+  readonly graph: RenderGraphBuilder<RenderPipelineFrame>;
+  readonly size: GraphTextureDescriptor['size'];
+  readonly nearestLayer: RenderPipelineTarget;
+  readonly nearestDepth: RenderPipelineTarget;
+  readonly color: RenderPipelineTarget;
+  readonly colorResolve?: RenderPipelineTarget | undefined;
+  readonly depth: RenderPipelineTarget;
+  readonly sampled?: readonly RenderPipelineTarget[] | undefined;
+  readonly directionalShadow?: RenderPipelineTarget | undefined;
+  readonly spotShadow?: RenderPipelineTarget | undefined;
+  /** Optional producer-owned cloud shadow bound through the Standard frame group. */
+  readonly cloudShadow?: RenderPipelineTarget | undefined;
+  readonly ssao?: RenderPipelineTarget | undefined;
+  readonly extraAccesses?: readonly GraphAccess[] | undefined;
+  /** Producer-owned pair of opaque color and sampled raw-depth facts. */
+  readonly surfacePair: RenderPipelineSurfaceMediumPair;
+  readonly gpuDriven?: RenderPipelineGpuDrivenProjection | undefined;
+}
+
+/**
+ * Admit the nearest-layer and color Surface submissions to the existing
+ * Standard graph only when the producer supplied a paired sampled raw depth.
+ * The pair is deliberately an input: this helper does not invent a backdrop,
+ * copy depth, or turn an unavailable fact into a graph resource.
+ */
+export function addSingleLayerMediumPasses(
+  input: SingleLayerMediumPassInput,
+): Result<void, RenderGraphError> {
+  const pair = input.surfacePair;
+  if (pair.rawDepth.status === 'unavailable') {
+    return err(
+      new RenderGraphError({
+        code: 'resource-descriptor-invalid',
+        expected: 'single-layer medium consumes a graph-paired sampled raw depth',
+        hint: 'enable an owner-approved depth-copy producer before admitting the Surface passes',
+        detail: {
+          resourceLabel: 'single-layer-medium',
+          field: 'surfacePair.rawDepth',
+          expected: 'available sampled depth view',
+          actual: pair.rawDepth.reason,
+        },
+      }),
+    );
+  }
+  const sampled = input.sampled ?? [];
+  const nearest = addTypedScenePass(input.graph, {
+    name: 'single-layer-medium-nearest-layer',
+    color: input.nearestLayer,
+    depth: input.nearestDepth,
+    sampled,
+    ...(input.directionalShadow === undefined
+      ? {}
+      : { directionalShadow: input.directionalShadow }),
+    ...(input.spotShadow === undefined ? {} : { spotShadow: input.spotShadow }),
+    ...(input.cloudShadow === undefined ? {} : { cloudShadow: input.cloudShadow }),
+    ...(input.ssao === undefined ? {} : { ssao: input.ssao }),
+    selector: { LightMode: ['Forward'] },
+    colorLoadOp: 'clear',
+    depthLoadOp: 'clear',
+    recordMode: 'single-layer-medium-nearest-layer',
+    transmissionBackdrop: pair.opaqueColor,
+    surfacePair: pair,
+    gpuDrivenFilter: 'single-layer-medium',
+    ...(input.extraAccesses === undefined ? {} : { extraAccesses: input.extraAccesses }),
+    ...(input.gpuDriven === undefined ? {} : { gpuDriven: input.gpuDriven }),
+  });
+  if (!nearest.ok) return nearest;
+
+  const nearestPair =
+    input.nearestLayer.sampleCount === 4
+      ? addSingleLayerMediumMsaaPairProducer({
+          graph: input.graph,
+          label: 'single-layer-medium-nearest-resolve',
+          sourceColor: input.nearestLayer,
+          sourceDepth: input.nearestDepth,
+          size: input.size,
+        })
+      : (() => {
+          const depth = addSingleLayerMediumRawDepthProducer({
+            graph: input.graph,
+            label: 'single-layer-medium-nearest-depth-sampled',
+            sourceColor: input.nearestLayer,
+            sourceDepth: input.nearestDepth,
+            size: input.size,
+          });
+          return depth.ok ? ok({ color: input.nearestLayer, depth: depth.value }) : depth;
+        })();
+  if (!nearestPair.ok) return nearestPair;
+
+  const colorSampled = [...sampled, nearestPair.value.color];
+  const color = addTypedScenePass(input.graph, {
+    name: 'single-layer-medium-color',
+    color: input.color,
+    ...(input.colorResolve === undefined ? {} : { resolve: input.colorResolve }),
+    depth: input.depth,
+    sampled: colorSampled,
+    ...(input.directionalShadow === undefined
+      ? {}
+      : { directionalShadow: input.directionalShadow }),
+    ...(input.spotShadow === undefined ? {} : { spotShadow: input.spotShadow }),
+    ...(input.cloudShadow === undefined ? {} : { cloudShadow: input.cloudShadow }),
+    ...(input.ssao === undefined ? {} : { ssao: input.ssao }),
+    selector: { LightMode: ['Forward'] },
+    colorLoadOp: 'load',
+    depthLoadOp: 'load',
+    recordMode: 'single-layer-medium-color',
+    transmissionBackdrop: pair.opaqueColor,
+    surfacePair: pair,
+    surfaceNearestLayer: nearestPair.value.color.view,
+    surfaceNearestDepth: nearestPair.value.depth.view,
+    gpuDrivenFilter: 'single-layer-medium',
+    ...(input.extraAccesses === undefined ? {} : { extraAccesses: input.extraAccesses }),
+    ...(input.gpuDriven === undefined ? {} : { gpuDriven: input.gpuDriven }),
+  });
+  if (!color.ok) return color;
+  return ok(undefined);
+}