@forgeax/engine-render 0.1.33 → 0.1.34

package/src/pbr-pipeline.ts

@@ -350,6 +350,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 +626,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 +679,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 +1022,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,
@@ -1185,13 +1274,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 +1525,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 +1534,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 +1542,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 },
+          },
         ],
       };
     }
@@ -1504,9 +1660,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 +1683,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 +1800,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);
+}