@forgeax/engine-render 0.1.20 → 0.1.23

package/src/render-contract.ts

@@ -31,23 +31,60 @@ import type { RenderFeature, RenderFeatureDiagnostics } from './features/types';
 import type { PostProcessShaderEntry } from './fullscreen-post-process-pass';
 import type {
   BloomInspection,
+  DirectionalShadowInspection,
+  LightInspection,
+  LodOcclusionInspection,
   MotionBlurInspection,
+  ReflectionProbeInspection,
   RenderSceneInspection,
+  SsrDependenciesInspection,
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types';
+import type { SsrAdmissionIdentity } from './ssr/identity';
+import type {
+  RenderTarget,
+  RenderTargetDescriptor,
+  RenderTargetReadbackData,
+  RenderTargetReadbackRequest,
+  RenderTargetReadbackTicket,
+  RenderTargetTextureSource,
+  RenderTargetTextureSourceOptions,
+} from './targets/contracts';
 import type { TemporalInspection } from './temporal/inspection';
 
 export type { TransmissionInspection } from './inspection-types';
 export type { PointsLinesInspection } from './points-lines/inspection';
 
 import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
+import type { StandardLightingInspection } from './pipeline/standard-lighting/inspection';
 import type { StandardProfile } from './pipeline/standard-profile';
+import type { PointShadowInspection } from './point-shadow-inspection';
 import type { PostProcessError } from './post-process-errors';
+import type {
+  GpuPassTimingObservation,
+  GpuPassTimingOptions,
+} from './record/gpu-pass-timing/index.js';
 import type { VolumeTimingObservation } from './record/gpu-timing';
 import type { TemporalView } from './temporal/view';
 import type { VolumetricFogInspection } from './volume/inspection';
 
+export type {
+  CubeCameraFace,
+  CubeCameraUpdateIntent,
+} from './components/cube-camera';
+
+export interface CubeCameraSnapshot {
+  readonly entityKey?: number;
+  readonly target: RenderTarget;
+  readonly position: readonly [number, number, number];
+  readonly near: number;
+  readonly far: number;
+  readonly updateIntent: import('./components/cube-camera').CubeCameraUpdateIntent;
+  readonly requestVersion: number;
+  readonly faceBudget: number;
+}
+
 export type RenderResult<T, E> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly error: E };
@@ -65,13 +102,15 @@ export type RenderWorldLease = RenderReadLease;
 export interface CameraSnapshot {
   /** Stable ECS identity used by the frame plan's camera authority fact. */
   readonly entityKey?: number;
+  /** Auxiliary logical target; physical views remain renderer-owned. */
+  readonly target?: RenderTarget;
   /** World index supplied by the multi-world extract merge. */
   readonly worldId?: number;
   /** Camera-owned history generation forwarded into the frame plan. */
   readonly historyVersion?: number;
-  /** World-space camera translation (mat4.getTranslation of Transform.world). */
+  /** World-space camera translation (mat4.getTranslation of GlobalTransform.world). */
   readonly position: Vec3;
-  /** Resolved world-space camera mat4, copied from Transform.world. */
+  /** Resolved world-space camera mat4, copied from GlobalTransform.world. */
   readonly world: Float32Array;
   readonly fov: number;
   readonly aspect: number;
@@ -105,6 +144,9 @@ export interface CameraSnapshot {
 /** Stable identity owned by the Standard feature host for output transform. */
 export const STANDARD_OUTPUT_TRANSFORM_FEATURE_ID = 'forgeax::standard::output-transform';
 
+/** Stable identity for the special FXAA pass' per-frame output policy UBO. */
+export const FXAA_POST_PROCESS_ID = 'forgeax::post::fxaa';
+
 export type {
   EnvironmentFrame,
   EnvironmentSource,
@@ -123,9 +165,6 @@ interface RenderPipelineStateView {
   readonly colorAttachmentFormat: TextureFormat;
   /** Renderer-owned View UBO shared by Standard lighting, shadows, and fog. */
   readonly viewUniformBuffer: Buffer;
-  /** Renderer-owned SpotLight std430 buffer shared by Standard and volume. */
-  readonly pointLightsBuffer: Buffer;
-  readonly spotLightsBuffer: Buffer;
   /** Fallback resources keep the shared view layout valid when no projector is authored. */
   readonly defaultWhiteTextureView: TextureView;
   readonly defaultSampler: Sampler;
@@ -156,6 +195,7 @@ interface RenderPipelineRuntime {
     id: string,
     bgl: BindGroupLayout,
     colorFormat: GPUTextureFormat,
+    entry?: PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
 }
 
@@ -237,6 +277,10 @@ export interface SpotLightProjectorFrameContext {
   readonly texture: Texture;
   readonly view: TextureView;
   readonly sampler: Sampler;
+  /** Spot-light index in ExtractedLights.spot for the accepted texture. */
+  readonly spotIndex?: number;
+  /** Unified Standard Cluster slot index (points precede spots). */
+  readonly lightSlotIndex?: number;
 }
 
 /**
@@ -246,6 +290,20 @@ export interface SpotLightProjectorFrameContext {
 export interface Renderer {
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
+  createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
+  resizeRenderTarget(
+    target: RenderTarget,
+    descriptor: RenderTargetDescriptor,
+  ): RenderResult<void, RenderError>;
+  createRenderTargetTextureSource(
+    target: RenderTarget,
+    options: RenderTargetTextureSourceOptions,
+  ): RenderResult<RenderTargetTextureSource, RenderError>;
+  requestTargetReadback(
+    target: RenderTarget,
+    request: RenderTargetReadbackRequest,
+  ): RenderResult<RenderTargetReadbackTicket, RenderError>;
+  destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   state(): RendererState;
   inspect(): RenderInspection;
@@ -256,6 +314,7 @@ export interface Renderer {
   subscribe(listener: (event: RendererEvent) => void): () => void;
   releaseSurface(): RenderResult<void, RenderError>;
   restoreSurface(): RenderResult<void, RenderError>;
+  /** Recover only from device-lost; a healthy renderer returns a guard error. */
   recover(): Promise<RenderResult<void, RenderError>>;
   dispose(): Promise<RenderResult<void, RenderError>>;
 }
@@ -305,11 +364,12 @@ export interface FrameEnvironment {
 
 /**
  * Receipt-bound observation selection. The request is consumed by `observe`
- * only with the matching FrameReceipt and returns a structured Result error
- * when the generation or frame identity is stale.
+ * only with the matching FrameReceipt after `receipt.completed` and returns a
+ * structured Result error when the generation or frame identity is stale.
  */
 export interface FrameObservationRequest {
-  readonly include: readonly ('timings' | 'draws' | 'bindings')[];
+  readonly include: readonly ('timings' | 'draws' | 'bindings' | 'target-readbacks')[];
+  readonly targetReadbacks?: readonly RenderTargetReadbackTicket[];
 }
 
 /**
@@ -340,8 +400,12 @@ export interface RenderFrameInput {
 export interface FrameReceiptObservation {
   readonly frameId: number;
   readonly deviceGeneration: number;
-  readonly include: readonly ('timings' | 'draws' | 'bindings')[];
-  readonly timings?: VolumeTimingObservation;
+  readonly include: readonly ('timings' | 'draws' | 'bindings' | 'target-readbacks')[];
+  /** Receipt-bound Render-owned GPU pass facts; absent when not requested. */
+  readonly timings?: GpuPassTimingObservation | undefined;
+  /** Receipt-bound volume GPU timing facts; absent when not requested. */
+  readonly volumeTimings?: VolumeTimingObservation | undefined;
+  readonly targetReadbacks?: readonly RenderTargetReadbackData[];
 }
 
 /** Stable backend facts for the Standard output transform projection. */
@@ -418,8 +482,15 @@ export interface RenderInspection {
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
   readonly renderScene: RenderSceneInspection;
+  readonly reflectionProbes: ReflectionProbeInspection;
+  /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */
+  readonly ssrDependencies: SsrDependenciesInspection;
   /** Last completed transmission candidate facts, detached from GPU handles. */
   readonly transmission?: TransmissionInspection;
+  /** Last prepared Standard transport facts, detached from GPU handles. */
+  readonly standardLighting?: StandardLightingInspection;
+  /** Renderer-owned point-shadow atlas budget facts from the last frame. */
+  readonly pointShadow?: PointShadowInspection;
   readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
   readonly perFramePassNames: readonly string[];
   readonly bindGroupCounts: {
@@ -440,10 +511,15 @@ export interface RenderInspection {
   readonly environment: EnvironmentInspection;
   readonly temporal: TemporalInspection;
   readonly bloom: BloomInspection;
+  /** Candidate/accepted/LKG facts for the single extendedLighting topology. */
+  readonly extendedLighting: LightInspection;
+  readonly directionalShadow: DirectionalShadowInspection;
   /** Semantic Standard temporal target metadata; no graph or RHI handles. */
   readonly temporalTarget?: TemporalTargetInspection;
   /** Renderer-owned Motion Blur facts; absent when no component is active. */
   readonly motionBlur?: MotionBlurInspection;
+  /** Bounded renderer-owned LOD/occlusion facts; absent before a candidate frame. */
+  readonly lodOcclusion?: LodOcclusionInspection;
 }
 
 /** Backend marker — single-element union preserved for future extensibility (D-2). */
@@ -607,6 +683,8 @@ export const RENDER_SCENE_STATE_PHASE_CATALOG = [
  * attribution without guessing from RHI command counts.
  */
 export const RENDER_RECORD_PHASE_CATALOG = [
+  'record/occlusion-query-submit',
+  'record/occlusion-global-advance',
   'record/scene-state',
   ...RENDER_SCENE_STATE_PHASE_CATALOG,
   'record/swapchain',
@@ -624,6 +702,7 @@ export type RenderRecordPhase = (typeof RENDER_RECORD_PHASE_CATALOG)[number];
 
 export const RENDER_PHASE_CATALOG = [
   'extract',
+  'occlusion-prepare',
   'bind-groups',
   'features',
   'sort',
@@ -651,6 +730,10 @@ export interface RendererOptions {
   readonly captureGpuTimings?: boolean | undefined;
   /** Optional host-owned RHI lifecycle instrumentation, such as recording. */
   readonly rhiInstrumentation?: RhiBackendInstrumentation | undefined;
+  /** Optional bounded GPU pass timing facts; this is not frame latency. */
+  readonly gpuPassTiming?: GpuPassTimingOptions | undefined;
+  /** Exact source/tree/lock/build identity binding for the renderer-owned SSR seam. */
+  readonly ssrIdentity?: SsrAdmissionIdentity | undefined;
   // feat-20260608-create-app-param-surface-trim / M1 / AC-02: `clearColor`
   // was deleted as a one-cut breaking change (AGENTS.md Change stance +
   // requirements constraint #1: no deprecation window, no shim). Scene

package/src/render-graph-primitives.ts

@@ -550,6 +550,7 @@ function dispatchFullscreenPass(
   graphPass?: RhiRenderPassEncoder,
   graphOutputFormat?: GPUTextureFormat,
   graphDepthView?: TextureView,
+  paramsOverride?: Uint8Array,
 ): void {
   if (shader === 'fxaa') {
     if (resolveCtx === undefined) {
@@ -705,7 +706,11 @@ function dispatchFullscreenPass(
   if (entry.params !== undefined) {
     const ubo = ctx.runtime.getPostProcessParamsBuffer?.(shader);
     if (ubo !== undefined) {
-      const data = ctx.postProcessParams.get(shader);
+      // Typed graph passes may make a narrow, per-pass copy of the payload
+      // (for example enabling final-surface dither without changing the
+      // camera-owned SSOT).  Use it when present, while preserving the normal
+      // frame snapshot for legacy callers.
+      const data = paramsOverride ?? ctx.postProcessParams.get(shader);
       if (data !== undefined) {
         if (data.byteLength !== entry.params.byteSize) {
           throw new PostProcessError({
@@ -769,9 +774,7 @@ function dispatchFullscreenPass(
   if (lookupPipeline === undefined) return;
   const postColorFormat = writeFormat;
   const pipeline = lookupPipeline(shader, built.bindGroupLayout, postColorFormat);
-  if (pipeline === null) {
-    return;
-  }
+  if (pipeline === null) return;
   const handle = built.createHandle(name, pipeline, paramsBuffer);
 
   // Open a render pass writing into the resolved color target. Fullscreen
@@ -810,6 +813,7 @@ export function encodeFullscreenPass(
     readonly outputFormat: GPUTextureFormat;
     readonly rawSwapchainOutput?: boolean | undefined;
     readonly depthView?: TextureView | undefined;
+    readonly paramsOverride?: Uint8Array | undefined;
   },
 ): void {
   dispatchFullscreenPass(
@@ -824,5 +828,6 @@ export function encodeFullscreenPass(
     pass,
     input.outputFormat,
     input.depthView,
+    input.paramsOverride,
   );
 }

package/src/render-pipeline.ts

@@ -35,21 +35,115 @@ 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';
+import type { OcclusionFrameProjection } from './scene/visibility/occlusion-runtime';
 import type { TransmissionDemand } from './transmission/projection';
 
 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;
@@ -122,6 +216,8 @@ export interface RenderPipelineTopology {
    * clear directly to the surface.
    */
   readonly clearOnly?: boolean | undefined;
+  /** Whether Standard main draws carry the producer-owned fallback MRT. */
+  readonly reflectionFallback?: { readonly enabled: boolean } | undefined;
   readonly surface: {
     readonly width: number;
     readonly height: number;
@@ -135,8 +231,13 @@ 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;
@@ -191,10 +292,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 {
@@ -320,6 +430,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
@@ -345,6 +461,8 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     readonly destination: GraphTextureView;
     readonly level: number;
   }) => void;
+  /** Renderer-owned occlusion query state for the primary scene pass. */
+  readonly occlusion?: OcclusionFrameProjection;
   projectGpuDriven(target: {
     readonly format: TextureFormat;
     readonly sampleCount: 1 | 4;
@@ -354,6 +472,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;
 }