@forgeax/engine-render 0.1.21 → 0.1.24

package/src/record/render-context.ts

@@ -20,7 +20,11 @@ import type {
   TextureView,
 } from '@forgeax/engine-rhi';
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
-import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  type MaterialRuntimeArtifact,
+  type MaterialShaderArtifact,
+} from '@forgeax/engine-shader';
 import type {
   MaterialRenderState,
   ParamSchemaEntry,
@@ -28,6 +32,7 @@ import type {
   PrimitiveTopology,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
 import type { MaterialRenderProjection } from '../assembly/material/assembly';
 import type { DeviceScope } from '../device/device-scope';
 import type { MeshGpuHandles } from '../device/gpu-residency';
@@ -50,6 +55,7 @@ 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 { SsrAdmissionIdentity } from '../ssr/identity';
 import type { GpuPassTimingReason } from './gpu-pass-timing/errors';
 import type {
   GpuPassTimingCapture,
@@ -68,7 +74,33 @@ export interface ReflectionProbeRecordState {
   readonly table: ReflectionProbeTable;
   readonly selections: ReadonlyMap<string, ReflectionProbeSelectionResult>;
   readonly graph: import('./typed-frame-graph').ReflectionProbeGraphState;
-  readonly completeSubmission: (submitted: boolean, completed?: Promise<unknown>) => void;
+  /** Detached committed fallback projections joined by main-pass renderable key. */
+  readonly fallbackProjections?: ReadonlyMap<
+    string,
+    import('../inspection-types').ReflectionFallbackReceipt
+  >;
+  /** Demand is derived from this frame's renderable/source selection. */
+  readonly fallbackDemand?: boolean;
+  /** True when at least one selected row must prove a non-zero readback. */
+  readonly fallbackHasNonNeutral?: boolean;
+  readonly completeSubmission: (
+    submitted: boolean,
+    completed?: Promise<unknown>,
+    fallbackOutput?: {
+      readonly format: TextureFormat;
+      readonly size: { readonly width: number; readonly height: number };
+      readonly frameId: number;
+      readonly graphGeneration: number;
+      readonly textureIdentity: number;
+      readonly readback?: Promise<{
+        readonly linearHdr: readonly [number, number, number, number];
+        readonly hash: string;
+        readonly graphGeneration: number;
+        readonly textureIdentity: number;
+      }>;
+    },
+    fallbackRequested?: boolean,
+  ) => Promise<void>;
 }
 
 export interface MaterialShaderPipelineEntry {
@@ -76,6 +108,18 @@ 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 {
   RenderDebugOverlay,
   RenderPipelineContext,
@@ -103,12 +147,20 @@ import type { FoldDispatchPlan } from './mesh-ssbo';
 
 export interface RenderSystemRuntime {
   readonly device: RhiDevice;
+  /** Internal backend-fixture hook evaluated at the submit transaction edge. */
+  readonly beforeSubmit?: ((device: RhiDevice) => RhiError | undefined) | undefined;
   readonly deviceScope: DeviceScope;
+  /** Resolve a recorder/backend wrapper before configuring the native surface. */
+  readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
   readonly errorRegistry: RhiErrorListenerRegistry;
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly healthRegistry: HealthListenerRegistry;
   readonly getMaterialProjection?: (materialGuid: string) => MaterialRenderProjection | undefined;
   readonly getMaterialArtifact?: (specializationKey: string) => MaterialRuntimeArtifact | undefined;
+  /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
+  readonly getMaterialShaderArtifact?: (
+    materialShaderId: string,
+  ) => MaterialShaderArtifact | undefined;
   readonly getMaterialShaderPipeline?: (
     materialShaderId: string,
     isHdr: boolean,
@@ -126,6 +178,7 @@ export interface RenderSystemRuntime {
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: 'pbr' | 'pbr-skin',
+    additionalColorFormats?: readonly GPUTextureFormat[],
   ) => RhiRenderPipeline | null;
   readonly getMaterialShaderPipelineEntry?: (
     materialShaderId: string,
@@ -143,12 +196,20 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
+    layoutKindOverride?: 'pbr' | 'pbr-skin',
+    additionalColorFormats?: readonly GPUTextureFormat[],
   ) => 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';
   readonly getParamSchema?: (materialShaderId: string) => readonly ParamSchemaEntry[] | undefined;
-  readonly getMaterialBindGroupLayout?: (materialShaderId: string) => BindGroupLayout | undefined;
+  readonly getMaterialBindGroupLayout?: (
+    materialShaderId: string,
+    materialParamSchema?: readonly ParamSchemaEntry[],
+  ) => BindGroupLayout | undefined;
+  recoveryColdWorkGuard?: RecoveryColdWorkGuard | undefined;
   readonly metrics: EngineMetrics;
   readonly lookupPostProcess?: (
     id: string,
@@ -160,6 +221,8 @@ export interface RenderSystemRuntime {
     colorFormat: GPUTextureFormat,
     entry?: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
+  /** Candidate-owned post-process pipelines transferred at publication. */
+  readonly getRecoveryPostProcessPipelines?: () => ReadonlyMap<string, RhiRenderPipeline>;
   readonly clearPostProcessPipelineCache?: (id: string) => void;
   readonly invalidateShaderModule?: (label: string) => void;
   readonly dynamicTextureStore?: DynamicTextureStore | undefined;
@@ -295,9 +358,9 @@ export interface PipelineState {
   readonly shadowCasterCascadeBuffer: Buffer;
   readonly materialUniformBuffer: { readonly buffer: Buffer; readonly sizeInBytes: number };
   readonly meshStorageBuffer: { readonly buffer: Buffer; readonly sizeInBytes: number };
-  readonly pointLightsBuffer: Buffer;
-  readonly spotLightsBuffer: Buffer;
   readonly instancesBindGroupLayout: BindGroupLayout;
+  /** Probe-enabled slot-3 layout; omitted from no-probe bind groups. */
+  readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
   readonly nearestSampler: Sampler;
@@ -307,19 +370,37 @@ export interface PipelineState {
   readonly unlitPipelineMsaa: RhiRenderPipeline | null;
   readonly unlitPipelineHdrMsaa: RhiRenderPipeline | null;
   readonly pbrPipelineLayout: PipelineLayout | null;
+  readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
+  readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
   readonly hdrpClusterMembershipPipeline: ComputePipeline | null;
   readonly hdrpClusterMembershipBindGroupLayout: BindGroupLayout | null;
   readonly pbrSkinPipelineLayout: PipelineLayout | null;
+  readonly pbrSkinProbePipelineLayout?: PipelineLayout | null;
   readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
   readonly hdrpSkinPipelineLayout: PipelineLayout | null;
   readonly hdrpSkinMeshBindGroupLayout: BindGroupLayout | null;
   readonly skinPaletteAllocator: SkinPaletteAllocator | null;
   readonly defaultWhiteTextureView: TextureView;
   readonly defaultNormalTextureView: TextureView;
+  /** Missing anisotropy maps encode a neutral direction and unit strength. */
+  readonly defaultAnisotropyTextureView?: TextureView;
   readonly unlitPipelineHdr: RhiRenderPipeline | null;
   readonly shadowFallbackTextureView: TextureView;
   readonly shadowAtlasFallbackTextureView: TextureView;
+  readonly extendedLightingAvailable?: boolean;
+  readonly iesProfileTexture?: Texture;
+  readonly cookieTexture?: Texture;
+  readonly cookieMatrixBuffer?: Buffer;
+  spotModifierUploadState?: {
+    readonly ies: Map<number, number>;
+    readonly cookie: Map<number, number>;
+    readonly cookieMatrix: Map<number, number>;
+  };
+  readonly iesProfileTextureView?: TextureView;
+  readonly cookieTextureView?: TextureView;
+  readonly ltcLambertTextureView?: TextureView;
+  readonly ltcGgxTextureView?: TextureView;
   readonly shadowParamsBuffer: Buffer;
   readonly skylightFallback: SkylightFallback | null;
   readonly perPassResources: PerPassResources;
@@ -327,9 +408,15 @@ export interface PipelineState {
 
 export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+  /** Build identity injected by the host's build-tool adapter. */
+  readonly build?: string | undefined;
+  /** Host identity binding for the renderer-owned SSR dependency seam. */
+  readonly ssrIdentity?: SsrAdmissionIdentity | undefined;
   readonly standardProfile?: StandardProfile | undefined;
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
+  /** Install a detached feature host only at the recovery publication boundary. */
+  readonly setFeatureHost?: ((host: RenderFeatureHost) => void) | undefined;
   readonly shaderModuleFactory?: PipelineBuilderShaderModuleFactory;
   readonly createShaderModule?: (
     device: import('@forgeax/engine-rhi').RhiDevice,
@@ -398,6 +485,8 @@ export interface _StandardForwardSceneView {
   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;
@@ -406,6 +495,8 @@ export interface _StandardForwardSceneView {
   readonly splitLdrSprite: boolean;
   readonly ldrSpritePassView: TextureView | null;
   readonly transparentColorFormat?: GPUTextureFormat;
+  /** Second Standard main-pass attachment used by the fallback producer. */
+  readonly reflectionFallbackColorFormat?: GPUTextureFormat;
   readonly dispatch: readonly DispatchEntry[];
   readonly hdrpClusterBindGroup: BindGroup | null;
   readonly hdrpClusterMembershipBindGroup: BindGroup | null;
@@ -425,14 +516,15 @@ export interface _StandardForwardSceneView {
     readonly payload: Uint8Array;
   };
   hdrpSsaoBlurredView?: TextureView;
+  readonly occlusion?: import('../scene/visibility/occlusion-runtime').OcclusionFrameProjection;
 }
 
 export type _InternalRenderPipelineContext = RenderPipelineContext & _StandardForwardSceneView;
 
 export type RecordProfileRunner = <T>(phase: RenderRecordPhase, action: () => T) => T;
 
-export const STANDARD_PBR_UBO_SIZE = 384;
-export const MATERIAL_PER_ENTITY_STRIDE = 512;
+export const STANDARD_PBR_UBO_SIZE = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA).uboLayout.totalBytes;
+export const MATERIAL_PER_ENTITY_STRIDE = Math.ceil(STANDARD_PBR_UBO_SIZE / 256) * 256;
 
 export type SwapChainFormatPair = {
   readonly storage: GPUTextureFormat;

package/src/record/shadow-pass.ts

@@ -23,12 +23,13 @@ import {
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline';
+import { COOKIE_MATRIX_BYTES } from '../prepare/extended-lighting/resources';
 import type { DispatchEntry, ExtractedLights } from '../render-system-extract';
 import { matchPass } from '../systems/pass-selector';
 import { worldEntityKey } from './frame-snapshot';
+import { resolveGeometryInstancesBindGroup } from './main-pass-geometry';
 import {
   getOrCreateFromChain,
-  getOrCreatePerEntity,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
   MESH_SSBO_BYTES,
@@ -83,23 +84,79 @@ function ensureTypedShadowViewBg(
   const { runtime, frameState, pipelineState } = c;
   const shadowSampler = pipelineState.perPassResources.shadowSampler;
   if (shadowSampler === null) return null;
+  const extendedLighting = pipelineState.extendedLightingAvailable ?? false;
+  const iesProfileTextureView = pipelineState.iesProfileTextureView;
+  const cookieTextureView = pipelineState.cookieTextureView;
+  const cookieMatrixBuffer = pipelineState.cookieMatrixBuffer;
+  const ltcLambertTextureView = pipelineState.ltcLambertTextureView;
+  const ltcGgxTextureView = pipelineState.ltcGgxTextureView;
+  const extendedLightingCacheKeys: object[] = [];
+  const extendedLightingEntries: BindGroupEntry[] = [];
+  if (extendedLighting) {
+    if (
+      iesProfileTextureView === undefined ||
+      cookieTextureView === undefined ||
+      cookieMatrixBuffer === undefined ||
+      ltcLambertTextureView === undefined ||
+      ltcGgxTextureView === undefined
+    ) {
+      return null;
+    }
+    extendedLightingCacheKeys.push(
+      pipelineState.defaultSampler,
+      iesProfileTextureView,
+      cookieTextureView,
+      ltcLambertTextureView,
+      ltcGgxTextureView,
+      cookieMatrixBuffer,
+    );
+    extendedLightingEntries.push(
+      {
+        binding: 9,
+        resource: { kind: 'sampler', value: pipelineState.defaultSampler },
+      },
+      {
+        binding: 11,
+        resource: { kind: 'textureView', value: iesProfileTextureView },
+      },
+      {
+        binding: 12,
+        resource: { kind: 'textureView', value: cookieTextureView },
+      },
+      {
+        binding: 13,
+        resource: { kind: 'textureView', value: ltcLambertTextureView },
+      },
+      {
+        binding: 14,
+        resource: { kind: 'textureView', value: ltcGgxTextureView },
+      },
+      {
+        binding: 15,
+        resource: {
+          kind: 'buffer',
+          value: { buffer: cookieMatrixBuffer, size: COOKIE_MATRIX_BYTES },
+        },
+      },
+    );
+  }
   const projectorAvailable = pipelineState.projectorAvailable !== false;
   try {
     return getOrCreateFromChain(
       frameState.viewBindGroupCache,
       [
         pipelineState.viewUniformBuffer,
-        pipelineState.pointLightsBuffer,
-        pipelineState.spotLightsBuffer,
         pipelineState.shadowFallbackTextureView,
         shadowSampler,
         pipelineState.shadowAtlasFallbackTextureView,
         pipelineState.shadowParamsBuffer,
         pipelineState.shadowCasterCascadeBuffer,
         pipelineState.shadowFallbackTextureView,
-        ...(projectorAvailable
-          ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
-          : []),
+        ...(extendedLighting
+          ? extendedLightingCacheKeys
+          : projectorAvailable
+            ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
+            : []),
         pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
       ],
       variant,
@@ -119,14 +176,6 @@ function ensureTypedShadowViewBg(
                 },
               },
             },
-            {
-              binding: 1,
-              resource: { kind: 'buffer', value: { buffer: pipelineState.pointLightsBuffer } },
-            },
-            {
-              binding: 2,
-              resource: { kind: 'buffer', value: { buffer: pipelineState.spotLightsBuffer } },
-            },
             {
               binding: 3,
               resource: { kind: 'textureView', value: pipelineState.shadowFallbackTextureView },
@@ -161,6 +210,7 @@ function ensureTypedShadowViewBg(
               binding: 8,
               resource: { kind: 'textureView', value: pipelineState.shadowFallbackTextureView },
             },
+            ...extendedLightingEntries,
             {
               binding: 10,
               resource: {
@@ -171,7 +221,7 @@ function ensureTypedShadowViewBg(
                 },
               },
             },
-            ...(projectorAvailable
+            ...(!extendedLighting && projectorAvailable
               ? [
                   {
                     binding: 11,
@@ -671,31 +721,7 @@ function recordShadowCasterDraws(
     // handle = shadowInstanceBuffer; the HDRP main pass read end (:3820 below)
     // must look up the same (compositeKey, instBuffer) leaf or the shadow
     // instances silently drop.
-    const shadowInstancesBg = getOrCreatePerEntity(
-      c.frameState.instancesBgPerEntity,
-      worldEntityKey(entry.source.worldId, entry.source.entityKey),
-      [shadowInstanceBuffer],
-      'shadow-instances',
-      () => {
-        const result = runtime.device.createBindGroup({
-          label: 'shadow-instances-bg',
-          layout: pipelineState.instancesBindGroupLayout,
-          entries: [
-            {
-              binding: 0,
-              resource: {
-                kind: 'buffer',
-                value: { buffer: shadowInstanceBuffer },
-              },
-            },
-          ],
-        });
-        if (!result.ok) throw result.error;
-        return result.value;
-      },
-      c.bindGroupCounts,
-    );
-
+    const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);
     shadowPass.setBindGroup(3, shadowInstancesBg);
     // feat-20260608 M4 / w16: per-submesh shadow draw loop.
     // Only draw submeshes whose topology is triangle-list or triangle-strip