@forgeax/engine-render 0.1.32 → 0.1.34

package/src/pipeline/standard-forward-lane.ts

@@ -1,11 +1,10 @@
-import type {
-  GraphTextureDescriptor,
-  RenderGraphBuilder,
-  RenderGraphError,
-} from '@forgeax/engine-render-graph';
+import type { GraphTextureDescriptor, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+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 } from '../errors/render';
+import { BARREL_DISTORTION_FEATURE_IDENTITY } from '../features/barrel-distortion';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
@@ -14,12 +13,14 @@ import {
 import type {
   RenderPipeline,
   RenderPipelineFrame,
+  RenderPipelineSurfaceMediumPair,
   RenderPipelineTopology,
 } from '../render-pipeline';
 import {
   createRenderPipelineTarget,
   importRenderPipelineSurface,
   type RenderPipelineTarget,
+  renderPipelineCloudHistoryTargets,
 } from '../render-pipeline';
 import {
   addStandardSceneDataPass,
@@ -43,6 +44,11 @@ import {
 import { addTypedShadowPasses } from '../typed-shadow-passes';
 import { addAuthoredVolumetricFogPasses } from '../volume/passes';
 import { renderExtentSize } from './render-extent';
+import {
+  addSingleLayerMediumMsaaPairProducer,
+  addSingleLayerMediumPasses,
+  addSingleLayerMediumRawDepthProducer,
+} from './single-layer-medium-passes';
 import type { StandardPipelineBuildContext } from './standard-build-context';
 import {
   addStandardClusterMembershipPass,
@@ -71,6 +77,10 @@ function buildUrp(
 
   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 clearOnly = topology.clearOnly === true;
   const msaa = !clearOnly && topology.camera.antialias === 'msaa' && topology.lane.multisample;
@@ -93,7 +103,7 @@ function buildUrp(
   });
   const needsTemporalIntermediate = temporalDemand.targetCount === 1;
   const sceneFormat =
-    hdr || linearLdr || rawOnly || needsTemporalIntermediate
+    hdr || linearLdr || rawOnly || needsTemporalIntermediate || topology.singleLayerMedium === true
       ? 'rgba16float'
       : topology.surface.storageFormat;
 
@@ -113,7 +123,13 @@ function buildUrp(
           domain: 'display-encoded',
         })
       : ok(surface.value.display)
-    : hdr || fxaa || linearLdr || msaa || rawOnly || needsTemporalIntermediate
+    : hdr ||
+        fxaa ||
+        linearLdr ||
+        msaa ||
+        rawOnly ||
+        needsTemporalIntermediate ||
+        topology.singleLayerMedium === true
       ? target(graph, 'scene-color', {
           format: sceneFormat,
           size: internalSize,
@@ -147,6 +163,27 @@ function buildUrp(
     : sceneResolved;
   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,
+            sampleCount: msaa ? 4 : 1,
+            domain: 'linear-ldr',
+          });
+          if (!nearestLayer.ok) return nearestLayer;
+          const nearestDepth = target(graph, 'single-layer-medium-nearest-depth', {
+            format: 'depth24plus-stencil8',
+            size: internalSize,
+            sampleCount: msaa ? 4 : 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
     ? target(graph, 'reflection-fallback-linear-hdr', {
         format: 'rgba16float',
@@ -214,10 +251,96 @@ function buildUrp(
   });
   if (!gpuDriven.ok) return gpuDriven;
   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 featureRasterWork =
+    context.hasFeatureRasterWork?.(CLOUD_LAYER_FEATURE_IDENTITY, 'scene') === true;
+  const cloudScene =
+    featureRasterWork && !msaa
+      ? target(graph, 'cloud-layer-scene-color', {
+          format: sceneResolved.value.format,
+          size: internalSize,
+          sampleCount: 1,
+          domain: hdr ? 'linear-hdr' : 'linear-ldr',
+          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: sceneResolved.value.texture,
+      view: sceneResolved.value.view,
+      format: sceneResolved.value.format,
+      sampleCount: 1,
+    },
+    {
+      kind: 'scene-depth',
+      texture: depth.value.texture,
+      view: depth.value.view,
+      format: depth.value.format,
+      sampleCount: depth.value.sampleCount,
+    },
+    ...(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;
+  // Produce the density cache and spatial receiver shadow before opaque
+  // shading. The cloud composite is a later scene pass, so it cannot be
+  // projected in this call without being overwritten by `main`.
+  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;
   const main = addTypedScenePass(graph, {
     environment: atmosphere.value,
     name: 'main',
@@ -231,20 +354,68 @@ function buildUrp(
       ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
       shadows.value.spot,
       ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+      ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
     ],
     ...(shadows.value.directional === undefined
       ? {}
       : { directionalShadow: shadows.value.directional }),
     spotShadow: shadows.value.spot,
+    cloudShadow: cloudShadow.value,
     selector: { LightMode: ['Forward'] },
     colorLoadOp: 'load',
     extraAccesses: clusterReads,
-    ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
+    // Opaque, transmission and ordinary transparency are separate queue
+    // segments. Keeping the opaque filter unconditional prevents an
+    // ordinary transparent material from being drawn before the cloud pass.
+    recordMode: 'opaque' as const,
+    ...(backdropActive && gpuDriven.value !== undefined
+      ? { gpuDrivenFilter: 'opaque' as const }
+      : {}),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
     ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
   });
   if (!main.ok) return main;
 
+  const opaqueMediumPair =
+    topology.singleLayerMedium === true && msaa
+      ? addSingleLayerMediumMsaaPairProducer({
+          graph,
+          label: 'single-layer-medium-opaque-resolve',
+          sourceColor: scene.value,
+          sourceDepth: depth.value,
+          size: internalSize,
+        })
+      : ok(undefined);
+  if (!opaqueMediumPair.ok) return opaqueMediumPair;
+  if (cloudScene.value !== undefined) {
+    const compositeFeatures = context.contributeFeatures(
+      featureTargets,
+      [],
+      {
+        'motion-input': sceneResolved.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,
+            }),
+      },
+      [],
+      '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;
+  }
+
   const temporalLane = topology.lane.compute ? 'clustered' : 'cpu-webgl2';
   const temporalAdmission = standardTemporalLaneAdmission({
     lane: temporalLane,
@@ -284,62 +455,135 @@ function buildUrp(
     if (!coverage.ok) return coverage;
   }
 
+  let sceneForLater: RenderPipelineTarget = scene.value;
+  let sceneResolvedForLater: RenderPipelineTarget = sceneResolved.value;
+  if (cloudScene.value !== undefined) {
+    sceneForLater = cloudScene.value;
+    sceneResolvedForLater = cloudScene.value;
+  }
+
   const transmission = addTransmissionBackdropPasses({
     graph,
-    source: sceneResolved.value,
-    demand: transmissionDemand,
-    copySize: { width: topology.surface.width, height: topology.surface.height },
+    source: sceneResolvedForLater,
+    demand: backdropDemand,
+    copySize: internalCopySize,
     encodeRoughMip: context.encodeTransmissionMip,
     includeConsumerPasses: false,
   });
   if (!transmission.ok) return transmission;
-  if (transmission.value.topology.active) {
-    const transmissionPass = addTypedScenePass(graph, {
-      environment: atmosphere.value,
-      name: 'transmission-forward',
-      color: scene.value,
-      depth: depth.value,
-      ...(msaa ? { resolve: sceneResolved.value } : {}),
-      sampled: [
-        ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
-        shadows.value.spot,
-        ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
-      ],
-      directionalShadow: shadows.value.directional,
-      spotShadow: shadows.value.spot,
-      selector: { LightMode: ['Forward'] },
-      colorLoadOp: 'load',
-      depthLoadOp: 'load',
-      recordMode: 'transmission',
-      extraAccesses: clusterReads,
-      // 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,
-    });
-    if (!transmissionPass.ok) return transmissionPass;
-
-    const transparentPass = addTypedScenePass(graph, {
-      environment: atmosphere.value,
-      name: 'transparent',
-      color: scene.value,
+  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',
+          },
+        }),
+      );
+    }
+    let rawDepthTarget: RenderPipelineTarget | undefined = opaqueMediumPair.value?.depth;
+    if (rawDepthTarget === undefined) {
+      const rawDepth = addSingleLayerMediumRawDepthProducer({
+        graph,
+        sourceColor: sceneResolvedForLater,
+        sourceDepth: depth.value,
+        size: internalSize,
+      });
+      if (!rawDepth.ok) return rawDepth;
+      rawDepthTarget = rawDepth.value;
+    }
+    const surfacePair: RenderPipelineSurfaceMediumPair = {
+      opaqueColor: opaqueMediumPair.value?.color.view ?? backdrop,
+      rawDepth:
+        rawDepthTarget === undefined
+          ? { status: 'unavailable', reason: 'depth-copy-unavailable' }
+          : { status: 'available', view: rawDepthTarget.view },
+    };
+    const mediumPasses = addSingleLayerMediumPasses({
+      graph,
+      size: internalSize,
+      ...nearestTargets,
+      color: sceneForLater,
+      ...(msaa ? { colorResolve: sceneResolvedForLater } : {}),
       depth: depth.value,
-      ...(msaa ? { resolve: sceneResolved.value } : {}),
       sampled: [
         ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+        ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
       ],
       directionalShadow: shadows.value.directional,
       spotShadow: shadows.value.spot,
-      selector: { LightMode: ['Forward'] },
-      colorLoadOp: 'load',
-      depthLoadOp: 'load',
-      recordMode: 'transparent',
+      cloudShadow: cloudShadow.value,
       extraAccesses: clusterReads,
+      surfacePair,
+      ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
     });
-    if (!transparentPass.ok) return transparentPass;
-    const temporal = addTransmissionBackdropTemporalPass(graph, sceneResolved.value);
+    if (!mediumPasses.ok) return mediumPasses;
+  }
+  if (backdropActive) {
+    if (transmissionActive) {
+      const transmissionPass = addTypedScenePass(graph, {
+        environment: atmosphere.value,
+        name: 'transmission-forward',
+        color: sceneForLater,
+        depth: depth.value,
+        ...(msaa ? { resolve: sceneResolvedForLater } : {}),
+        sampled: [
+          ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
+          shadows.value.spot,
+          ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+          ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
+        ],
+        directionalShadow: shadows.value.directional,
+        spotShadow: shadows.value.spot,
+        cloudShadow: cloudShadow.value,
+        selector: { LightMode: ['Forward'] },
+        colorLoadOp: 'load',
+        depthLoadOp: 'load',
+        recordMode: 'transmission',
+        extraAccesses: clusterReads,
+        // 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,
+      });
+      if (!transmissionPass.ok) return transmissionPass;
+    }
+  }
+  const transparentPass = addTypedScenePass(graph, {
+    environment: atmosphere.value,
+    name: 'transparent',
+    color: sceneForLater,
+    depth: depth.value,
+    ...(msaa ? { resolve: sceneResolvedForLater } : {}),
+    sampled: [
+      ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
+      shadows.value.spot,
+      ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+      ...(cloudShadow.value === undefined ? [] : [cloudShadow.value]),
+    ],
+    directionalShadow: shadows.value.directional,
+    spotShadow: shadows.value.spot,
+    cloudShadow: cloudShadow.value,
+    selector: { LightMode: ['Forward'] },
+    colorLoadOp: 'load',
+    depthLoadOp: 'load',
+    recordMode: 'transparent',
+    transparentDepthWrite: true,
+    extraAccesses: clusterReads,
+  });
+  if (!transparentPass.ok) return transparentPass;
+  if (backdropActive) {
+    const temporal = addTransmissionBackdropTemporalPass(graph, sceneResolvedForLater);
     if (!temporal.ok) return temporal;
   }
 
@@ -353,25 +597,31 @@ function buildUrp(
     const volume = addAuthoredVolumetricFogPasses(
       graph,
       topology,
-      sceneResolved.value,
+      sceneResolvedForLater,
       depthSample.value,
       shadows.value.directional?.view,
       shadows.value.spot.view,
       clusterBuffers.value,
+      cloudShadow.value?.view,
     );
     if (!volume.ok) return volume;
   }
 
+  // Project the remaining generic post features after every scene producer has
+  // finished. The forward lane may have replaced the scene target with the
+  // cloud-resolved target; keep the MSAA resolve target paired with that final
+  // color target so feature attachments observe the same surface that the
+  // Standard observation reads.
   const features = context.contributeFeatures(
     [
       {
         name: 'linear-hdr',
         kind: 'scene-color',
-        texture: scene.value.texture,
-        view: scene.value.view,
-        ...(msaa ? { resolveTarget: sceneResolved.value.view } : {}),
-        format: scene.value.format,
-        sampleCount: scene.value.sampleCount,
+        texture: sceneForLater.texture,
+        view: sceneForLater.view,
+        ...(msaa ? { resolveTarget: sceneResolvedForLater.view } : {}),
+        format: sceneForLater.format,
+        sampleCount: sceneForLater.sampleCount,
       },
       {
         kind: 'scene-depth',
@@ -385,17 +635,23 @@ function buildUrp(
     {},
     [
       ...clusterReads,
-      ...[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 }],
       ),
     ],
+    { exclude: [BARREL_DISTORTION_FEATURE_IDENTITY] },
   );
   if (!features.ok) return features;
 
   if (hdr || linearLdr || rawOnly) {
     const observation = addTypedFrameObservationPass(
       graph,
-      sceneResolved.value,
+      sceneResolvedForLater,
       'forgeax::standard',
     );
     if (!observation.ok) return observation;
@@ -411,7 +667,7 @@ function buildUrp(
   const post = addStandardPost(
     context,
     topology,
-    sceneResolved.value,
+    sceneResolvedForLater,
     depth.value,
     surface.value,
     temporal.value?.temporal,

package/src/pipeline/standard-output/graph.ts

@@ -31,6 +31,7 @@ function requestedStages(input: StandardOutputRequest): StandardOutputLogicalSta
   if (input.exposure || input.whiteBalance) stages.push('exposure-white-balance');
   stages.push('tone');
   if (input.lut) stages.push('lut');
+  if (input.barrelDistortion === true) stages.push('barrel-distortion');
   if (input.fxaa) stages.push('fxaa');
   stages.push('output-encoding');
   return stages;
@@ -50,6 +51,7 @@ function physicalStages(
       case 'tone':
         return { name, input: LINEAR_HDR_DOMAIN, output: LINEAR_LDR_DOMAIN };
       case 'lut':
+      case 'barrel-distortion':
       case 'fxaa':
         return { name, input: LINEAR_LDR_DOMAIN, output: LINEAR_LDR_DOMAIN };
       case 'output-encoding':
@@ -62,8 +64,11 @@ function physicalStages(
 
 export function createStandardOutputPlan(input: StandardOutputRequest): StandardOutputPlan {
   const logicalStages = requestedStages(input);
-  const incrementalResources = input.lut ? ['standard-color-lut'] : [];
-  const incrementalBindings = input.lut ? 2 : 0;
+  const incrementalResources = [
+    ...(input.lut ? ['standard-color-lut'] : []),
+    ...(input.barrelDistortion === true ? ['standard-barrel-distortion'] : []),
+  ];
+  const incrementalBindings = (input.lut ? 2 : 0) + (input.barrelDistortion === true ? 3 : 0);
   return {
     lane: input.lane,
     features: {
@@ -74,6 +79,7 @@ export function createStandardOutputPlan(input: StandardOutputRequest): Standard
       exposure: input.exposure,
       whiteBalance: input.whiteBalance,
       lut: input.lut,
+      barrelDistortion: input.barrelDistortion === true,
       fxaa: input.fxaa,
     },
     outputEncoding: input.outputEncoding,

package/src/pipeline/standard-output/types.ts

@@ -8,6 +8,7 @@ export const STANDARD_OUTPUT_LOGICAL_STAGES = [
   'exposure-white-balance',
   'tone',
   'lut',
+  'barrel-distortion',
   'fxaa',
   'output-encoding',
 ] as const;
@@ -32,6 +33,8 @@ export interface StandardOutputRequest {
   readonly exposure: boolean;
   readonly whiteBalance: boolean;
   readonly lut: boolean;
+  /** Output-space barrel warp; runs after LUT in linear-LDR. */
+  readonly barrelDistortion?: boolean;
   readonly fxaa: boolean;
   readonly outputEncoding: StandardOutputEncoding;
 }
@@ -47,7 +50,15 @@ export interface StandardOutputPlan {
   readonly features: Readonly<
     Pick<
       StandardOutputRequest,
-      'temporal' | 'meter' | 'bloom' | 'dof' | 'exposure' | 'whiteBalance' | 'lut' | 'fxaa'
+      | 'temporal'
+      | 'meter'
+      | 'bloom'
+      | 'dof'
+      | 'exposure'
+      | 'whiteBalance'
+      | 'lut'
+      | 'barrelDistortion'
+      | 'fxaa'
     >
   >;
   readonly outputEncoding: StandardOutputEncoding;