@forgeax/engine-render 0.1.19 → 0.1.21

package/src/render-pipeline.ts

@@ -35,12 +35,14 @@ import type {
 } from '@forgeax/engine-rhi';
 import { ok, type Result } from '@forgeax/engine-types';
 import type { Tonemap } from './components/camera';
+import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type { RenderError } from './errors/render';
 import type { RenderFeatureTargetKind } from './features/targets';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
 } from './gpu-texture-usage';
+import type { StandardTopologyInputValue } from './pipeline/standard-lighting/topology';
 import { STANDARD_POST_STAGE_NAMES, type StandardProfile } from './pipeline/standard-profile';
 import type { SurfaceProfile } from './record/render-context';
 import type { RenderPipelineContext } from './render-contract';
@@ -50,6 +52,97 @@ export type { RenderPipelineContext } from './render-contract';
 
 export type RenderColorDomain = 'linearHdr' | 'linearLdr' | 'displayEncoded';
 
+/** Backend admission inputs used by the existing Render candidate owner. */
+export interface DirectionalShadowBackendAdmissionInput {
+  readonly backendKind: 'webgpu' | 'wgpu-webgl2' | 'null';
+  readonly requested: 'off' | DirectionalShadowFilterLabel;
+  readonly candidate: 'accepted' | 'failed';
+  readonly lastKnownGood?: DirectionalShadowFilterLabel | undefined;
+}
+
+/** Bounded, truthful Directional effective-profile projection. */
+export interface DirectionalShadowBackendAdmission {
+  readonly requested: 'off' | DirectionalShadowFilterLabel;
+  readonly effective: 'off' | DirectionalShadowFilterLabel | 'rhi-null-structural';
+  readonly status: 'accepted' | 'fallback' | 'rejected';
+  readonly fallbackReason?: 'webgl2-unsupported' | 'rhi-null-structural' | 'candidate-failed';
+  readonly lastKnownGood: boolean;
+  readonly pixelEvidence: 'available' | 'not-available';
+}
+
+/**
+ * Resolve a Directional profile only after the selected production candidate
+ * has been admitted. WebGL2 and RhiNull are the sole declared fallbacks;
+ * capable candidate failure retains a compatible LKG and never silently maps
+ * a failed PCSS request to PCF.
+ */
+export function resolveDirectionalShadowBackendAdmission(
+  input: DirectionalShadowBackendAdmissionInput,
+): DirectionalShadowBackendAdmission {
+  if (input.requested === 'off') {
+    return {
+      requested: 'off',
+      effective: 'off',
+      status: 'accepted',
+      lastKnownGood: false,
+      pixelEvidence: 'not-available',
+    };
+  }
+  if (input.backendKind === 'null') {
+    return {
+      requested: input.requested,
+      effective: 'rhi-null-structural',
+      status: 'fallback',
+      fallbackReason: 'rhi-null-structural',
+      lastKnownGood: false,
+      pixelEvidence: 'not-available',
+    };
+  }
+  if (input.backendKind === 'wgpu-webgl2') {
+    const effective =
+      input.requested === 'pcssMedium'
+        ? 'pcf3'
+        : input.requested === 'pcssHigh'
+          ? 'pcf5'
+          : input.requested;
+    return {
+      requested: input.requested,
+      effective,
+      status: effective === input.requested ? 'accepted' : 'fallback',
+      ...(effective === input.requested ? {} : { fallbackReason: 'webgl2-unsupported' as const }),
+      lastKnownGood: false,
+      pixelEvidence: 'available',
+    };
+  }
+  if (input.candidate === 'accepted') {
+    return {
+      requested: input.requested,
+      effective: input.requested,
+      status: 'accepted',
+      lastKnownGood: false,
+      pixelEvidence: 'available',
+    };
+  }
+  if (input.lastKnownGood !== undefined) {
+    return {
+      requested: input.requested,
+      effective: input.lastKnownGood,
+      status: 'rejected',
+      fallbackReason: 'candidate-failed',
+      lastKnownGood: true,
+      pixelEvidence: 'available',
+    };
+  }
+  return {
+    requested: input.requested,
+    effective: input.requested,
+    status: 'rejected',
+    fallbackReason: 'candidate-failed',
+    lastKnownGood: false,
+    pixelEvidence: 'available',
+  };
+}
+
 export interface ToneOutputContract {
   readonly input: RenderColorDomain;
   readonly toneMapped: boolean;
@@ -135,12 +228,59 @@ export interface RenderPipelineTopology {
     readonly motionBlur: boolean;
   };
   readonly shadow: {
-    readonly mapSize: number;
-    readonly cascadeCount: 1 | 2 | 3 | 4;
+    readonly directional:
+      | 'disabled'
+      | {
+          readonly mapSize: number;
+          readonly cascadeCount: 1 | 2 | 3 | 4;
+        };
+    readonly spotMapSize: number;
     readonly pointCount: number;
     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;
@@ -149,10 +289,19 @@ export interface RenderPipelineTopology {
   };
   readonly featureTopologySignature: string;
   readonly gpuDrivenTopologySignature: string;
+  /** Stable Cluster transport/layout facts; excludes per-frame light payloads. */
+  readonly standardLightingTopologySignature?: string | undefined;
   /** Internal graph fact; renderer callers do not configure transmission demand. */
   readonly transmissionDemand?: TransmissionDemand | undefined;
 }
 
+/** Resolve the built-in final-output dither policy from the pipeline asset. */
+export function resolveOutputDither(
+  config: import('@forgeax/engine-types').RenderPipelineAsset['config'],
+): boolean {
+  return config?.outputDither ?? true;
+}
+
 export interface RenderPipelineFrame extends RenderPipelineContext, RenderGraphFrame {}
 
 export interface RenderPipelineTarget {
@@ -257,6 +406,8 @@ export function importRenderPipelineSurface(
 }
 
 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;
@@ -276,6 +427,12 @@ export interface RenderPipelineGpuDrivenProjection {
 
 export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame> {
   readonly graph: RenderGraphBuilder<FrameCtx>;
+  /**
+   * The single prepared Standard lighting projection for this frame.  The
+   * Forward and Deferred adapters consume this value; they never inspect raw
+   * light snapshots, cluster config, or capability facts themselves.
+   */
+  readonly standardLighting?: StandardTopologyInputValue;
   /**
    * Renderer-owned capability facts needed for admission decisions. The
    * Standard temporal producer must use the live device probe rather than
@@ -310,6 +467,8 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     semanticTargets?: readonly RenderPipelineTarget[],
     namedTargets?: Readonly<Record<string, RenderPipelineTarget>>,
   ): Result<void, RenderPipelineBuildError>;
+  /** Add renderer-owned cube capture work to the active pipeline graph. */
+  contributeCubeCaptures?(): Result<void, RenderPipelineBuildError>;
   /** Whether a producer-owned feature is installed for this graph build. */
   hasFeature?(identity: string): boolean;
 }