@forgeax/engine-render 0.1.2

package/src/typed-shadow-passes.ts

@@ -0,0 +1,195 @@
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import { PointShadowAtlasUninitializedError } from './errors/render';
+import {
+  directionalCascadeAtlasSize,
+  directionalCascadeRasterViewport,
+} from './extract/directional-csm';
+import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING } from './gpu-texture-usage';
+import {
+  encodeDirectionalShadowPass,
+  encodePointShadowPass,
+  encodeSpotShadowPass,
+} from './record/shadow-pass';
+import type {
+  RenderPipelineFrame,
+  RenderPipelineGpuDrivenShadowProjection,
+  RenderPipelineTopology,
+} from './render-pipeline';
+import type { _InternalRenderPipelineContext } from './render-pipeline-context';
+import { createRenderPipelineTarget, type RenderPipelineTarget } from './render-pipeline-target';
+
+export interface TypedShadowTargets {
+  readonly directional: RenderPipelineTarget;
+  readonly spot: RenderPipelineTarget;
+  readonly point?: RenderPipelineTarget | undefined;
+}
+
+function addShadowPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  name: string,
+  target: RenderPipelineTarget,
+  loadOp: 'clear' | 'load',
+  encode: Parameters<RenderGraphBuilder<RenderPipelineFrame>['addRasterPass']>[1]['encode'],
+  executeIf?: (frame: RenderPipelineFrame) => boolean,
+  extraAccesses: readonly import('@forgeax/engine-render-graph').GraphAccess[] = [],
+): Result<void, RenderGraphError> {
+  return graph.addRasterPass(name, {
+    accesses: [{ resource: target.view, usage: 'depth-stencil-write' }, ...extraAccesses],
+    colorAttachments: [],
+    depthStencilAttachment: {
+      view: target.view,
+      depthLoadOp: loadOp,
+      depthStoreOp: 'store',
+      ...(loadOp === 'clear' ? { depthClearValue: 1 } : {}),
+    },
+    ...(executeIf === undefined ? {} : { executeIf }),
+    encode,
+  });
+}
+
+export function addTypedShadowPasses(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  topology: RenderPipelineTopology,
+  gpuDrivenShadow: readonly RenderPipelineGpuDrivenShadowProjection[] = [],
+): Result<TypedShadowTargets, RenderGraphError> {
+  const rasterViewports = Array.from({ length: topology.shadow.cascadeCount }, (_, cascade) =>
+    directionalCascadeRasterViewport(
+      cascade,
+      topology.shadow.cascadeCount,
+      topology.shadow.mapSize,
+    ),
+  );
+  const atlasSize = directionalCascadeAtlasSize(
+    topology.shadow.cascadeCount,
+    topology.shadow.mapSize,
+  );
+  const directional = createRenderPipelineTarget(graph, 'directional-shadow-depth', {
+    format: 'depth32float',
+    size: atlasSize,
+  });
+  if (!directional.ok) return directional;
+  const resetDirectionalAtlas = addShadowPass(
+    graph,
+    'directional-shadow-reset',
+    directional.value,
+    'clear',
+    () => {},
+    // Keep a stable, inspectable topology name for capture/debug consumers.
+    // The independent legacy shadow encoder owns the cache-aware atlas clear;
+    // opening this declarative graph pass would add a second depth pass.
+    () => false,
+  );
+  if (!resetDirectionalAtlas.ok) return resetDirectionalAtlas;
+  for (let cascade = 0; cascade < topology.shadow.cascadeCount; cascade += 1) {
+    const rasterViewport = rasterViewports[cascade];
+    if (rasterViewport === undefined) throw new RangeError('directional cascade viewport missing');
+    const gpuShadow = gpuDrivenShadow.find((candidate) => candidate.cascadeIndex === cascade);
+    const added = addShadowPass(
+      graph,
+      `shadowCascade${cascade}`,
+      directional.value,
+      cascade === 0 ? 'clear' : 'load',
+      ({ pass, frame, resources }) =>
+        encodeDirectionalShadowPass(
+          frame as never,
+          pass,
+          cascade,
+          rasterViewport,
+          gpuShadow === undefined ? undefined : { projection: gpuShadow, resources },
+        ),
+      (frame) => !(frame as _InternalRenderPipelineContext).directionalShadowCacheReuse,
+      gpuShadow?.accesses,
+    );
+    if (!added.ok) return added;
+  }
+  const observation = graph.addCopyPass('directional-shadow-observation', {
+    accesses: [{ resource: directional.value.view, usage: 'copy-src' }],
+    encode: ({ frame, resources }) => {
+      const texture = resources.texture(directional.value.texture);
+      if (!texture.ok) throw texture.error;
+      frame.pipelineState.perPassResources.shadowTexture = texture.value;
+    },
+  });
+  if (!observation.ok) return observation;
+
+  let point: RenderPipelineTarget | undefined;
+  if (topology.shadow.pointCount > 0) {
+    const texture = graph.importTexture(
+      'point-shadow-atlas',
+      {
+        format: 'depth32float',
+        size: {
+          width: topology.shadow.pointFaceSize,
+          height: topology.shadow.pointFaceSize,
+          depthOrArrayLayers: 24,
+        },
+        usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING,
+      },
+      (frame) => {
+        const atlas = frame.frameState.pointShadowAtlas?.getTexture();
+        if (atlas === null || atlas === undefined) {
+          throw new PointShadowAtlasUninitializedError();
+        }
+        return atlas;
+      },
+    );
+    if (!texture.ok) return texture;
+    const cube = graph.view(texture.value, {
+      label: 'point-shadow-atlas.cube-array',
+      dimension: 'cube-array',
+      aspect: 'depth-only',
+      arrayLayerCount: 24,
+    });
+    if (!cube.ok) return cube;
+    point = {
+      texture: texture.value,
+      view: cube.value,
+      format: 'depth32float',
+      sampleCount: 1,
+    };
+    for (let pointIndex = 0; pointIndex < topology.shadow.pointCount; pointIndex += 1) {
+      for (let face = 0; face < 6; face += 1) {
+        const faceView = graph.view(texture.value, {
+          label: `point-shadow-${pointIndex}-${face}`,
+          dimension: '2d',
+          aspect: 'depth-only',
+          baseArrayLayer: pointIndex * 6 + face,
+          arrayLayerCount: 1,
+        });
+        if (!faceView.ok) return faceView;
+        const added = addShadowPass(
+          graph,
+          `point-shadow-${pointIndex}-${face}`,
+          {
+            texture: texture.value,
+            view: faceView.value,
+            format: 'depth32float',
+            sampleCount: 1,
+          },
+          'clear',
+          ({ pass, frame }) => encodePointShadowPass(frame as never, pass, pointIndex, face),
+        );
+        if (!added.ok) return added;
+      }
+    }
+  }
+
+  const spot = createRenderPipelineTarget(graph, 'spot-shadow-depth', {
+    format: 'depth32float',
+    size: { width: topology.shadow.mapSize * 2, height: topology.shadow.mapSize * 2 },
+  });
+  if (!spot.ok) return spot;
+  for (let spotIndex = 0; spotIndex < Math.max(1, topology.shadow.spotCount); spotIndex += 1) {
+    const added = addShadowPass(
+      graph,
+      topology.shadow.spotCount === 0 ? 'spot-shadow' : `spot-shadow-${spotIndex}`,
+      spot.value,
+      spotIndex === 0 ? 'clear' : 'load',
+      ({ pass, frame }) => encodeSpotShadowPass(frame as never, pass, spotIndex),
+    );
+    if (!added.ok) return added;
+  }
+
+  return ok({ directional: directional.value, spot: spot.value, point });
+}

package/src/urp-pipeline.ts

@@ -0,0 +1,340 @@
+import type {
+  GraphTextureDescriptor,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import { addTypedDebugOverlayPass } from './debug-draw-glue';
+import {
+  addEnvironmentCompositionPass,
+  addEnvironmentProducerPasses,
+  environmentGenerationEnabled,
+} from './environment/graph';
+import {
+  addSceneTemporalRasterPass,
+  createSceneTemporalDepthTarget,
+  createSceneTemporalTarget,
+} from './features/scene-temporal';
+import type {
+  RenderPipeline,
+  RenderPipelineBuildContext,
+  RenderPipelineFrame,
+  RenderPipelineTopology,
+} from './render-pipeline';
+import {
+  createRenderPipelineTarget,
+  importRenderPipelineSurface,
+  type RenderPipelineTarget,
+} from './render-pipeline-target';
+import {
+  addTypedBloomPasses,
+  addTypedCompositePostEffects,
+  addTypedFrameObservationPass,
+  addTypedFullscreenPass,
+  addTypedScenePass,
+  addTypedSkyboxPass,
+  addTypedTonemapPass,
+} from './typed-render-graph-primitives';
+import { addTypedShadowPasses } from './typed-shadow-passes';
+
+export const URP_PIPELINE_ID: 'forgeax::urp' = 'forgeax::urp';
+
+function target(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  label: string,
+  descriptor: GraphTextureDescriptor,
+): Result<RenderPipelineTarget, RenderGraphError> {
+  return createRenderPipelineTarget(graph, label, descriptor);
+}
+
+function buildUrp(
+  context: RenderPipelineBuildContext<RenderPipelineFrame>,
+  topology: RenderPipelineTopology,
+): ReturnType<RenderPipeline['build']> {
+  const graph = context.graph;
+  const surface = importRenderPipelineSurface(graph, topology);
+  if (!surface.ok) return surface;
+
+  const msaa = topology.camera.antialias === 'msaa' && topology.lane.multisample;
+  const hdr = topology.camera.tonemap !== 'none';
+  const fxaa = topology.camera.antialias === 'fxaa';
+  const taa = topology.camera.antialias === 'taa';
+  const linearLdr = !hdr && (topology.lane.storageBuffer || taa);
+  const sceneFormat = hdr || linearLdr ? 'rgba16float' : topology.surface.storageFormat;
+
+  const depth = target(graph, 'scene-depth', {
+    format: 'depth24plus-stencil8',
+    size: 'surface',
+    sampleCount: msaa ? 4 : 1,
+  });
+  if (!depth.ok) return depth;
+  const sceneResolved =
+    hdr || fxaa || linearLdr || msaa
+      ? target(graph, 'scene-color', {
+          format: sceneFormat,
+          size: 'surface',
+          sampleCount: 1,
+          ...(sceneFormat === topology.surface.storageFormat &&
+          topology.surface.storageFormat !== topology.surface.viewFormat
+            ? { viewFormats: [topology.surface.viewFormat] }
+            : {}),
+        })
+      : ok(surface.value.display);
+  if (!sceneResolved.ok) return sceneResolved;
+  const scene = msaa
+    ? target(graph, 'scene-color-msaa', {
+        format: sceneFormat,
+        size: 'surface',
+        sampleCount: 4,
+        ...(sceneFormat === topology.surface.storageFormat &&
+        topology.surface.storageFormat !== topology.surface.viewFormat
+          ? { viewFormats: [topology.surface.viewFormat] }
+          : {}),
+      })
+    : sceneResolved;
+  if (!scene.ok) return scene;
+  const temporal = taa ? createSceneTemporalTarget(graph) : ok(undefined);
+  if (!temporal.ok) return temporal;
+  const temporalDepth = taa ? createSceneTemporalDepthTarget(graph) : ok(undefined);
+  if (!temporalDepth.ok) return temporalDepth;
+
+  const gpuDriven = context.projectGpuDriven({
+    format: scene.value.format,
+    sampleCount: scene.value.sampleCount,
+  });
+  if (!gpuDriven.ok) return gpuDriven;
+  // GPU visibility must be declared before the directional shadow raster
+  // passes so the graph establishes compute -> depth ordering for the same
+  // four-view indirect contract. The main scene pass consumes the projection
+  // returned here below; calling the context a second time would otherwise
+  // hide the projection behind its once-per-build guard.
+  const shadows = addTypedShadowPasses(graph, topology, gpuDriven.value?.shadow);
+  if (!shadows.ok) return shadows;
+  if (topology.environment?.dirty === true) {
+    const environmentProducer = addEnvironmentProducerPasses(
+      graph,
+      scene.value,
+      'urp',
+      () => true,
+      context.environment?.targets,
+    );
+    if (!environmentProducer.ok) return environmentProducer;
+  }
+  if (topology.environment?.enabled === true) {
+    const environmentDepthClear = graph.addRasterPass('urp.environment-depth-clear', {
+      accesses: [{ resource: depth.value.view, usage: 'depth-stencil-write' }],
+      colorAttachments: [],
+      depthStencilAttachment: {
+        view: depth.value.view,
+        depthClearValue: 1,
+        depthLoadOp: 'clear',
+        depthStoreOp: 'store',
+        stencilClearValue: 0,
+        stencilLoadOp: 'clear',
+        stencilStoreOp: 'store',
+      },
+      executeIf: environmentGenerationEnabled,
+      encode: () => undefined,
+    });
+    if (!environmentDepthClear.ok) return environmentDepthClear;
+    const environmentBackground = addEnvironmentCompositionPass(
+      graph,
+      scene.value,
+      'urp.environment-background',
+      environmentGenerationEnabled,
+      {
+        clear: true,
+        sampled: context.environment?.sampledSky,
+        depth: depth.value.view,
+        sunDisc: false,
+      },
+    );
+    if (!environmentBackground.ok) return environmentBackground;
+    const sunDisc = addEnvironmentCompositionPass(
+      graph,
+      scene.value,
+      'urp.sun-disc',
+      environmentGenerationEnabled,
+      { sampled: context.environment?.sampledSky, depth: depth.value.view, sunDisc: true },
+    );
+    if (!sunDisc.ok) return sunDisc;
+  }
+  // Analytic environment owns the scene background. The legacy skybox pass
+  // clears the same target before its optional draw, so keeping it in this
+  // lane would erase the generated atmosphere on every frame.
+  if (topology.environment?.enabled !== true) {
+    const skybox = addTypedSkyboxPass(graph, scene.value);
+    if (!skybox.ok) return skybox;
+  }
+  // scene-radiance-fog-opaque-fragment: the existing Forward scene raster
+  // writes linear HDR and each built-in fragment producer applies the shared
+  // forgeax_view::fog module exactly once. This is an in-fragment operation,
+  // not a graph pass, target, resource, or history owner.
+  const main = addTypedScenePass(graph, {
+    name: 'main',
+    color: scene.value,
+    depth: depth.value,
+    ...(msaa ? { resolve: sceneResolved.value } : {}),
+    sampled: [
+      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',
+    ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
+  });
+  if (!main.ok) return main;
+
+  const sceneFeatureTarget = {
+    kind: 'scene-color' as const,
+    texture: scene.value.texture,
+    view: scene.value.view,
+    ...(msaa ? { resolveTarget: sceneResolved.value.view } : {}),
+    format: scene.value.format,
+    sampleCount: scene.value.sampleCount,
+  };
+  const depthFeatureTarget = {
+    kind: 'scene-depth' as const,
+    texture: depth.value.texture,
+    view: depth.value.view,
+    format: depth.value.format,
+    sampleCount: depth.value.sampleCount,
+  };
+  const temporalFeatureTarget =
+    temporal.value === undefined
+      ? undefined
+      : {
+          kind: 'scene-temporal' as const,
+          texture: temporal.value.texture,
+          view: temporal.value.view,
+          format: temporal.value.format,
+          sampleCount: 1 as const,
+        };
+  if (temporal.value !== undefined && temporalDepth.value !== undefined) {
+    const temporalRaster = addSceneTemporalRasterPass(graph, {
+      target: temporal.value,
+      depth: temporalDepth.value,
+      sampled: [
+        shadows.value.directional,
+        shadows.value.spot,
+        ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
+      ],
+      directionalShadow: shadows.value.directional,
+      spotShadow: shadows.value.spot,
+    });
+    if (!temporalRaster.ok) return temporalRaster;
+  }
+  const features = context.contributeFeatures([
+    sceneFeatureTarget,
+    depthFeatureTarget,
+    ...(temporalFeatureTarget === undefined ? [] : [temporalFeatureTarget]),
+  ]);
+  if (!features.ok) return features;
+  const temporalResolve = context.resolveTemporal({
+    sceneColor: {
+      kind: 'scene-color',
+      ...sceneResolved.value,
+    },
+    sceneDepth: depthFeatureTarget,
+    ...(temporalFeatureTarget === undefined ? {} : { sceneTemporal: temporalFeatureTarget }),
+  });
+  if (!temporalResolve.ok) return temporalResolve;
+  const resolvedScene = temporalResolve.value?.resolvedColor ?? sceneResolved.value;
+
+  if (hdr || linearLdr) {
+    const observation = addTypedFrameObservationPass(graph, resolvedScene, URP_PIPELINE_ID);
+    if (!observation.ok) return observation;
+  }
+
+  let postInput = resolvedScene;
+  if (hdr) {
+    const composited = target(graph, 'bloom-composited', {
+      format: 'rgba16float',
+      size: 'surface',
+    });
+    if (!composited.ok) return composited;
+    const bright = target(graph, 'bloom-bright', {
+      format: 'rgba16float',
+      size: 'half-surface',
+    });
+    if (!bright.ok) return bright;
+    const blurH = target(graph, 'bloom-blur-h', {
+      format: 'rgba16float',
+      size: 'half-surface',
+    });
+    if (!blurH.ok) return blurH;
+    const blurV = target(graph, 'bloom-blur-v', {
+      format: 'rgba16float',
+      size: 'half-surface',
+    });
+    if (!blurV.ok) return blurV;
+    const bloom = addTypedBloomPasses(graph, {
+      scene: resolvedScene,
+      composited: composited.value,
+      bright: bright.value,
+      blurH: blurH.value,
+      blurV: blurV.value,
+    });
+    if (!bloom.ok) return bloom;
+    postInput = topology.camera.bloom === 'on' ? composited.value : resolvedScene;
+  }
+
+  if (hdr) {
+    if (fxaa) {
+      const ldr = target(graph, 'ldr-color', {
+        format: topology.surface.storageFormat,
+        size: 'surface',
+        ...(topology.surface.storageFormat === topology.surface.viewFormat
+          ? {}
+          : { viewFormats: [topology.surface.viewFormat] }),
+      });
+      if (!ldr.ok) return ldr;
+      const tonemap = addTypedTonemapPass(graph, postInput, ldr.value);
+      if (!tonemap.ok) return tonemap;
+      const aa = addTypedFullscreenPass(graph, {
+        name: 'fxaa',
+        shader: 'fxaa',
+        input: ldr.value,
+        output: surface.value.storage,
+      });
+      if (!aa.ok) return aa;
+    } else {
+      const tonemap = addTypedTonemapPass(graph, postInput, surface.value.display);
+      if (!tonemap.ok) return tonemap;
+    }
+  } else if (fxaa) {
+    const aa = addTypedFullscreenPass(graph, {
+      name: 'fxaa',
+      shader: 'fxaa',
+      input: resolvedScene,
+      output: surface.value.storage,
+    });
+    if (!aa.ok) return aa;
+  } else if (linearLdr) {
+    const output = addTypedTonemapPass(graph, resolvedScene, surface.value.storage, true);
+    if (!output.ok) return output;
+  }
+
+  const postEffects = topology.config?.postEffects ?? [];
+  if (topology.lane.storageBuffer && postEffects.length > 0) {
+    const effects = addTypedCompositePostEffects(
+      graph,
+      postEffects,
+      surface.value.display,
+      surface.value.storage,
+      depth.value,
+      topology.surface,
+    );
+    if (!effects.ok) return effects;
+  }
+
+  const debug = addTypedDebugOverlayPass(graph, surface.value.display);
+  if (!debug.ok) return debug;
+
+  return ok(undefined);
+}
+
+export const urpPipeline: RenderPipeline = { build: buildUrp };