@forgeax/engine-render 0.1.3 → 0.1.6

package/src/render-pipeline.ts

@@ -1,10 +1,9 @@
 // @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).
+// `RenderPipeline` is the typed topology contribution used by the Standard host.
+// The host owns the single active pipeline identity and its lifecycle; producers
+// contribute graph declarations through this interface instead of publishing a
+// second renderer authority.
 //
 // Naming note (requirements line 155): `RenderPipeline` here is the forgeax engine
 // concept name. The RHI GPU `RenderPipeline` handle (`@forgeax/engine-rhi`) is a
@@ -20,25 +19,26 @@ import type {
   GraphAccess,
   GraphResourceResolver,
   GraphTexture,
+  GraphTextureDescriptor,
   GraphTextureView,
+  GraphTextureViewDescriptor,
   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 { BindGroup, RhiError, RhiRenderPassEncoder, TextureFormat } from '@forgeax/engine-rhi';
+import { 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 { RenderError } from './errors/render';
 import type { RenderFeatureTargetKind } from './features/targets';
-import type { PostProcessError } from './post-process-errors';
-import type { RenderPipelineContext } from './render-pipeline-context';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+} from './gpu-texture-usage';
+import type { StandardProfile } from './pipeline/standard-profile';
+import type { RenderPipelineContext } from './render-contract';
 
-export type { RenderPipelineContext } from './render-pipeline-context';
+export type { RenderPipelineContext } from './render-contract';
 
 export type RenderColorDomain = 'linearHdr' | 'linearLdr' | 'displayEncoded';
 
@@ -58,16 +58,16 @@ export type RenderPostDomainStage = readonly [
 ];
 
 /**
- * Single post-stage domain contract shared by URP and HDRP.
- * The pipeline selects the scene domain for transparent geometry; every later
+ * Single post-stage domain contract shared by the Standard lighting lanes.
+ * The selected scene domain for transparent geometry is explicit; every later
  * stage follows the same linear blend, tone, anti-alias, and output sequence.
  */
 export function resolvePostColorDomainContract(
-  pipeline: 'urp' | 'hdrp',
+  sceneDomain: 'linear-ldr' | 'linear-hdr',
 ): readonly RenderPostDomainStage[] {
-  const sceneDomain: ColorValueDomain = pipeline === 'hdrp' ? 'linear-hdr' : 'linear-ldr';
+  const scene: ColorValueDomain = sceneDomain;
   return [
-    ['transparent-blend', sceneDomain, sceneDomain],
+    ['transparent-blend', scene, scene],
     ['bloom', 'linear-hdr', 'linear-hdr'],
     ['tone', 'linear-hdr', 'linear-ldr'],
     ['fxaa', 'linear-ldr', 'linear-ldr'],
@@ -102,6 +102,7 @@ export function resolveToneOutputContract(tonemap: Tonemap): ToneOutputContract
 /** Stable facts that may change graph topology and therefore its compiled identity. */
 export interface RenderPipelineTopology {
   readonly pipelineId: string;
+  readonly standardProfile?: StandardProfile | undefined;
   readonly config: import('@forgeax/engine-types').RenderPipelineAsset['config'];
   readonly surface: {
     readonly width: number;
@@ -125,167 +126,103 @@ export interface RenderPipelineTopology {
   };
   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;
+export interface RenderPipelineTarget {
   readonly texture: GraphTexture;
   readonly view: GraphTextureView;
-  readonly resolveTarget?: GraphTextureView | undefined;
-  readonly format: string;
+  readonly format: TextureFormat;
   readonly sampleCount: 1 | 4;
+  readonly resolveTarget?: GraphTextureView | undefined;
 }
 
-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 createRenderPipelineTarget(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  label: string,
+  descriptor: GraphTextureDescriptor,
+  viewDescriptor: GraphTextureViewDescriptor = {},
+): Result<RenderPipelineTarget, RenderGraphError> {
+  const texture = graph.createTexture(label, descriptor);
+  if (!texture.ok) return texture;
+  const view = graph.view(texture.value, { label: `${label}.view`, ...viewDescriptor });
+  if (!view.ok) return view;
+  return ok({
+    texture: texture.value,
+    view: view.value,
+    format: viewDescriptor.format ?? descriptor.format,
+    sampleCount: descriptor.sampleCount === 4 ? 4 : 1,
+  });
 }
 
-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);
+export function importRenderPipelineSurface(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  topology: RenderPipelineTopology,
+): Result<
+  { readonly display: RenderPipelineTarget; readonly storage: RenderPipelineTarget },
+  RenderGraphError
+> {
+  const texture = graph.importTexture(
+    'surface',
+    {
+      format: topology.surface.storageFormat,
+      size: 'surface',
+      usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_COPY_SRC,
+      viewFormats:
+        topology.surface.storageFormat === topology.surface.viewFormat
+          ? []
+          : [topology.surface.viewFormat],
     },
-    finish() {
-      return input.enabled && resolveCount !== 1
-        ? err(new TemporalUnsupportedError('resolve-count', 'exactly 1', String(resolveCount)))
-        : ok(undefined);
+    (frame) => frame.currentTexture,
+  );
+  if (!texture.ok) return texture;
+  const display = graph.importView(
+    texture.value,
+    { label: 'surface.display', format: topology.surface.viewFormat },
+    (frame) => frame.view,
+  );
+  if (!display.ok) return display;
+  const storage = graph.importView(
+    texture.value,
+    { label: 'surface.storage', format: topology.surface.storageFormat },
+    (frame) => {
+      if (topology.surface.storageFormat === topology.surface.viewFormat) return frame.view;
+      const resolved = frame.runtime.device.createTextureView(frame.currentTexture, {
+        format: topology.surface.storageFormat,
+      });
+      if (!resolved.ok) throw resolved.error;
+      return resolved.value;
     },
-    inspect: () => ({ resolveCount }),
-  };
+  );
+  if (!storage.ok) return storage;
+  return ok({
+    display: {
+      texture: texture.value,
+      view: display.value,
+      format: topology.surface.viewFormat,
+      sampleCount: 1,
+    },
+    storage: {
+      texture: texture.value,
+      view: storage.value,
+      format: topology.surface.storageFormat,
+      sampleCount: 1,
+    },
+  });
+}
+
+export interface RenderPipelineFeatureTarget {
+  readonly kind: RenderFeatureTargetKind;
+  readonly texture: GraphTexture;
+  readonly view: GraphTextureView;
+  readonly resolveTarget?: GraphTextureView | undefined;
+  readonly format: TextureFormat;
+  readonly sampleCount: 1 | 4;
 }
 
 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,
@@ -293,39 +230,18 @@ export interface RenderPipelineGpuDrivenProjection {
   ): 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 format: TextureFormat;
     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;
+export type RenderPipelineBuildError = RenderGraphError | RenderError | RhiError;
 
 /**
  * Registrable, installable, hot-swappable render topology.