@forgeax/engine-render 0.1.7 → 0.1.20

package/src/render-pipeline.ts

@@ -26,7 +26,13 @@ import type {
   RenderGraphError,
   RenderGraphFrame,
 } from '@forgeax/engine-render-graph';
-import type { BindGroup, RhiError, RhiRenderPassEncoder, TextureFormat } from '@forgeax/engine-rhi';
+import type {
+  BindGroup,
+  RhiCaps,
+  RhiError,
+  RhiRenderPassEncoder,
+  TextureFormat,
+} from '@forgeax/engine-rhi';
 import { ok, type Result } from '@forgeax/engine-types';
 import type { Tonemap } from './components/camera';
 import type { RenderError } from './errors/render';
@@ -35,8 +41,10 @@ import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
 } from './gpu-texture-usage';
-import type { StandardProfile } from './pipeline/standard-profile';
+import { STANDARD_POST_STAGE_NAMES, type StandardProfile } from './pipeline/standard-profile';
+import type { SurfaceProfile } from './record/render-context';
 import type { RenderPipelineContext } from './render-contract';
+import type { TransmissionDemand } from './transmission/projection';
 
 export type { RenderPipelineContext } from './render-contract';
 
@@ -50,7 +58,7 @@ export interface ToneOutputContract {
   readonly exposureStage: 'linearHdr' | 'none';
 }
 
-export type RenderPostStageName = 'transparent-blend' | 'bloom' | 'tone' | 'fxaa' | 'output';
+export type RenderPostStageName = (typeof STANDARD_POST_STAGE_NAMES)[number];
 export type RenderPostDomainStage = readonly [
   RenderPostStageName,
   ColorValueDomain,
@@ -60,18 +68,21 @@ export type RenderPostDomainStage = readonly [
 /**
  * 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.
+ * stage follows the same linear blend, output-transform, anti-alias, post-effect, and present sequence.
  */
 export function resolvePostColorDomainContract(
   sceneDomain: 'linear-ldr' | 'linear-hdr',
 ): readonly RenderPostDomainStage[] {
   const scene: ColorValueDomain = sceneDomain;
+  const [transparentBlend, bloom, outputTransform, fxaa, postEffect, present] =
+    STANDARD_POST_STAGE_NAMES;
   return [
-    ['transparent-blend', scene, scene],
-    ['bloom', 'linear-hdr', 'linear-hdr'],
-    ['tone', 'linear-hdr', 'linear-ldr'],
-    ['fxaa', 'linear-ldr', 'linear-ldr'],
-    ['output', 'linear-ldr', 'display-encoded'],
+    [transparentBlend, scene, scene],
+    [bloom, 'linear-hdr', 'linear-hdr'],
+    [outputTransform, scene, 'display-encoded'],
+    [fxaa, 'display-encoded', 'display-encoded'],
+    [postEffect, 'display-encoded', 'display-encoded'],
+    [present, 'display-encoded', 'display-encoded'],
   ];
 }
 
@@ -104,13 +115,25 @@ export interface RenderPipelineTopology {
   readonly pipelineId: string;
   readonly standardProfile?: StandardProfile | undefined;
   readonly config: import('@forgeax/engine-types').RenderPipelineAsset['config'];
+  /**
+   * The record stage had no Camera and injected the synthetic clear-only
+   * snapshot.  Keep that fact explicit so a normal no-tone Camera still uses
+   * the float Output Transform while the empty-scene contract can write its
+   * clear directly to the surface.
+   */
+  readonly clearOnly?: boolean | undefined;
   readonly surface: {
     readonly width: number;
     readonly height: number;
     readonly storageFormat: import('@forgeax/engine-rhi').TextureFormat;
     readonly viewFormat: import('@forgeax/engine-rhi').TextureFormat;
+    readonly profile?: SurfaceProfile | undefined;
   };
   readonly camera: Pick<RenderPipelineContext['camera'], 'tonemap' | 'antialias' | 'bloom'>;
+  readonly temporal?: {
+    readonly taa: boolean;
+    readonly motionBlur: boolean;
+  };
   readonly shadow: {
     readonly mapSize: number;
     readonly cascadeCount: 1 | 2 | 3 | 4;
@@ -118,6 +141,48 @@ export interface RenderPipelineTopology {
     readonly pointFaceSize: number;
     readonly spotCount: number;
   };
+  /**
+   * Authored volume topology facts.  Identity/generation/digest are runtime
+   * residency facts and deliberately do not participate in graph topology.
+   */
+  readonly volumetricFog?: {
+    readonly enabled: boolean;
+    readonly lightKind?: 'directional' | 'point' | 'spot' | undefined;
+    readonly lightEntity?: number | undefined;
+    readonly pointLightEntity?: number | undefined;
+    readonly spotLightEntity?: number | undefined;
+    readonly projector?:
+      | {
+          readonly guid: string;
+          readonly generation: number;
+          readonly revision: number;
+        }
+      | undefined;
+    readonly format?: TextureFormat | undefined;
+    readonly extent?:
+      | {
+          readonly width: number;
+          readonly height: number;
+          readonly depth: number;
+        }
+      | undefined;
+    /** Renderer-owned froxel grid derived from the compiled surface extent. */
+    readonly froxelExtent?:
+      | {
+          readonly width: number;
+          readonly height: number;
+          readonly depth: number;
+        }
+      | undefined;
+    /** Renderer-owned 2D resolve/history extent derived from the same profile. */
+    readonly resolvedExtent?:
+      | {
+          readonly width: number;
+          readonly height: number;
+          readonly depth: number;
+        }
+      | undefined;
+  };
   readonly lane: {
     readonly compute: boolean;
     readonly storageBuffer: boolean;
@@ -126,6 +191,8 @@ export interface RenderPipelineTopology {
   };
   readonly featureTopologySignature: string;
   readonly gpuDrivenTopologySignature: string;
+  /** Internal graph fact; renderer callers do not configure transmission demand. */
+  readonly transmissionDemand?: TransmissionDemand | undefined;
 }
 
 export interface RenderPipelineFrame extends RenderPipelineContext, RenderGraphFrame {}
@@ -135,6 +202,7 @@ export interface RenderPipelineTarget {
   readonly view: GraphTextureView;
   readonly format: TextureFormat;
   readonly sampleCount: 1 | 4;
+  readonly domain?: ColorValueDomain | undefined;
   readonly resolveTarget?: GraphTextureView | undefined;
 }
 
@@ -153,6 +221,7 @@ export function createRenderPipelineTarget(
     view: view.value,
     format: viewDescriptor.format ?? descriptor.format,
     sampleCount: descriptor.sampleCount === 4 ? 4 : 1,
+    ...(descriptor.domain === undefined ? {} : { domain: descriptor.domain }),
   });
 }
 
@@ -160,7 +229,7 @@ export function importRenderPipelineSurface(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   topology: RenderPipelineTopology,
 ): Result<
-  { readonly display: RenderPipelineTarget; readonly storage: RenderPipelineTarget },
+  { readonly display?: RenderPipelineTarget; readonly storage: RenderPipelineTarget },
   RenderGraphError
 > {
   const texture = graph.importTexture(
@@ -168,21 +237,32 @@ export function importRenderPipelineSurface(
     {
       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],
+      // The imported surface is the final encoded endpoint.  Keeping this
+      // semantic fact on the graph resource lets detached inspection project
+      // from the compiled graph instead of re-inferring it from format names.
+      domain: 'display-encoded',
+      usage:
+        GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+        (topology.surface.profile?.kind === 'raw-only' ? 0 : GPU_TEXTURE_USAGE_COPY_SRC),
+      viewFormats: [
+        ...(topology.surface.profile?.viewFormats ??
+          (topology.surface.storageFormat === topology.surface.viewFormat
+            ? []
+            : [topology.surface.viewFormat])),
+      ],
     },
     (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 display =
+    topology.surface.profile?.hasDisplayEndpoint === false
+      ? undefined
+      : graph.importView(
+          texture.value,
+          { label: 'surface.display', format: topology.surface.viewFormat },
+          (frame) => frame.view,
+        );
+  if (display !== undefined && !display.ok) return display;
   const storage = graph.importView(
     texture.value,
     { label: 'surface.storage', format: topology.surface.storageFormat },
@@ -197,22 +277,30 @@ export function importRenderPipelineSurface(
   );
   if (!storage.ok) return storage;
   return ok({
-    display: {
-      texture: texture.value,
-      view: display.value,
-      format: topology.surface.viewFormat,
-      sampleCount: 1,
-    },
+    ...(display === undefined
+      ? {}
+      : {
+          display: {
+            texture: texture.value,
+            view: display.value,
+            format: topology.surface.viewFormat,
+            sampleCount: 1 as const,
+            domain: 'display-encoded' as const,
+          },
+        }),
     storage: {
       texture: texture.value,
       view: storage.value,
       format: topology.surface.storageFormat,
       sampleCount: 1,
+      domain: 'display-encoded',
     },
   });
 }
 
 export interface RenderPipelineFeatureTarget {
+  /** Optional semantic alias when a pipeline exposes multiple color roles. */
+  readonly name?: string;
   readonly kind: RenderFeatureTargetKind;
   readonly texture: GraphTexture;
   readonly view: GraphTextureView;
@@ -232,13 +320,42 @@ export interface RenderPipelineGpuDrivenProjection {
 
 export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame> {
   readonly graph: RenderGraphBuilder<FrameCtx>;
+  /**
+   * Renderer-owned capability facts needed for admission decisions. The
+   * Standard temporal producer must use the live device probe rather than
+   * inferring rgba16float support from the selected surface format.
+   */
+  readonly capabilities?: Pick<RhiCaps, 'rgba16floatRenderable'>;
+  /**
+   * Renderer-owned TAA history targets. The graph sees only imported typed
+   * targets; opaque RHI handles remain inside RenderFrameState.
+   */
+  readonly taaHistory?: {
+    readonly currentColor: RenderPipelineTarget;
+    readonly previousColor: RenderPipelineTarget;
+    readonly currentTemporal: RenderPipelineTarget;
+    readonly previousTemporal: RenderPipelineTarget;
+  };
+  /** Renderer-owned, prewarmed encoder for one graph mip level. */
+  readonly encodeTransmissionMip?: (input: {
+    readonly pass: RhiRenderPassEncoder;
+    readonly frame: FrameCtx;
+    readonly resources: GraphResourceResolver;
+    readonly source: GraphTextureView;
+    readonly destination: GraphTextureView;
+    readonly level: number;
+  }) => void;
   projectGpuDriven(target: {
     readonly format: TextureFormat;
     readonly sampleCount: 1 | 4;
   }): Result<RenderPipelineGpuDrivenProjection | undefined, RenderPipelineBuildError>;
   contributeFeatures(
     targets: readonly RenderPipelineFeatureTarget[],
+    semanticTargets?: readonly RenderPipelineTarget[],
+    namedTargets?: Readonly<Record<string, RenderPipelineTarget>>,
   ): Result<void, RenderPipelineBuildError>;
+  /** Whether a producer-owned feature is installed for this graph build. */
+  hasFeature?(identity: string): boolean;
 }
 
 export type RenderPipelineBuildError = RenderGraphError | RenderError | RhiError;