@forgeax/engine-render 0.1.2

package/src/render-pipeline.ts

@@ -0,0 +1,343 @@
+// @forgeax/engine-render - typed render-pipeline topology contract.
+//
+// `RenderPipeline` is the registrable / installable / hot-swappable unit that owns
+// the per-frame render-graph topology. The engine's own standard forward pipeline
+// (`forgeax::urp`) implements this same interface and is driven through
+// the same public registerPipeline / installPipeline channel a user would use
+// (dogfood hard constraint, requirements M1 item 6).
+//
+// Naming note (requirements line 155): `RenderPipeline` here is the forgeax engine
+// concept name. The RHI GPU `RenderPipeline` handle (`@forgeax/engine-rhi`) is a
+// separate, internal opaque-handle type distinguished by module path (AGENTS.md RHI
+// form rules - "opaque handles distinguished by module path"); it is not exposed to
+// AI users. Files importing both alias the RHI one locally.
+//
+// Pipelines declare topology once through a typed builder. The renderer compiles,
+// executes, retires, finishes, and submits the resulting graph.
+
+import type {
+  ColorValueDomain,
+  GraphAccess,
+  GraphResourceResolver,
+  GraphTexture,
+  GraphTextureView,
+  RenderGraphBuilder,
+  RenderGraphError,
+  RenderGraphFrame,
+} from '@forgeax/engine-render-graph';
+import type { BindGroup, RhiError, RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { Tonemap } from './components/camera';
+import type { EnvironmentGraphTargets } from './environment/graph';
+import {
+  type RenderError,
+  TaaCapsInsufficientError,
+  TemporalUnsupportedError,
+} from './errors/render';
+import type { RenderFeatureTargetKind } from './features/targets';
+import type { PostProcessError } from './post-process-errors';
+import type { RenderPipelineContext } from './render-pipeline-context';
+
+export type { RenderPipelineContext } from './render-pipeline-context';
+
+export type RenderColorDomain = 'linearHdr' | 'linearLdr' | 'displayEncoded';
+
+export interface ToneOutputContract {
+  readonly input: RenderColorDomain;
+  readonly toneMapped: boolean;
+  readonly mapped: 'linearLdr';
+  readonly finalCapture: 'displayEncoded';
+  readonly exposureStage: 'linearHdr' | 'none';
+}
+
+export type RenderPostStageName = 'transparent-blend' | 'bloom' | 'tone' | 'fxaa' | 'output';
+export type RenderPostDomainStage = readonly [
+  RenderPostStageName,
+  ColorValueDomain,
+  ColorValueDomain,
+];
+
+/**
+ * Single post-stage domain contract shared by URP and HDRP.
+ * The pipeline selects the scene domain for transparent geometry; every later
+ * stage follows the same linear blend, tone, anti-alias, and output sequence.
+ */
+export function resolvePostColorDomainContract(
+  pipeline: 'urp' | 'hdrp',
+): readonly RenderPostDomainStage[] {
+  const sceneDomain: ColorValueDomain = pipeline === 'hdrp' ? 'linear-hdr' : 'linear-ldr';
+  return [
+    ['transparent-blend', sceneDomain, sceneDomain],
+    ['bloom', 'linear-hdr', 'linear-hdr'],
+    ['tone', 'linear-hdr', 'linear-ldr'],
+    ['fxaa', 'linear-ldr', 'linear-ldr'],
+    ['output', 'linear-ldr', 'display-encoded'],
+  ];
+}
+
+/**
+ * Describe the built-in output stages without moving color-domain policy into
+ * a mode name. Tone-enabled cameras render HDR, apply exposure and the
+ * selected curve in the fullscreen pass, then reach the encoded surface.
+ */
+export function resolveToneOutputContract(tonemap: Tonemap): ToneOutputContract {
+  if (tonemap === 'none') {
+    return {
+      input: 'linearLdr',
+      toneMapped: false,
+      mapped: 'linearLdr',
+      finalCapture: 'displayEncoded',
+      exposureStage: 'none',
+    };
+  }
+  return {
+    input: 'linearHdr',
+    toneMapped: true,
+    mapped: 'linearLdr',
+    finalCapture: 'displayEncoded',
+    exposureStage: 'linearHdr',
+  };
+}
+
+/** Stable facts that may change graph topology and therefore its compiled identity. */
+export interface RenderPipelineTopology {
+  readonly pipelineId: string;
+  readonly config: import('@forgeax/engine-types').RenderPipelineAsset['config'];
+  readonly surface: {
+    readonly width: number;
+    readonly height: number;
+    readonly storageFormat: import('@forgeax/engine-rhi').TextureFormat;
+    readonly viewFormat: import('@forgeax/engine-rhi').TextureFormat;
+  };
+  readonly camera: Pick<RenderPipelineContext['camera'], 'tonemap' | 'antialias' | 'bloom'>;
+  readonly shadow: {
+    readonly mapSize: number;
+    readonly cascadeCount: 1 | 2 | 3 | 4;
+    readonly pointCount: number;
+    readonly pointFaceSize: number;
+    readonly spotCount: number;
+  };
+  readonly lane: {
+    readonly compute: boolean;
+    readonly storageBuffer: boolean;
+    readonly multisample: boolean;
+    readonly maxColorAttachments: number;
+  };
+  readonly featureTopologySignature: string;
+  readonly gpuDrivenTopologySignature: string;
+  /** Environment topology is absent off-path and producer-free when steady. */
+  readonly environment?:
+    | {
+        readonly enabled: boolean;
+        readonly dirty: boolean;
+      }
+    | undefined;
+}
+
+export type BuiltinEnvironmentPipeline = 'urp' | 'hdrp';
+
+/** Stable pass provenance used by topology traces and pixel-capture attribution. */
+export function createEnvironmentPipelineTopology(
+  pipeline: BuiltinEnvironmentPipeline,
+): readonly string[] {
+  return pipeline === 'urp'
+    ? [
+        'urp.shadow',
+        'urp.atmosphere-producer',
+        'urp.environment-background',
+        'urp.sun-disc',
+        'urp.forward',
+      ]
+    : [
+        'hdrp.membership',
+        'hdrp.shadow',
+        'hdrp.atmosphere-producer',
+        'hdrp.g-buffer',
+        'hdrp.lighting',
+        'hdrp.environment-background-depth-aware',
+        'hdrp.sun-disc',
+        'hdrp.forward',
+      ];
+}
+
+export interface RenderPipelineFrame extends RenderPipelineContext, RenderGraphFrame {}
+
+export interface RenderPipelineFeatureTarget {
+  readonly kind: RenderFeatureTargetKind;
+  readonly texture: GraphTexture;
+  readonly view: GraphTextureView;
+  readonly resolveTarget?: GraphTextureView | undefined;
+  readonly format: string;
+  readonly sampleCount: 1 | 4;
+}
+
+export interface RenderPipelineTemporalInput {
+  readonly sceneColor: RenderPipelineFeatureTarget;
+  readonly sceneDepth: RenderPipelineFeatureTarget;
+  readonly sceneTemporal?: RenderPipelineFeatureTarget | undefined;
+}
+
+export interface RenderPipelineTemporalOutput {
+  readonly resolvedColor: RenderPipelineFeatureTarget;
+}
+
+export interface RenderPipelineTemporalContract {
+  resolve(
+    input: RenderPipelineTemporalInput,
+  ): Result<RenderPipelineTemporalOutput | undefined, RenderPipelineBuildError>;
+  finish(): Result<void, RenderPipelineBuildError>;
+  inspect(): { readonly resolveCount: number };
+}
+
+export function createRenderPipelineTemporalContract(input: {
+  readonly enabled: boolean;
+  readonly rgba16floatRenderable: boolean;
+  readonly maxColorAttachments: number;
+  project(
+    input: RenderPipelineTemporalInput,
+  ): Result<RenderPipelineTemporalOutput, RenderPipelineBuildError>;
+}): RenderPipelineTemporalContract {
+  let resolveCount = 0;
+  return {
+    resolve(targets) {
+      resolveCount += 1;
+      if (!input.enabled) return ok(undefined);
+      if (resolveCount !== 1) {
+        return err(
+          new TemporalUnsupportedError('resolve-count', 'exactly 1', String(resolveCount)),
+        );
+      }
+      if (!input.rgba16floatRenderable || input.maxColorAttachments < 2) {
+        return err(
+          new TaaCapsInsufficientError(input.rgba16floatRenderable, input.maxColorAttachments),
+        );
+      }
+      if (targets.sceneColor.format !== 'rgba16float') {
+        return err(
+          new TemporalUnsupportedError(
+            'scene-color-domain',
+            'linear rgba16float',
+            targets.sceneColor.format,
+          ),
+        );
+      }
+      if (targets.sceneColor.sampleCount !== 1) {
+        return err(
+          new TemporalUnsupportedError(
+            'scene-color-sample-count',
+            '1',
+            String(targets.sceneColor.sampleCount),
+          ),
+        );
+      }
+      if (targets.sceneDepth.sampleCount !== 1) {
+        return err(
+          new TemporalUnsupportedError(
+            'scene-depth-sample-count',
+            '1',
+            String(targets.sceneDepth.sampleCount),
+          ),
+        );
+      }
+      const temporal = targets.sceneTemporal;
+      if (temporal === undefined || temporal.kind !== 'scene-temporal') {
+        return err(
+          new TemporalUnsupportedError(
+            'temporal-attachment-missing',
+            'scene-temporal',
+            temporal?.kind ?? 'missing',
+          ),
+        );
+      }
+      if (temporal.format !== 'rgba16float') {
+        return err(
+          new TemporalUnsupportedError(
+            'temporal-attachment-format',
+            'rgba16float',
+            temporal.format,
+          ),
+        );
+      }
+      if (temporal.sampleCount !== 1) {
+        return err(
+          new TemporalUnsupportedError(
+            'temporal-attachment-sample-count',
+            '1',
+            String(temporal.sampleCount),
+          ),
+        );
+      }
+      return input.project(targets);
+    },
+    finish() {
+      return input.enabled && resolveCount !== 1
+        ? err(new TemporalUnsupportedError('resolve-count', 'exactly 1', String(resolveCount)))
+        : ok(undefined);
+    },
+    inspect: () => ({ resolveCount }),
+  };
+}
+
+export interface RenderPipelineGpuDrivenProjection {
+  readonly accesses: readonly GraphAccess[];
+  /**
+   * Shadow cascades consume the same GPU-generated visibility/indirect
+   * contract as the main raster. The projection is optional for fallback
+   * devices and for frames without a safe shadow batch.
+   */
+  readonly shadow?: readonly RenderPipelineGpuDrivenShadowProjection[];
+  encode(
+    viewBindGroup: BindGroup,
+    pass: RhiRenderPassEncoder,
+    resources: GraphResourceResolver,
+  ): void;
+}
+
+export interface RenderPipelineGpuDrivenShadowProjection {
+  readonly cascadeIndex: number;
+  readonly accesses: readonly GraphAccess[];
+  /** Number of indirect `(cascade, shadow batch)` draw calls in this projection. */
+  readonly batchCount?: number;
+  /** The caller has already bound the shared shadow view/material groups. */
+  encode(pass: RhiRenderPassEncoder, resources: GraphResourceResolver): void;
+}
+
+export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame> {
+  readonly graph: RenderGraphBuilder<FrameCtx>;
+  /** Renderer-owned physical candidate views; custom pipelines may consume them. */
+  readonly environment?:
+    | {
+        readonly enabled: boolean;
+        readonly dirty: boolean;
+        readonly targets?: EnvironmentGraphTargets | undefined;
+        readonly sampledSky?: GraphTextureView | undefined;
+      }
+    | undefined;
+  projectGpuDriven(target: {
+    readonly format: string;
+    readonly sampleCount: 1 | 4;
+  }): Result<RenderPipelineGpuDrivenProjection | undefined, RenderPipelineBuildError>;
+  contributeFeatures(
+    targets: readonly RenderPipelineFeatureTarget[],
+  ): Result<void, RenderPipelineBuildError>;
+  resolveTemporal(
+    input: RenderPipelineTemporalInput,
+  ): Result<RenderPipelineTemporalOutput | undefined, RenderPipelineBuildError>;
+}
+
+export type RenderPipelineBuildError = RenderGraphError | RenderError | RhiError | PostProcessError;
+
+/**
+ * Registrable, installable, hot-swappable render topology.
+ *
+ * `build` declares resources and passes only. The renderer owns compilation,
+ * last-known-good replacement, execution, retirement, and the single frame submit.
+ * Feature contributions enter through `contributeFeatures`, so compute-produced
+ * buffers and later raster reads remain inside the same typed dependency graph.
+ */
+export interface RenderPipeline<FrameCtx extends RenderPipelineFrame = RenderPipelineFrame> {
+  build(
+    context: RenderPipelineBuildContext<FrameCtx>,
+    topology: RenderPipelineTopology,
+  ): Result<void, RenderPipelineBuildError>;
+}