@forgeax/engine-render 0.1.27 → 0.1.29

package/src/record/render-context.ts

@@ -15,6 +15,7 @@ import type {
   RhiDevice,
   RenderPipeline as RhiRenderPipeline,
   Sampler,
+  ShaderModule,
   Texture,
   TextureFormat,
   TextureView,
@@ -40,6 +41,9 @@ import type { MeshGpuHandles } from '../device/gpu-residency';
 import type { EngineMetrics } from '../engine-metrics';
 import type { RenderFeatureHost } from '../features/host';
 import type { RenderFeatureShaderModuleMode } from '../features/types';
+import type { GpuDrivenPbrProgram } from '../gpu-driven/pbr-program';
+import type { GpuDrivenShadowBatchProjection } from '../gpu-driven/production-raster';
+import type { ShadowViewStatePool } from '../gpu-driven/shadow-views';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
@@ -56,7 +60,9 @@ import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
 import type { ReflectionProbeTable } from '../reflection/gpu-table';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
+import type { FrameObservationDomain } from '../render-contract';
 import type { SsrAdmissionIdentity } from '../ssr/identity';
+import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
 import type { GpuPassTimingReason } from './gpu-pass-timing/errors';
 import type {
   GpuPassTimingCapture,
@@ -109,27 +115,19 @@ export interface MaterialShaderPipelineEntry {
   readonly group2Contract: PipelineGroup2Contract;
 }
 
-/**
- * Armed only for the first published recovery frame. Candidate preparation
- * must make every pipeline and static residency lookup a cache hit before this
- * guard is armed; a miss is a hard failure before queue submission.
- */
-export interface RecoveryColdWorkGuard {
-  arm(): void;
-  notePipelineColdWork(): void;
-  noteUploadColdWork(): void;
-  finish(): void;
-}
-
 import type {
+  AtmosphereShaderSources,
   RenderDebugOverlay,
   RenderPipelineContext,
   RenderRecordPhase,
+  SsrShaderSources,
   VolumetricFogShaderSources,
 } from '../render-contract';
+import type { GpuDrivenStandardPbrFrameResources } from '../render-pipeline';
 import type {
   DispatchEntry,
   MaterialSnapshot,
+  ShadowCasterMembership,
   SkyboxSnapshot,
   SkylightSnapshot,
 } from '../render-system-extract';
@@ -148,9 +146,25 @@ import type { FoldDispatchPlan } from './mesh-ssbo';
 
 export interface RenderSystemRuntime {
   readonly device: RhiDevice;
+  /** Current renderer device generation used to fence receipt-bound captures. */
+  readonly deviceGeneration?: number;
+  /** Public receipt identity reserved before graph encoding. */
+  readonly observationFrameId?: number | undefined;
+  /** Graph identity written by the typed graph for the current receipt. */
+  observationGraphGeneration?: number | undefined;
+  /** Renderer-owned capture bridge consumed after queue submission. */
+  readonly observationCaptureOwner?:
+    | {
+        register(capture: TypedFrameObservationCapture): void;
+        consume(frameNumber: number): readonly TypedFrameObservationCapture[];
+        drain(): readonly TypedFrameObservationCapture[];
+      }
+    | undefined;
   /** Internal backend-fixture hook evaluated at the submit transaction edge. */
   readonly beforeSubmit?: ((device: RhiDevice) => RhiError | undefined) | undefined;
   readonly deviceScope: DeviceScope;
+  /** Domains explicitly armed for the frame being encoded. */
+  readonly observationCaptureDomains?: readonly FrameObservationDomain[] | undefined;
   /** Resolve a recorder/backend wrapper before configuring the native surface. */
   readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
   readonly errorRegistry: RhiErrorListenerRegistry;
@@ -164,6 +178,7 @@ export interface RenderSystemRuntime {
   /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
   readonly getMaterialShaderArtifact?: (
     materialShaderId: string,
+    vertexColorAvailable?: boolean,
   ) => MaterialShaderArtifact | undefined;
   readonly getMaterialShaderPipeline?: (
     materialShaderId: string,
@@ -181,10 +196,14 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin',
+    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    /** Optional vertex entry override for receipt-owned scene-index passes. */
+    vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
     vertexEntry?: string,
     fragmentEntry?: string,
+    particleInputLanes?: number,
+    fragmentConstants?: Readonly<Record<string, number>>,
   ) => RhiRenderPipeline | null;
   readonly getMaterialShaderPipelineEntry?: (
     materialShaderId: string,
@@ -203,21 +222,33 @@ export interface RenderSystemRuntime {
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: 'pbr' | 'pbr-skin',
+    /** Optional vertex entry override for receipt-owned scene-index passes. */
+    vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
     vertexEntry?: string,
     fragmentEntry?: string,
+    particleInputLanes?: number,
+    fragmentConstants?: Readonly<Record<string, number>>,
   ) => MaterialShaderPipelineEntry | null;
   /** Reflection-derived UV count included in the material PipelineSpec cache key. */
   readonly getMaterialShaderUvSetCount?: (materialShaderId: string) => number | undefined;
   readonly getMaterialShaderBindingContract?: (
     materialShaderId: string,
-  ) => 'group-0' | 'group-0-resource' | 'view-only' | 'view-and-scene-depth' | 'render-material';
+  ) =>
+    | 'group-0'
+    | 'group-0-resource'
+    | 'view-only'
+    | 'view-and-scene-depth'
+    | 'render-material-with-scene-depth'
+    | 'render-material-and-scene-depth'
+    | 'render-material';
   readonly getParamSchema?: (materialShaderId: string) => readonly ParamSchemaEntry[] | undefined;
   readonly getMaterialBindGroupLayout?: (
     materialShaderId: string,
     materialParamSchema?: readonly ParamSchemaEntry[],
   ) => BindGroupLayout | undefined;
-  recoveryColdWorkGuard?: RecoveryColdWorkGuard | undefined;
+  /** Handle-first factory for built-in same-frame GPU producers. */
+  readonly immediateShaderModuleFactory?: PipelineBuilderShaderModuleFactory;
   readonly metrics: EngineMetrics;
   readonly lookupPostProcess?: (
     id: string,
@@ -226,7 +257,7 @@ export interface RenderSystemRuntime {
   readonly getPostProcessPipeline?: (
     id: string,
     bgl: BindGroupLayout,
-    colorFormat: GPUTextureFormat,
+    colorFormats: readonly GPUTextureFormat[],
     entry?: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
   /** Candidate-owned post-process pipelines transferred at publication. */
@@ -371,13 +402,24 @@ export interface PipelineState {
   readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
-  readonly nearestSampler: Sampler;
   readonly fallbackTextureView: TextureView;
   readonly unlitPipeline: RhiRenderPipeline | null;
   readonly standardPipeline: RhiRenderPipeline | null;
+  /** Producer-owned Standard PBR module for this device generation. */
+  readonly standardPbrShaderModule: ShaderModule | null;
+  /** Producer-owned skinned Standard PBR module for this device generation. */
+  readonly pbrSkinShaderModule: ShaderModule | null;
+  /** Producer-resolved Standard PBR UV ABI count for geometry projection. */
+  readonly standardPbrShaderUvSetCount: number;
   readonly unlitPipelineMsaa: RhiRenderPipeline | null;
   readonly unlitPipelineHdrMsaa: RhiRenderPipeline | null;
   readonly pbrPipelineLayout: PipelineLayout | null;
+  /** Dedicated slot-3 layout for scene-index GPU-driven Standard PBR draws. */
+  readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+  readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
+  /** Device-owned shader modules paired with their exact Standard PBR receipts. */
+  readonly gpuDrivenPbrPrograms?: ReadonlyMap<string, GpuDrivenPbrProgram>;
+  readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
   readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
   readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
@@ -453,7 +495,7 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
     | ((
         entry: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
         bgl: BindGroupLayout,
-        colorFormat: GPUTextureFormat,
+        colorFormats: readonly GPUTextureFormat[],
         label: string,
       ) => RhiRenderPipeline | null)
     | undefined;
@@ -469,6 +511,10 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   ) => void;
   /** Composed renderer utility sources installed atomically at build-ready. */
   volumetricFogShaders?: VolumetricFogShaderSources | undefined;
+  /** Composed renderer utility sources installed atomically at build-ready. */
+  ssrShaders?: SsrShaderSources | undefined;
+  /** Composed renderer utility sources installed atomically at build-ready. */
+  atmosphereShaders?: AtmosphereShaderSources | undefined;
 }
 
 export interface _StandardForwardSceneView {
@@ -492,9 +538,6 @@ export interface _StandardForwardSceneView {
   readonly profilePhase?: <T>(phase: RenderRecordPhase, action: () => T) => T;
   readonly directionalShadowCacheReuse: boolean;
   readonly world: World;
-  readonly gpuDrivenEntityKeys: ReadonlySet<number>;
-  /** Renderer-local world namespace paired with gpuDrivenEntityKeys. */
-  readonly gpuDrivenWorldKeys?: readonly number[];
   readonly tonemapActive: boolean;
   readonly geometryColorView: TextureView | null;
   readonly geometryDepthView: TextureView | null;
@@ -513,10 +556,37 @@ export interface _StandardForwardSceneView {
   readonly foldDispatchPlan: FoldDispatchPlan | null;
   readonly materialSlotIndices: readonly (readonly number[])[];
   readonly materialSlots: readonly MaterialSnapshot[];
-  readonly materialSlotOwners: readonly number[];
+  readonly materialSlotOwners: readonly ValidatedRenderable[];
   readonly materialSlotCount: number;
+  /** Filled by main-pass material producers before the GPU-driven raster tail. */
+  readonly gpuDrivenStandardPbrFrameResources?: GpuDrivenStandardPbrFrameResources;
+  /** Scene table retained by the renderer even when no draw is GPU-admitted. */
+  readonly gpuDrivenSceneMaterialBuffer?: Buffer;
+  /** Concrete main-pass draw identities already claimed by the capable GPU lane. */
+  readonly gpuDrivenDrawKeys?: ReadonlySet<string>;
+  readonly gpuDrivenShadowViews?: ShadowViewStatePool;
+  readonly gpuDrivenShadowBatchProjections?: ReadonlyMap<
+    string,
+    ReadonlyMap<number, GpuDrivenShadowBatchProjection>
+  >;
+  /** Concrete ShadowCaster keys already claimed by the capable GPU subset. */
+  readonly gpuDrivenShadowDrawKeys?: ReadonlySet<string>;
+  /** View-scoped ShadowCaster claims for exact CPU residual routing. */
+  readonly gpuDrivenShadowDrawKeysByView?: ReadonlyMap<string, ReadonlySet<string>>;
+  /** Extracted structured ShadowCaster ownership facts. */
+  readonly shadowCasterMembership?: readonly ShadowCasterMembership[];
+  /** Complete retained ShadowCaster rows, including camera-culled casters. */
+  readonly shadowValidatedOrdered?: readonly ValidatedRenderable[];
+  /** Dispatch entries remapped to the complete retained ShadowCaster rows. */
+  readonly shadowDispatch?: readonly DispatchEntry[];
+  /** Mesh-SSBO slot base reserved for the retained ShadowCaster rows. */
+  readonly shadowMeshSsboBase?: number;
+  /** Renderer-stable world keys used by ShadowCaster ownership identities. */
+  readonly shadowCasterWorldKeys?: readonly number[];
   readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
+  /** Record-stage proof callback; invoked only after a real draw command is encoded. */
+  readonly onRenderableDraw?: (entry: ValidatedRenderable) => void;
   readonly reflectionProbes?: ReflectionProbeRecordState;
   materialUboPayloadCache?: {
     readonly materialSlots: readonly MaterialSnapshot[];