@forgeax/engine-render 0.1.28 → 0.1.30

package/src/record/dynamic-geometry-consumption.ts

@@ -0,0 +1,59 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { RenderFrameState, ValidatedRenderable } from './frame-snapshot';
+
+/** Capture the render-stage mesh binding used by the current submitted frame. */
+export function createDynamicGeometryConsumptionRecorder(
+  worlds: readonly World[],
+  bindings: WeakMap<World, Map<number, number>>,
+): (entry: ValidatedRenderable) => void {
+  return (entry) => {
+    const renderable = entry.source;
+    const world = worlds[renderable.worldId];
+    if (world === undefined) return;
+    let worldBindings = bindings.get(world);
+    if (worldBindings === undefined) {
+      worldBindings = new Map();
+      bindings.set(world, worldBindings);
+    }
+    worldBindings.set(renderable.entityKey, renderable.assetHandle);
+  };
+}
+
+export interface DynamicGeometryFrameBindings {
+  begin(): void;
+  onRenderableDraw(worlds: readonly World[]): (entry: ValidatedRenderable) => void;
+  commit(submitted: boolean): void;
+  isConsumed(world: World, entity: number, meshHandle: number | undefined): boolean;
+}
+
+/** Own the submitted-frame receipt used by dynamic-geometry publication. */
+export function createDynamicGeometryFrameBindings(): DynamicGeometryFrameBindings {
+  let submitted = new WeakMap<World, ReadonlyMap<number, number>>();
+  let pending = new WeakMap<World, Map<number, number>>();
+  return {
+    begin(): void {
+      submitted = new WeakMap();
+      pending = new WeakMap();
+    },
+    onRenderableDraw(worlds): (entry: ValidatedRenderable) => void {
+      return createDynamicGeometryConsumptionRecorder(worlds, pending);
+    },
+    commit(didSubmit): void {
+      if (didSubmit) submitted = pending;
+    },
+    isConsumed(world, entity, meshHandle): boolean {
+      if (!Number.isInteger(entity) || meshHandle === undefined) return false;
+      return submitted.get(world)?.get(entity) === meshHandle;
+    },
+  };
+}
+
+/** Drop temporal history after a dynamic-geometry topology replacement. */
+export function resetDynamicGeometryTemporalHistory(frameState: RenderFrameState): void {
+  frameState.temporalFrameTransaction.reset('signature-change');
+  frameState.temporalFrame = undefined;
+  frameState.temporalFrameInput = undefined;
+  frameState.lastSuccessfulTemporalView = undefined;
+  frameState.successfulTemporalFrameIndex = 0;
+  frameState.pendingTemporalCommit = { kind: 'none' };
+}

package/src/record/frame-lighting.ts

@@ -58,7 +58,7 @@ import {
   ShadowAtlas,
 } from '../shadow-atlas';
 import { getOrCreateSsaoBuffers } from '../ssao-buffers';
-import { getSsaoParameters } from '../ssao-config';
+import { getSsaoParameters, SSAO_SAMPLE_COUNTS } from '../ssao-config';
 // extendedLighting keeps Spot modifier factors on the existing light record
 // path; no additional render pass or submit owner is introduced.
 import type { BindGroupCounts, RenderFrameState } from './frame-snapshot';
@@ -137,8 +137,8 @@ function mapClusterUploadFailure(
  * verbatim from `recordFrame`. Walks the handle-identity WeakMap caches
  * (feat-20260531 M2 + feat-20260622 M3) to resolve or lazily create the view
  * (@group 0), mesh (@group 2), and — when HDRP is active — HDRP-unified cluster
- * bind groups. Returns all three (null when `hasValidated` is false, the Case E
- * clear-pass-only path). No new mutable state: `bindGroupCounts` accounting +
+ * bind groups. Raster groups may be null with no validated meshes; the Cluster
+ * producer follows the accepted lighting topology independently. `bindGroupCounts` accounting +
  * cache maps are threaded through explicitly.
  *
  * @internal
@@ -181,10 +181,12 @@ export function buildPerFrameBindGroups(
   const clusteredLighting = standardLighting?.kind === 'clustered';
   const membershipLayout = pipelineState.hdrpClusterMembershipBindGroupLayout;
   const membership = frameState.hdrpClusterMembership;
-  const expectedHdrpBuffers =
-    hasValidated && clusteredLighting
-      ? getOrCreateHdrpBuffers(internals, frameState.installedPipelineConfig?.clusterGrid)
-      : null;
+  // The graph's Cluster producer also serves RenderFeature consumers and
+  // warmup frames with no ordinary meshes. Its lifetime follows the accepted
+  // lighting topology, not the ordinary raster validation count.
+  const expectedHdrpBuffers = clusteredLighting
+    ? getOrCreateHdrpBuffers(internals, frameState.installedPipelineConfig?.clusterGrid)
+    : null;
   const currentMembership =
     expectedHdrpBuffers !== null &&
     membership?.clusterGridBuffer === expectedHdrpBuffers.clusterGridBuffer
@@ -332,7 +334,7 @@ export function buildPerFrameBindGroups(
             },
             // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1:
             // shadowParams UBO (`array<vec4<f32>, 4>` = 64 B). Lane N
-            // stores `(near, far, 1/(far-near), 0)` for the point light
+            // stores `(near, far, depthBias, normalBias)` for the point light
             // with shadowAtlasLayer === N. Updated per frame from
             // `pointShadowSnapshots` below.
             {
@@ -829,7 +831,7 @@ export function writeSpotModifierTextures(
  * binding 6), extracted verbatim from `recordFrame`.
  *
  * feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1: 4 lanes x vec4<f32>;
- * lane[shadowAtlasLayer] = (near, far, 1/(far-near), 0). Lanes for non-shadow
+ * lane[shadowAtlasLayer] = (near, far, depthBias, normalBias). Lanes for non-shadow
  * slots stay zero (the WGSL sample path is gated by PointLight.shadowAtlasLayer
  * >= 0). Always writes the full 64 B so stale non-zero lanes from a previous
  * frame's allocation cannot poison the current frame.
@@ -854,11 +856,10 @@ export function writeShadowParamsBuffer(
     const base = layer * SHADOW_PARAMS_FLOATS_PER_LANE;
     const near = ps.nearPlane;
     const far = ps.farPlane;
-    const invSpan = far > near ? 1 / (far - near) : 0;
     shadowParamsArr[base] = near;
     shadowParamsArr[base + 1] = far;
-    shadowParamsArr[base + 2] = invSpan;
-    shadowParamsArr[base + 3] = 0;
+    shadowParamsArr[base + 2] = ps.depthBias;
+    shadowParamsArr[base + 3] = ps.normalBias;
   }
   const shadowParamsWriteRes = internals.device.queue.writeBuffer(
     pipelineState.shadowParamsBuffer,
@@ -1127,6 +1128,7 @@ export function writeHdrpClusterAndSsaoBuffers(
     profilePhase,
     'record/scene-state/hdrp-cluster/buffer-upload',
     (): Result<void, RenderError> => {
+      if (frameState.installedPipelineConfig?.ssao?.enabled !== true) return ok(undefined);
       const ssaoBufs = getOrCreateSsaoBuffers(internals);
       if (ssaoBufs === null) return ok(undefined);
       const sProj = computeProjectionMatrix(camera);
@@ -1151,6 +1153,7 @@ export function writeHdrpClusterAndSsaoBuffers(
       ssaoUniformPayload[48] = parameters.intensity;
       ssaoUniformPayload[49] = parameters.radius;
       ssaoUniformPayload[50] = parameters.bias;
+      ssaoUniformPayload[51] = SSAO_SAMPLE_COUNTS[parameters.quality];
 
       const ssaoUniformRes = internals.device.queue.writeBuffer(
         ssaoBufs.uniformBuffer,

package/src/record/frame-snapshot.ts

@@ -18,10 +18,16 @@ import type { DirectionalShadowQuality } from '../components/directional-shadow-
 import type { EnvironmentGeneration } from '../environment/generation';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { GpuBuffer } from '../gpu-resource';
-import type { InstanceCollectionId, InstanceResidency } from '../instances';
+import type { InstanceCollectionStore } from '../instances';
 import type { IblBindingInspection } from '../mesh-material-bindings';
 import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
+import type { AutoExposureGpuResources } from '../pipeline/standard-output/auto-exposure/gpu';
+import type { AutoExposureState } from '../pipeline/standard-output/auto-exposure/state';
+import type { StandardLutGpuResources } from '../pipeline/standard-output/lut-gpu';
+import type { StandardLutCandidate, StandardLutState } from '../pipeline/standard-output/lut-state';
 import type { PointShadowInspection } from '../point-shadow-inspection';
+import type { SsrSpatialAdmission } from '../ssr/admission';
+import type { SsrHistoryCandidate, SsrHistoryOwner } from '../ssr/history';
 import type { TemporalGpuState } from '../temporal/gpu';
 import type { TemporalView } from '../temporal/view';
 
@@ -30,6 +36,23 @@ export type TemporalCommitOutcome =
   | { readonly kind: 'off'; readonly view: TemporalView }
   | { readonly kind: 'taa'; readonly view: TemporalView };
 
+/** CPU transaction metadata staged beside the renderer-owned GPU candidate. */
+export interface PendingAutoExposureState {
+  readonly state: AutoExposureState;
+  readonly generation: number;
+  readonly deviceEpoch: number;
+  readonly frameId: number;
+}
+
+/** CPU POD staged beside the renderer-owned LUT resources until submit. */
+export interface PendingStandardLutState {
+  readonly state: StandardLutState;
+  readonly candidate?: StandardLutCandidate;
+  readonly remove: boolean;
+  readonly targetGeneration: number;
+  readonly deviceEpoch: number;
+}
+
 /**
  * feat-20260708-composited-multi-world-rendering M1 / D-1 / D-9:
  * worldId-entityKey composite key helper. Formula: `worldId * 2^32 + entityKey`.
@@ -53,7 +76,14 @@ export function worldEntityKey(worldId: number, entityKey: number): number {
   return worldId * 4294967296 + entityKey; // 2^32 = 4294967296
 }
 
-/** Per-renderer projection identity, with entity keys for sprite/fold snapshots. */
+/**
+ * Cache identity for a renderer-owned instance collection.
+ *
+ * A collection can be rebound from one entity to another while retaining the
+ * same count, revision, and extraction archetype. The collection id is the
+ * owner identity in that case; the entity cache key is only the compatibility
+ * fallback for legacy snapshots that predate the collection field.
+ */
 export function instanceCollectionCacheKey(
   worldId: number,
   instance: { readonly cacheKey: number; readonly collectionId?: number },
@@ -77,6 +107,7 @@ export interface MaterialBgAssemblyCacheEntry {
   readonly materialBgl: BindGroupLayout;
   /** Buffer identity changes when the shared material capacity grows. */
   readonly materialBuffer: Buffer;
+  readonly sceneMaterialBuffer?: Buffer;
   readonly skylightResources: SkylightBindGroupResources;
   readonly bindGroup: BindGroup;
 }
@@ -204,34 +235,92 @@ export function validateGraphTargetCaptureReadback(input: {
   if (!allowZero && bytes.every((value) => value === 0)) {
     return { ok: false, code: 'capture-readback-empty' };
   }
-  for (let index = 0; index + 1 < bytes.length; index += 2) {
-    const exponent = ((bytes[index + 1] ?? 0) >>> 2) & 0x1f;
-    if (exponent === 0x1f) return { ok: false, code: 'capture-readback-non-finite' };
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let index = 0;
+  // Inspect both half-float exponents per word. DataView also preserves
+  // little-endian capture semantics for unaligned slices and host byte orders.
+  for (; index + 3 < bytes.byteLength; index += 4) {
+    const word = view.getUint32(index, true);
+    if ((word & 0x7c00) === 0x7c00 || (word & 0x7c000000) === 0x7c000000)
+      return { ok: false, code: 'capture-readback-non-finite' };
   }
+  if (index + 1 < bytes.byteLength && (view.getUint16(index, true) & 0x7c00) === 0x7c00)
+    return { ok: false, code: 'capture-readback-non-finite' };
   return { ok: true };
 }
 
+/**
+ * Receipt delivered after a selected pass-replay raster pass has encoded.
+ * The depth view and target handles are the frame-resolved objects used by
+ * the graph; the numeric texture identity is derived by getTextureIdentity.
+ */
+export interface GraphTargetPassReplayReceipt {
+  readonly passName: string;
+  readonly executionIndex: number;
+  readonly resolvedDepthStencilAttachmentView: TextureView;
+  readonly graphGeneration: number;
+  readonly targetName: string;
+  readonly targetView: TextureView;
+  readonly targetTexture: Texture;
+  readonly targetTextureIdentity: number;
+}
+
+export type GraphTargetPassReplayCallback = (receipt: GraphTargetPassReplayReceipt) => void;
+
+/** Receipt delivered once after a complete selected prefix reaches its boundary pass. */
+export interface GraphTargetPassReplayPrefixReceipt extends GraphTargetPassReplayReceipt {
+  /** The compiled-order prefix that was replayed. */
+  readonly replayPassNames: readonly string[];
+  /** The unique depth-bearing raster pass used as the observation anchor. */
+  readonly depthAttachmentPassName: string;
+  /** The final pass in the selected prefix. */
+  readonly observeAfterPassName: string;
+  readonly depthAttachmentExecutionIndex: number;
+}
+
+export type GraphTargetPassReplayPrefixCallback = (
+  receipt: GraphTargetPassReplayPrefixReceipt,
+) => void;
+
 /** Internal readback request consumed by the record encoder in the same submit. */
-export interface GraphTargetCaptureRequest {
-  readonly name: string;
-  readonly buffer: Buffer;
-  readonly bytesPerRow: number;
-  readonly width: number;
-  readonly height: number;
-  /** Descriptor contract checked against the resolved target at copy time. */
-  readonly expected: {
-    readonly format: ResolvedColorTargetDescriptor['format'];
-    readonly width: number;
-    readonly height: number;
-    readonly usage: number;
-    /** Optional caller binding; when present it is checked at copy time. */
-    readonly identity?: {
-      readonly graphGeneration: number;
-      readonly frameId: number;
-      readonly textureIdentity: number;
+export type GraphTargetCaptureRequest =
+  | {
+      /** The default preserves the original target-copy request shape. */
+      readonly kind?: 'target-copy';
+      readonly name: string;
+      /** Optional one-shot pass selection for internal graph-target diagnostics. */
+      readonly replayPassNames?: readonly string[];
+      readonly buffer: Buffer;
+      readonly bytesPerRow: number;
+      readonly width: number;
+      readonly height: number;
+      /** Descriptor contract checked against the resolved target at copy time. */
+      readonly expected: {
+        readonly format: ResolvedColorTargetDescriptor['format'];
+        readonly width: number;
+        readonly height: number;
+        readonly usage: number;
+        /** Optional caller binding; when present it is checked at copy time. */
+        readonly identity?: {
+          readonly graphGeneration: number;
+          readonly frameId: number;
+          readonly textureIdentity: number;
+        };
+      };
+    }
+  | {
+      /** Execute selected compiled passes without requesting a target copy. */
+      readonly kind: 'pass-replay';
+      readonly replayPassNames: readonly string[];
+      /** Optional graph target used to validate the selected pass attachment. */
+      readonly targetName?: string;
+      /** Optional callback invoked after each selected pass encodes. */
+      readonly onPassEncoded?: GraphTargetPassReplayCallback;
+      /** Optional one-shot callback invoked after the selected prefix boundary encodes. */
+      readonly depthAttachmentPassName?: string;
+      readonly observeAfterPassName?: string;
+      readonly onPrefixEncoded?: GraphTargetPassReplayPrefixCallback;
     };
-  };
-}
 
 /** Renderer-private readback request for the Standard fallback MRT. */
 export interface ReflectionFallbackReadbackRequest {
@@ -251,7 +340,6 @@ export interface ReflectionFallbackReadbackRequest {
   };
   encoded: boolean;
 }
-
 /**
  * Build a synthetic CameraSnapshot the record stage uses when the world
  * carries no Camera entity. Identity-shaped projection / view inputs
@@ -319,6 +407,18 @@ export interface RenderFrameState {
   iblBindingInspection?: IblBindingInspection;
   /** Demand for the frame-local Standard fallback MRT. */
   reflectionFallbackDemand?: boolean;
+  /** Whether the active camera explicitly requested SSR this frame. */
+  ssrRequested?: boolean | undefined;
+  /** Current renderer-owned SSR spatial admission projection. */
+  ssrSpatialAdmission?: SsrSpatialAdmission | undefined;
+  /** Persistent SSR history owner; candidate is promoted only after submit. */
+  ssrHistoryOwner?: SsrHistoryOwner | undefined;
+  ssrHistoryCandidate?: SsrHistoryCandidate | undefined;
+  /** Reused CPU parameter payload for the SSR temporal resolve. */
+  ssrTemporalParamsPayload?: Uint8Array | undefined;
+  /** Last camera identity used by the SSR history reset seam. */
+  ssrLastCameraEntity?: number | undefined;
+  ssrLastHistoryVersion?: number | undefined;
   /** Monotonic compiled-graph identity used by diagnostic readbacks. */
   graphGeneration: number;
   /** Number of successfully submitted TAA frames; failed attempts do not advance it. */
@@ -390,6 +490,22 @@ export interface RenderFrameState {
   lastSuccessfulCameraAntialias: CameraSnapshot['antialias'] | undefined;
   /** Staged TAA GPU state is promoted only after queue.submit succeeds. */
   temporalGpuState: TemporalGpuState | undefined;
+  /** Device-scoped auto-exposure buffers imported by the Standard graph. */
+  autoExposureGpuResources?: AutoExposureGpuResources | undefined;
+  /** Candidate auto-exposure buffers; promoted only after queue.submit succeeds. */
+  pendingAutoExposureGpuResources?: AutoExposureGpuResources | undefined;
+  /** Accepted auto-exposure inspection state; promoted only after submit. */
+  autoExposureState?: AutoExposureState | undefined;
+  /** Candidate auto-exposure inspection state; cleared on any failed frame. */
+  pendingAutoExposureState?: PendingAutoExposureState | undefined;
+  /** Prepared ordinary TextureAsset LUT candidate for the Standard graph. */
+  standardLutGpuResources?: StandardLutGpuResources | undefined;
+  /** Candidate LUT resources; promoted only after queue.submit succeeds. */
+  pendingStandardLutGpuResources?: StandardLutGpuResources | undefined;
+  /** Accepted LUT inspection state; promoted only after submit. */
+  standardLutState: StandardLutState;
+  /** Candidate LUT inspection state; cleared on any failed frame. */
+  pendingStandardLutState?: PendingStandardLutState | undefined;
   /** Last successful TAA GPU state; candidate replacement stays staged until submit. */
   activeTemporalGpuState: TemporalGpuState | undefined;
   /** Submitted temporal generations retained until their queue fence resolves. */
@@ -399,12 +515,14 @@ export interface RenderFrameState {
   pendingTemporalCommit: TemporalCommitOutcome;
   /** Staged environment generation is promoted only after queue.submit succeeds. */
   environmentGeneration: EnvironmentGeneration | undefined;
+  environmentFrame?: import('../environment/frame').SelectedEnvironmentFrame | undefined;
+  pendingAtmospherePublish?: (() => void) | undefined;
   readonly environmentLifecycle: EnvironmentLifecycle | undefined;
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
   /** Renderer-owned collection owner used for record-stage residency facts. */
-  readonly instanceResidency?: Map<InstanceCollectionId, InstanceResidency>;
+  readonly instanceCollections?: InstanceCollectionStore;
   /** Stable buffers for renderer-owned collections split by device cap. */
   readonly instanceBufferChunks?: Map<string, InstanceBufferCacheEntry>;
   /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
@@ -548,14 +666,8 @@ export interface RenderFrameState {
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame fast path for fully-resident, immutable material snapshots. */
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
-  /**
-   * feat-20260622-handle-to-id-allocator-elimination M1 / w2: singleton
-   * material bind group cache (D-6). Single flat Map<variant, BindGroup>
-   * for the one true singleton in production: shadow-material-singleton.
-   * shadow-instances-singleton is a test fixture fiction (research F3);
-   * no second singleton field is needed.
-   */
-  readonly singletonMaterialCache: Map<string, BindGroup>;
+  /** Opaque shadow fallback bindings follow physical resources across scene replacement. */
+  shadowMaterialBindGroups: WeakMap<object, unknown>;
   /**
    * Post-process bind group cache: nested WeakMap chain root shared by the
    * built-in bloom (bright / blur-H / blur-V / composite), FXAA, and HDRP SSAO

package/src/record/frame-targets.ts

@@ -9,6 +9,15 @@ export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase
   if (passName.startsWith('shadowCascade')) return 'record/graph-execute/shadow';
   if (passName.startsWith('point-shadow')) return 'record/graph-execute/point-shadow';
   if (passName.startsWith('spot-shadow')) return 'record/graph-execute/spot-shadow';
+  if (passName === 'ssr-hiz-seed' || passName.startsWith('ssr-hiz-reduce-')) {
+    return 'record/graph-execute/ssr-hiz';
+  }
+  if (passName === 'ssr-trace') return 'record/graph-execute/ssr-trace';
+  if (passName === 'ssr-temporal') return 'record/graph-execute/ssr-temporal';
+  if (passName.startsWith('ssr-reflection-mip-')) {
+    return 'record/graph-execute/ssr-reflection-mip';
+  }
+  if (passName === 'ssr-compose') return 'record/graph-execute/ssr-compose';
   switch (passName) {
     case 'cluster-binner-upload':
     case 'cluster-membership-producer':