@forgeax/engine-render 0.1.33 → 0.1.35

package/src/render-contract.ts

@@ -3,7 +3,12 @@ import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
 import type { Vec3 } from '@forgeax/engine-math';
 import type { ProfileFrameToken, Profiler } from '@forgeax/engine-profiler';
-import type { ColorValueDomain, RenderGraphError } from '@forgeax/engine-render-graph';
+import type {
+  ColorValueDomain,
+  RenderGraphError,
+  RenderGraphGenerationAllocationInspection,
+  RenderGraphResourceAllocationInspection,
+} from '@forgeax/engine-render-graph';
 import type {
   BindGroupLayout,
   Buffer,
@@ -24,6 +29,8 @@ import type {
 import type { SkinError } from '@forgeax/engine-skinning';
 import type { ImageError } from '@forgeax/engine-types';
 import type { RhiBackendInstrumentation } from './assembly/backend-contract.js';
+import type { CloudLayerInspection } from './cloud/inspection.js';
+import type { BarrelDistortionData } from './components/barrel-distortion.js';
 import type { Antialias, BloomEnabled, CameraExposure, Tonemap } from './components/camera.js';
 import type { DynamicResolutionData } from './components/dynamic-resolution.js';
 import type { ScreenSpaceReflectionData } from './components/screen-space-reflection.js';
@@ -53,8 +60,9 @@ import type {
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types.js';
-import type { InstanceCollectionInspection, InstanceCollectionStore } from './instances.js';
+import type { InstanceCollectionInspection } from './instances.js';
 import type { RenderExtent } from './pipeline/render-extent.js';
+import type { PublishedRenderFrameInput, RenderPublicationIdentity } from './publication/contract';
 import type { RenderSceneBounds } from './scene/render-scene-types.js';
 import type { SsrAdmissionIdentity } from './ssr/identity.js';
 import type {
@@ -94,6 +102,7 @@ import type {
   GpuPassTimingOptions,
 } from './record/gpu-pass-timing/index.js';
 import type { VolumeTimingObservation } from './record/gpu-timing.js';
+import type { SurfaceDynamicInputFrame } from './surface/dynamic-input.js';
 import type { TemporalView } from './temporal/view.js';
 import type { VolumetricFogInspection } from './volume/inspection.js';
 
@@ -189,6 +198,8 @@ export interface CameraSnapshot {
     /** Target presentation rate; zero follows the accepted frame interval. */
     readonly targetFps?: number;
   };
+  /** Optional active-camera barrel projection, copied from the ECS schema. */
+  readonly barrelDistortion?: BarrelDistortionData;
 }
 
 /** Stable identity owned by the Standard feature host for output transform. */
@@ -370,6 +381,11 @@ export interface AtmosphereShaderSources {
  * and never reach into AssetRegistry or World.
  */
 export interface VolumetricFogFrameContext {
+  readonly additional?: readonly {
+    readonly densityTexture: Texture;
+    readonly densityView: TextureView;
+    readonly densityGeneration: number;
+  }[];
   readonly densityTexture: Texture;
   readonly densityView: TextureView;
   readonly paramsBuffer: Buffer;
@@ -407,8 +423,8 @@ export interface SpotLightProjectorFrameContext {
  * leases, receipts, inspection PODs, and recovery Result values.
  */
 export interface Renderer {
-  /** Renderer-owned authoring and update path for large instance collections. */
-  readonly instances: InstanceCollectionStore;
+  /** Publish one renderer-owned read-only Surface dynamic page for the next frame. */
+  setSurfaceDynamicInput(frame: SurfaceDynamicInputFrame | undefined): void;
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   /** Prepare a standard MeshAsset for the active device generation. */
   prepareDynamicGeometry(
@@ -431,7 +447,9 @@ export interface Renderer {
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
-  draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
+  draw(
+    input: RenderFrameInput | PublishedRenderFrameInput,
+  ): RenderResult<FrameReceipt, RenderError>;
   /**
    * Arm one upcoming submitted frame for explicit color-domain observation.
    * Observation buffers are not created, copied, mapped, or retained until a
@@ -499,6 +517,8 @@ export type RendererEvent =
       readonly kind: 'frame-submitted';
       readonly frameId: number;
       readonly deviceGeneration: number;
+      /** Compiled graph identity paired with the submitted picture. */
+      readonly graphGeneration?: number;
       /** The exact draw receipt, for observation when App owns the draw loop. */
       readonly receipt: FrameReceipt;
     };
@@ -553,13 +573,25 @@ export interface FrameObservationRequest {
 export interface FrameReceipt {
   readonly frameId: number;
   readonly deviceGeneration: number;
+  /** Whether this frame can present the active scene without a readiness fallback. */
+  readonly presentation: FramePresentation;
   /** Backend identity captured at submit and checked before observation. */
   readonly backendId?: RhiCaps['backendKind'];
   /** Monotonic compiled graph identity used by renderer-issued observations. */
   readonly graphGeneration?: number;
+  /**
+   * Effective output mapping for the submitted camera, including identity
+   * when this receipt has an accepted camera context. `undefined` means that
+   * no submitted display context is available; consumers must fail closed and
+   * must not infer identity or read the live World camera.
+   */
+  readonly barrelDistortion?: import('./barrel-distortion.js').BarrelDistortionMapping;
   readonly completed: Promise<RenderResult<void, RenderError>>;
 }
 
+/** Producer-derived presentation readiness for one submitted frame. */
+export type FramePresentation = 'pending' | 'ready';
+
 /**
  * The sole public draw input; World objects never cross this boundary. Render
  * owns extraction and graph interpretation, while the host owns encoding,
@@ -586,6 +618,12 @@ export interface RenderFrameInput {
   readonly fixedStep?: number;
   /** Optional profiler correlation token owned by App and consumed by Render. */
   readonly profileFrame?: ProfileFrameToken;
+  /**
+   * Select the geometry submission command lane while retaining the same
+   * extracted scene and material inputs. This is an acceptance/debug seam;
+   * both lanes remain subject to the ordinary resource and generation gates.
+   */
+  readonly geometryLane?: 'automatic' | 'direct';
 }
 
 /** Detached, bounded observation metadata tied to one FrameReceipt and request. */
@@ -719,8 +757,12 @@ export interface RenderInspection {
     readonly frameId: number;
     readonly deviceGeneration: number;
   };
+  /** Effective output mapping and accepted/LKG identity for the last picture. */
+  readonly barrelDistortion: import('./inspection-types').BarrelDistortionInspection;
   /** Renderer-owned authored volume projection and submit/LKG state. */
   readonly volumetricFog?: VolumetricFogInspection;
+  /** Renderer-owned procedural cloud projection from the latest resource-owner extract. */
+  readonly cloudLayer?: CloudLayerInspection;
   readonly features: readonly string[];
   /** Truthful lifecycle facts for every registered declarative feature. */
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
@@ -737,6 +779,10 @@ export interface RenderInspection {
   /** Standard MeshAsset dynamic-candidate lifecycle facts. */
   readonly dynamicGeometry?: DynamicGeometryInspection;
   readonly renderScene: RenderSceneInspection;
+  /** Detached logical allocation facts for graph-created render targets. */
+  readonly renderGraphResourceAllocation?: RenderGraphResourceAllocationInspection;
+  /** Detached logical allocation facts across graph generations. */
+  readonly renderGraphGenerationAllocation?: RenderGraphGenerationAllocationInspection;
   readonly reflectionProbes: ReflectionProbeInspection;
   /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */
   readonly ssrDependencies: SsrDependenciesInspection;
@@ -832,6 +878,7 @@ export type DrawOwnerOptions = {
   /** Explicit pause/resume or replay lifecycle boundary for temporal owners. */
   readonly temporalReset?: boolean;
   readonly profileFrame?: ProfileFrameToken;
+  readonly geometryLane?: 'automatic' | 'direct';
 };
 
 /** Information attached to a device-loss notification. */
@@ -1018,6 +1065,8 @@ export type RenderPhaseSkipReason =
 
 /** First-version options bag (intentionally empty; reserved for v0.1). */
 export interface RendererOptions {
+  /** Bind a source session before receiving any publication. */
+  readonly publicationSource?: RenderPublicationIdentity;
   /** Producer-owned features installed by the renderer host. */
   readonly features?: readonly RenderFeature<unknown>[] | undefined;
   /** Standard profile consumed by the single renderer-owned pipeline. */

package/src/render-graph-primitives.ts

@@ -586,7 +586,13 @@ function dispatchFullscreenPass(
         detail: { readsKey: reads[0] ?? 'ldrColor', passName: name },
       });
     }
-    recordFxaaPass(requireRenderGraphRecordContext(ctx), resolveCtx, graphPass, paramsOverride);
+    recordFxaaPass(
+      requireRenderGraphRecordContext(ctx),
+      resolveCtx,
+      graphPass,
+      paramsOverride,
+      graphOutputFormat,
+    );
     return;
   }
   const lookup = ctx.runtime.lookupPostProcess;

package/src/render-pipeline.ts

@@ -41,6 +41,7 @@ import type { DepthOfFieldSide } from './components/depth-of-field';
 import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type { RenderError } from './errors/render';
 import type { RenderFeatureTargetKind } from './features/targets';
+import type { RenderFeaturePlacement } from './features/types';
 import type { ShadowViewIdentity, ShadowViewProjection } from './gpu-driven/shadow-views';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
@@ -249,6 +250,8 @@ export interface RenderPipelineTopology {
           readonly useFar: boolean;
         }
       | undefined;
+    /** Shape-only barrel admission; numeric mapping stays per-frame data. */
+    readonly barrelDistortion?: boolean | undefined;
   };
   /** Frame-stable Standard output policy; no raw RHI handles enter topology. */
   readonly output?: {
@@ -285,6 +288,10 @@ export interface RenderPipelineTopology {
    */
   readonly volumetricFog?: {
     readonly enabled: boolean;
+    readonly additional?: readonly {
+      readonly format: TextureFormat;
+      readonly extent: { readonly width: number; readonly height: number; readonly depth: number };
+    }[];
     readonly lightKind?: 'directional' | 'point' | 'spot' | undefined;
     readonly lightEntity?: number | undefined;
     readonly pointLightEntity?: number | undefined;
@@ -333,6 +340,8 @@ export interface RenderPipelineTopology {
   readonly standardLightingTopologySignature?: string | undefined;
   /** Internal graph fact; renderer callers do not configure transmission demand. */
   readonly transmissionDemand?: TransmissionDemand | undefined;
+  /** Whether the extracted frame contains a single-layer medium Surface. */
+  readonly singleLayerMedium?: boolean | undefined;
 }
 
 /** Resolve the built-in final-output dither policy from the pipeline asset. */
@@ -463,9 +472,30 @@ export interface RenderPipelineGpuDrivenProjection {
     pass: RhiRenderPassEncoder,
     resources: GraphResourceResolver,
     frameResources: GpuDrivenStandardPbrFrameResources,
+    filter?: RenderPipelineGpuDrivenFilter,
+    fragmentEntryPoint?: string,
   ): void;
 }
 
+/** Material family selected by a typed scene pass for GPU-driven encoding. */
+export type RenderPipelineGpuDrivenFilter =
+  | 'opaque'
+  | 'deferred-opaque'
+  | 'forward-only-opaque'
+  | 'single-layer-medium';
+
+/** Graph-paired inputs available to a single-layer medium Surface pass. */
+export interface RenderPipelineSurfaceMediumPair {
+  /** The resolved opaque scene color produced by the shared Standard owner. */
+  readonly opaqueColor: GraphTextureView;
+  /** Raw depth copy is backend-dependent and remains explicit when unavailable. */
+  readonly rawDepth:
+    | { readonly status: 'available'; readonly view: GraphTextureView }
+    | {
+        readonly status: 'unavailable';
+        readonly reason: 'depth-copy-unavailable';
+      };
+}
 /** Exact scene rows selected by an indirect batch; palette offsets are global. */
 export interface GpuDrivenSceneMeshBinding {
   readonly meshBuffer: Buffer;
@@ -475,6 +505,8 @@ export interface GpuDrivenSceneMeshBinding {
 
 /** Producer-owned Standard PBR resources resolved during graph execution. */
 export interface GpuDrivenStandardPbrFrameResources {
+  /** Resource generation of the actual scene-index/indirect producer. */
+  readonly resourceGeneration?: number;
   readonly materialBindGroups: (BindGroup | undefined)[];
   /** Frame-global material slots keyed by the retained scene entity identity. */
   readonly materialSlotIndicesByEntity: Map<number, readonly number[]>;
@@ -485,6 +517,56 @@ export interface GpuDrivenStandardPbrFrameResources {
   colorFormats?: readonly TextureFormat[];
   /** Exact producer-owned numeric Material table consumed by scene-index PBR. */
   readonly sceneMaterialBuffer: Buffer;
+  /** Renderer-owned generic Surface page and frame/range metadata. */
+  readonly surfaceDynamicInput?: {
+    readonly page: Buffer;
+    readonly frame: Buffer;
+    readonly sharedFrame: Buffer;
+    readonly pageBytes: number;
+    readonly frameBytes: number;
+    readonly sharedFrameBytes: number;
+  };
+  /**
+   * Resolve the complete direct Surface slot-3 closure for one retained draw.
+   * The producer validates the stable draw identity and instance count before
+   * publishing a bind group; record never derives a frame-row address.
+   */
+  readonly surfaceDirectInstances?: (input: {
+    readonly worldId: number;
+    readonly entityKey: number;
+    readonly drawItemIndex: number;
+    readonly instanceCount: number;
+    readonly firstInstanceOrdinal?: number;
+    readonly instanceBuffer: Buffer;
+    readonly probeBuffer?: Buffer;
+    readonly probeOffset?: number;
+  }) => Result<
+    {
+      readonly bindGroup: BindGroup;
+      readonly dynamicOffsets: readonly number[];
+      readonly frameBase: number;
+      /** Public Surface member identities covered by the recorded command. */
+      readonly memberIds: readonly string[];
+    },
+    RhiError
+  >;
+  /** Frame-local sink fed only by actual Surface draw commands. */
+  readonly surfaceSubmissionObservation?: import('./surface/submission-observation').SurfaceSubmissionCandidate;
+  /** Existing Standard clustered group(2), supplied by the main-pass owner. */
+  clusterBindGroup?: BindGroup | undefined;
+  /** Rebind the same cluster resources around one batch-local mesh row page. */
+  clusterBindGroupForMesh?:
+    | ((meshBuffer: Buffer, bindingBytes: number) => BindGroup | undefined)
+    | undefined;
+  /** Rebind clustered lighting around the scene-index Mesh/Palette/Morph page. */
+  clusterBindGroupForSkin?:
+    | ((
+        meshBuffer: Buffer,
+        meshBindingBytes: number,
+        paletteBuffer: Buffer,
+        paletteBindingWindowBytes: number,
+      ) => BindGroup | undefined)
+    | undefined;
   resolveClusteredMeshBindGroup?: (binding: GpuDrivenSceneMeshBinding) => BindGroup;
 }
 
@@ -512,6 +594,8 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
    * inferring rgba16float support from the selected surface format.
    */
   readonly capabilities?: Pick<RhiCaps, 'rgba16floatRenderable'>;
+  /** Renderer-derived cloud shadow size shared by graph allocation and projection. */
+  readonly cloudShadowResolution?: number;
   /** Prepared typed graph resources owned by RenderSystem/RenderFrameState. */
   readonly standardOutput?: {
     readonly autoExposure?: {
@@ -541,6 +625,19 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     readonly currentStability: RenderPipelineTarget;
     readonly previousStability: RenderPipelineTarget;
   };
+  /**
+   * Renderer-owned CloudLayer transport history.  Each pair is backed by the
+   * same submit-fenced temporal owner as TAA, while the three attachments keep
+   * radiance, transmittance and representative depth in separate typed lanes.
+   */
+  readonly cloudHistory?: {
+    readonly currentRadiance: RenderPipelineTarget;
+    readonly previousRadiance: RenderPipelineTarget;
+    readonly currentTransmittance: RenderPipelineTarget;
+    readonly previousTransmittance: RenderPipelineTarget;
+    readonly currentDepth: RenderPipelineTarget;
+    readonly previousDepth: RenderPipelineTarget;
+  };
   /** Renderer-owned SSR temporal history targets for the admitted spatial chain. */
   readonly ssrHistory?: {
     readonly previous: RenderPipelineTarget;
@@ -573,6 +670,15 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     semanticTargets?: readonly RenderPipelineTarget[],
     namedTargets?: Readonly<Record<string, RenderPipelineTarget>>,
     standardSurfaceAccesses?: readonly GraphAccess[],
+    featureSelectionOrPlacement?:
+      | {
+          /** Project only these identities at this ordered stage. */
+          readonly include?: readonly string[];
+          /** Keep these identities for a later ordered stage. */
+          readonly exclude?: readonly string[];
+        }
+      | RenderFeaturePlacement,
+    passNames?: readonly string[],
   ): Result<void, RenderPipelineBuildError>;
   /** Prepare feature-owned shadow draws and their early compute producers once. */
   contributeShadowFeatures?(): Result<
@@ -585,6 +691,30 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
   ): Result<void, RenderPipelineBuildError>;
   /** Whether a producer-owned feature is installed for this graph build. */
   hasFeature?(identity: string): boolean;
+  /** Whether a producer-owned feature has executable work at this graph build. */
+  hasFeatureWork?(identity: string, placement?: RenderFeaturePlacement): boolean;
+  /** Whether a producer-owned feature has a resolved raster pass this frame. */
+  hasFeatureRasterWork?(identity: string, placement?: RenderFeaturePlacement): boolean;
+}
+
+/** Project the six CloudLayer history attachments into feature target aliases. */
+export function renderPipelineCloudHistoryTargets(input: {
+  readonly currentRadiance: RenderPipelineTarget;
+  readonly previousRadiance: RenderPipelineTarget;
+  readonly currentTransmittance: RenderPipelineTarget;
+  readonly previousTransmittance: RenderPipelineTarget;
+  readonly currentDepth: RenderPipelineTarget;
+  readonly previousDepth: RenderPipelineTarget;
+}): readonly RenderPipelineFeatureTarget[] {
+  const entries: readonly (readonly [string, RenderPipelineTarget])[] = [
+    ['cloud-history-radiance-previous', input.previousRadiance],
+    ['cloud-history-radiance-current', input.currentRadiance],
+    ['cloud-history-transmittance-previous', input.previousTransmittance],
+    ['cloud-history-transmittance-current', input.currentTransmittance],
+    ['cloud-history-depth-previous', input.previousDepth],
+    ['cloud-history-depth-current', input.currentDepth],
+  ];
+  return entries.map(([name, target]) => ({ name, kind: 'scene-color' as const, ...target }));
 }
 
 export type RenderPipelineBuildError = RenderGraphError | RenderError | RhiError;