@forgeax/engine-render 0.1.28 → 0.1.30

package/src/pipeline/standard-pipeline.ts

@@ -1,13 +1,17 @@
 import {
   type GraphAccess,
   type GraphTextureDescriptor,
+  type GraphTextureView,
   type RenderGraphBuilder,
   RenderGraphError,
 } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import { addAtmosphereBackground } from '../environment/background';
 import { SceneDataUnavailableError, StandardProfileInvalidError } from '../errors/render';
 import type { FramePlan } from '../extract/environment';
+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';
 import type {
   RenderPipeline,
   RenderPipelineBuildContext,
@@ -19,12 +23,15 @@ import {
   importRenderPipelineSurface,
   type RenderPipelineTarget,
 } from '../render-pipeline';
+import { addSsrCompositionPass } from '../ssr/compose';
+import { addSsrSpatialPasses } from '../ssr/graph';
 import {
   addStandardSceneDataPass,
   aggregateTemporalDemand,
   createStandardSceneDataTarget,
   standardTemporalLaneAdmission,
 } from '../temporal/standard-scene-data';
+import { addTargetCoveragePass } from '../temporal/target-coverage-attachment';
 import {
   addTransmissionBackdropPasses,
   addTransmissionBackdropTemporalPass,
@@ -32,14 +39,16 @@ import {
   transmissionDemandForTopology,
 } from '../transmission/backdrop';
 import {
+  addReflectionFallbackObservationPass,
   addTypedFrameObservationPass,
   addTypedScenePass,
   addTypedSkyboxPass,
   addTypedSsaoPasses,
-  typedFrameClearColor,
 } from '../typed-render-graph-primitives';
 import { addTypedShadowPasses } from '../typed-shadow-passes';
 import { addAuthoredVolumetricFogPasses } from '../volume/passes';
+import { renderExtentSize } from './render-extent';
+import type { StandardPipelineBuildContext } from './standard-build-context';
 import { buildStandardForwardLane } from './standard-forward-lane';
 import {
   addStandardClusterMembershipPass,
@@ -154,13 +163,15 @@ function target(
 }
 
 function buildStandardDeferredLane(
-  context: RenderPipelineBuildContext<RenderPipelineFrame>,
+  context: StandardPipelineBuildContext,
   topology: RenderPipelineTopology,
   lighting: StandardTopologyInputValue,
 ): ReturnType<RenderPipeline['build']> {
   const graph = context.graph;
   const surface = importRenderPipelineSurface(graph, topology);
   if (!surface.ok) return surface;
+  const internalSize =
+    topology.extent === undefined ? 'surface' : renderExtentSize(topology.extent, 'internal');
   const buffers = importStandardClusterBuffers(graph, lighting);
   if (!buffers.ok) return buffers;
   const membership =
@@ -168,34 +179,57 @@ function buildStandardDeferredLane(
       ? ok(undefined)
       : addStandardClusterMembershipPass(graph, lighting, buffers.value);
   if (!membership.ok) return membership;
-  const shadows = addTypedShadowPasses(graph, topology);
+  const featureShadows = context.contributeShadowFeatures?.();
+  if (featureShadows !== undefined && !featureShadows.ok) return featureShadows;
+  const shadows = addTypedShadowPasses(
+    graph,
+    topology,
+    context.projectGpuDrivenShadow,
+    featureShadows?.value,
+  );
   if (!shadows.ok) return shadows;
 
   const depth = target(graph, 'hdrp-depth', {
     format: 'depth24plus-stencil8',
-    size: 'surface',
+    size: internalSize,
   });
   if (!depth.ok) return depth;
+  const depthSample = graph.view(depth.value.texture, {
+    label: 'ssr-scene-depth',
+    dimension: '2d',
+    aspect: 'depth-only',
+  });
+  if (!depthSample.ok) return depthSample;
   const gbuffer0 = target(graph, 'gbuffer-normal-roughness', {
     format: DEFERRED_COLOR_FORMATS[0] ?? 'rgba16float',
-    size: 'surface',
+    size: internalSize,
   });
   if (!gbuffer0.ok) return gbuffer0;
   const gbuffer1 = target(graph, 'gbuffer-albedo-metallic', {
     format: DEFERRED_COLOR_FORMATS[1] ?? 'rgba8unorm',
-    size: 'surface',
+    size: internalSize,
   });
   if (!gbuffer1.ok) return gbuffer1;
-  const gbuffer2 = target(graph, 'gbuffer-emissive-ao', {
+  const gbuffer2 = target(graph, 'gbuffer-specular-response-ao', {
     format: DEFERRED_COLOR_FORMATS[2] ?? 'rgba16float',
-    size: 'surface',
+    size: internalSize,
   });
   if (!gbuffer2.ok) return gbuffer2;
-  const scene = target(graph, 'hdrp-scene-color', { format: 'rgba16float', size: 'surface' });
+  const scene = target(graph, 'hdrp-scene-color', { format: 'rgba16float', size: internalSize });
   if (!scene.ok) return scene;
+  const reflectionFallback =
+    topology.reflectionFallback?.enabled === true || topology.ssr?.status === 'admitted'
+      ? target(graph, 'reflection-fallback-linear-hdr', {
+          format: 'rgba16float',
+          size: internalSize,
+          domain: 'linear-hdr',
+        })
+      : ok(undefined);
+  if (!reflectionFallback.ok) return reflectionFallback;
   const temporalDemand = aggregateTemporalDemand({
     taa: topology.camera.antialias === 'taa',
     motionBlur: topology.temporal?.motionBlur === true,
+    ssr: topology.ssr?.status === 'admitted',
   });
   const temporalLane = topology.lane.compute ? 'clustered' : 'cpu-webgl2';
   const temporalAdmission = standardTemporalLaneAdmission({
@@ -223,6 +257,11 @@ function buildStandardDeferredLane(
   const gpuDriven = context.projectGpuDriven({
     format: scene.value.format,
     sampleCount: scene.value.sampleCount,
+    ...(reflectionFallback.value === undefined
+      ? {}
+      : {
+          additionalColorFormats: [reflectionFallback.value.format],
+        }),
   });
   if (!gpuDriven.ok) return gpuDriven;
   const gbuffer = addTypedScenePass(graph, {
@@ -252,33 +291,133 @@ function buildStandardDeferredLane(
     ssao = blurred.value;
   }
 
-  const lightingAccesses: GraphAccess[] = [
-    { resource: gbuffer0.value.view, usage: 'sampled-read' },
-    { resource: gbuffer1.value.view, usage: 'sampled-read' },
-    { resource: gbuffer2.value.view, usage: 'sampled-read' },
-    { resource: depth.value.view, usage: 'depth-stencil-read' },
-    ...(buffers.value === null ? [] : standardClusterReadAccesses(buffers.value)),
-    ...(ssao === undefined
-      ? []
-      : ([{ resource: ssao.view, usage: 'sampled-read' }] satisfies GraphAccess[])),
-    { resource: scene.value.view, usage: 'color-attachment' },
-  ];
-  const lightingPass = graph.addRasterPass('lighting', {
-    accesses: lightingAccesses,
-    colorAttachments: [
-      {
-        view: scene.value.view,
-        loadOp: 'clear',
-        storeOp: 'store',
-        clearValue: typedFrameClearColor,
-      },
+  // Initialize the background before receiver lighting. The skybox recorder
+  // has no depth attachment, so placing it later would cover lit geometry.
+  const atmosphere =
+    topology.atmosphere === true ? addAtmosphereBackground(graph, scene.value) : ok(undefined);
+  if (!atmosphere.ok) return atmosphere;
+  if (atmosphere.value === undefined) {
+    const skybox = addTypedSkyboxPass(graph, scene.value);
+    if (!skybox.ok) return skybox;
+  }
+
+  // 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
+  // output encoded geometry, not scene radiance. This keeps
+  // one material/BRDF owner while making the graph's LIGHT node executable;
+  // the later forward lane excludes these handles so SSR composition is not
+  // overwritten by a second draw.
+  const lightingPass = addTypedScenePass(graph, {
+    environment: atmosphere.value,
+    name: 'lighting',
+    color: scene.value,
+    colorTargets: [
+      scene.value,
+      ...(reflectionFallback.value === undefined ? [] : [reflectionFallback.value]),
     ],
-    encode: () => undefined,
+    depth: depth.value,
+    selector: { LightMode: ['Forward'] },
+    includeSelector: { LightMode: ['Deferred'] },
+    colorLoadOp: ['load', 'clear'],
+    clearColor: [0, 0, 0, 0],
+    depthLoadOp: 'clear',
+    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]),
+    ],
+    ...(shadows.value.directional === undefined
+      ? {}
+      : { directionalShadow: shadows.value.directional }),
+    spotShadow: shadows.value.spot,
+    ...(ssao === undefined ? {} : { ssao }),
+    ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
+    passKind: 'forward',
+    extraAccesses: buffers.value === null ? [] : standardClusterReadAccesses(buffers.value),
   });
   if (!lightingPass.ok) return lightingPass;
 
-  const skybox = addTypedSkyboxPass(graph, scene.value);
-  if (!skybox.ok) return skybox;
+  // SSR consumes the same Standard temporal-v1 producer as TAA and motion
+  // blur. Insert it before the spatial chain so the graph dependency order is
+  // explicit and one producer serves every temporal consumer.
+  const temporal =
+    temporalDemand.targetCount === 1
+      ? createStandardSceneDataTarget(graph, topology.extent)
+      : ok(undefined);
+  if (!temporal.ok) return temporal;
+  if (temporal.value !== undefined) {
+    const producer = addStandardSceneDataPass(graph, temporal.value.temporal, depth.value);
+    if (!producer.ok) return producer;
+  }
+  if (context.targetCoverage !== undefined) {
+    const coverage = addTargetCoveragePass(graph, context.targetCoverage);
+    if (!coverage.ok) return coverage;
+  }
+
+  const sceneOutput: RenderPipelineTarget = scene.value;
+  let secondaryReactivity: GraphTextureView | undefined;
+  if (topology.ssr !== undefined) {
+    const ssrView =
+      topology.ssr.status === 'admitted'
+        ? graph.importBuffer(
+            'ssr-view',
+            {
+              size: VIEW_UNIFORM_BYTES,
+              usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+            },
+            (frame) => frame.pipelineState.viewUniformBuffer,
+          )
+        : ok(undefined);
+    if (!ssrView.ok) return ssrView;
+    const spatial = addSsrSpatialPasses(graph, {
+      admission: topology.ssr,
+      width: topology.surface.width,
+      height: topology.surface.height,
+      depth: depthSample.value,
+      normal: gbuffer0.value.view,
+      scene: scene.value.view,
+      ...(temporal.value === undefined ? {} : { currentTemporal: temporal.value.temporal.view }),
+      ...(reflectionFallback.value === undefined
+        ? {}
+        : { fallback: reflectionFallback.value.view }),
+      ...(temporal.value === undefined || context.ssrHistory === undefined
+        ? {}
+        : {
+            temporal: {
+              previousHistory: context.ssrHistory.previous.view,
+              outputHistory: context.ssrHistory.output.view,
+              previousSurface: context.ssrHistory.previousSurface.view,
+              outputSurface: context.ssrHistory.outputSurface.view,
+              params: context.ssrHistory.params,
+            },
+          }),
+      ...(ssrView.value === undefined ? {} : { view: ssrView.value }),
+    });
+    if (!spatial.ok) return spatial;
+    if (
+      spatial.value.resources !== undefined &&
+      reflectionFallback.value !== undefined &&
+      ssrView.value !== undefined
+    ) {
+      secondaryReactivity = spatial.value.resources.hitReactivity;
+      const radiance =
+        spatial.value.resources.radiancePyramid ?? spatial.value.resources.trace.view;
+      const composed = addSsrCompositionPass(graph, {
+        scene: scene.value,
+        radiance,
+        fallback: reflectionFallback.value.view,
+        response: gbuffer2.value.view,
+        normal: gbuffer0.value.view,
+        view: ssrView.value,
+      });
+      if (!composed.ok) return composed;
+    }
+  }
 
   const transmissionDemand = transmissionDemandForTopology(topology);
   const transmissionActive = resolveTransmissionBackdropTopology({
@@ -289,12 +428,13 @@ function buildStandardDeferredLane(
     buffers.value === null ? [] : [...standardClusterReadAccesses(buffers.value)];
 
   const forward = addTypedScenePass(graph, {
+    environment: atmosphere.value,
     name: 'forward',
-    color: scene.value,
+    color: sceneOutput,
     depth: depth.value,
     selector: { LightMode: ['Forward'] },
     colorLoadOp: 'load',
-    depthLoadOp: 'clear',
+    depthLoadOp: 'load',
     sampled: [
       gbuffer0.value,
       gbuffer1.value,
@@ -311,22 +451,16 @@ function buildStandardDeferredLane(
     ...(ssao === undefined ? {} : { ssao }),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
     passKind: 'forward',
+    excludeSelector: { LightMode: ['Deferred'] },
     ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
     ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
     extraAccesses: forwardExtraAccesses,
   });
   if (!forward.ok) return forward;
 
-  const temporal =
-    temporalDemand.targetCount === 1 ? createStandardSceneDataTarget(graph) : ok(undefined);
-  if (!temporal.ok) return temporal;
-  if (temporal.value !== undefined) {
-    const producer = addStandardSceneDataPass(graph, temporal.value.temporal, depth.value);
-    if (!producer.ok) return producer;
-  }
   const transmission = addTransmissionBackdropPasses({
     graph,
-    source: scene.value,
+    source: sceneOutput,
     demand: transmissionDemand,
     copySize: { width: topology.surface.width, height: topology.surface.height },
     encodeRoughMip: context.encodeTransmissionMip,
@@ -335,8 +469,9 @@ function buildStandardDeferredLane(
   if (!transmission.ok) return transmission;
   if (transmission.value.topology.active) {
     const transmissionPass = addTypedScenePass(graph, {
+      environment: atmosphere.value,
       name: 'transmission-forward',
-      color: scene.value,
+      color: sceneOutput,
       depth: depth.value,
       selector: { LightMode: ['Forward'] },
       colorLoadOp: 'load',
@@ -364,8 +499,9 @@ function buildStandardDeferredLane(
     if (!transmissionPass.ok) return transmissionPass;
 
     const transparentPass = addTypedScenePass(graph, {
+      environment: atmosphere.value,
       name: 'transparent',
-      color: scene.value,
+      color: sceneOutput,
       depth: depth.value,
       selector: { LightMode: ['Forward'] },
       colorLoadOp: 'load',
@@ -387,7 +523,7 @@ function buildStandardDeferredLane(
       extraAccesses: forwardExtraAccesses,
     });
     if (!transparentPass.ok) return transparentPass;
-    const temporal = addTransmissionBackdropTemporalPass(graph, scene.value);
+    const temporal = addTransmissionBackdropTemporalPass(graph, sceneOutput);
     if (!temporal.ok) return temporal;
   }
   if (topology.volumetricFog?.enabled === true) {
@@ -400,7 +536,7 @@ function buildStandardDeferredLane(
     const volume = addAuthoredVolumetricFogPasses(
       graph,
       topology,
-      scene.value,
+      sceneOutput,
       depthSample.value,
       shadows.value.directional?.view,
       shadows.value.spot.view,
@@ -410,36 +546,57 @@ function buildStandardDeferredLane(
   }
   // The volume-composite pass remains in linear HDR before tone mapping.
 
-  const features = context.contributeFeatures([
-    {
-      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,
-    },
-  ]);
+  const features = context.contributeFeatures(
+    [
+      {
+        name: 'linear-hdr',
+        kind: 'scene-color',
+        texture: sceneOutput.texture,
+        view: sceneOutput.view,
+        format: sceneOutput.format,
+        sampleCount: sceneOutput.sampleCount,
+      },
+      {
+        kind: 'scene-depth',
+        texture: depth.value.texture,
+        view: depth.value.view,
+        format: depth.value.format,
+        sampleCount: 1,
+      },
+    ],
+    [],
+    {},
+    [
+      ...forwardExtraAccesses,
+      ...[shadows.value.directional, shadows.value.spot, shadows.value.point].flatMap((target) =>
+        target === undefined ? [] : [{ resource: target.view, usage: 'sampled-read' as const }],
+      ),
+      ...(ssao === undefined ? [] : [{ resource: ssao.view, usage: 'sampled-read' as const }]),
+    ],
+  );
   if (!features.ok) return features;
-  const observation = addTypedFrameObservationPass(graph, scene.value, 'forgeax::standard');
+  const observation = addTypedFrameObservationPass(graph, sceneOutput, 'forgeax::standard');
   if (!observation.ok) return observation;
+  if (reflectionFallback.value?.sampleCount === 1) {
+    const fallbackObservation = addReflectionFallbackObservationPass(
+      graph,
+      reflectionFallback.value,
+    );
+    if (!fallbackObservation.ok) return fallbackObservation;
+  }
   const post = addStandardPost(
     context,
     topology,
-    scene.value,
+    sceneOutput,
     depth.value,
     surface.value,
     temporal.value?.temporal,
+    secondaryReactivity,
+    context.targetCoverage?.coverage,
+    context.targetCoverage?.depth,
   );
   if (!post.ok) return post;
-  const cubeCaptures = context.contributeCubeCaptures?.();
+  const cubeCaptures = context.contributeCubeCaptures?.(atmosphere.value);
   if (cubeCaptures !== undefined && !cubeCaptures.ok) return cubeCaptures;
   return ok(undefined);
 }
@@ -501,7 +658,11 @@ function standardTopology(
 ): RenderPipelineTopology {
   const config = {
     ...(topology.config ?? {}),
-    ssao: { enabled: profile.ssao },
+    ssao: {
+      ...(topology.config?.ssao ?? {}),
+      ...(typeof profile.ssao === 'object' ? profile.ssao : {}),
+      enabled: profile.ssao !== false,
+    },
   };
   return {
     ...topology,
@@ -520,6 +681,7 @@ function buildStandard(
   context: RenderPipelineBuildContext<RenderPipelineFrame>,
   topology: RenderPipelineTopology,
 ): ReturnType<RenderPipeline['build']> {
+  const standardContext = context as StandardPipelineBuildContext;
   const profile = profileFor(topology);
   if (!STANDARD_LIGHT_COUNTS.some((count) => count === profile.lightCount)) {
     return err(
@@ -542,11 +704,11 @@ function buildStandard(
   // A missing Camera is an intentional clear-only frame. Keep it on the
   // forward raster lane so clustered resources cannot introduce work.
   if (effective.clearOnly === true) {
-    return buildStandardForwardLane(context, effective, lighting.value);
+    return buildStandardForwardLane(standardContext, effective, lighting.value);
   }
   return profile.renderPath === 'forward'
-    ? buildStandardForwardLane(context, effective, lighting.value)
-    : buildStandardDeferredLane(context, effective, lighting.value);
+    ? buildStandardForwardLane(standardContext, effective, lighting.value)
+    : buildStandardDeferredLane(standardContext, effective, lighting.value);
 }
 
 export const standardPipeline: StandardPipeline = Object.freeze({