@forgeax/engine-render 0.1.20 → 0.1.23

package/src/record/frame-snapshot.ts

@@ -2,13 +2,24 @@
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import type { World } from '@forgeax/engine-ecs';
+import type { RenderReadVersion } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
 import type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';
-import type { Texture } from '@forgeax/engine-rhi';
+import type {
+  BindGroup,
+  BindGroupLayout,
+  Buffer,
+  RhiDevice,
+  Texture,
+  TextureView,
+} from '@forgeax/engine-rhi';
 import type { ClusterBinScratch } from '../cluster-binner';
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
 import type { EnvironmentGeneration } from '../environment/generation';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { GpuBuffer } from '../gpu-resource';
+import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
+import type { PointShadowInspection } from '../point-shadow-inspection';
 import type { TemporalGpuState } from '../temporal/gpu';
 import type { TemporalView } from '../temporal/view';
 
@@ -58,7 +69,6 @@ export interface MaterialBgAssemblyCacheEntry {
 }
 
 import type { CompiledRenderGraph } from '@forgeax/engine-render-graph';
-import type { BindGroup, BindGroupLayout, Buffer, TextureView } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, RenderPipelineAsset } from '@forgeax/engine-types';
 import type { MeshGpuHandles } from '../device/gpu-residency';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
@@ -72,6 +82,7 @@ import type {
   RenderableSnapshot,
   SpotLightSnapshot,
 } from '../render-system-extract';
+import type { ProbeBlendRecord } from '../scene/probe-blend-record';
 import type { ShadowAtlas } from '../shadow-atlas';
 import type {
   TemporalFrame,
@@ -81,6 +92,18 @@ import type {
 import type { VolumetricFogInspection } from '../volume/inspection';
 import type { VolumeTemporalSignature } from '../volume/temporal';
 
+/** Retained probe record bytes carried with one extracted render frame. */
+export interface ProbeBlendFrameSnapshot {
+  readonly records: readonly ProbeBlendRecord[];
+  readonly recordByteLength: 160;
+}
+
+/** Renderer-owned GPU cache entry for one object's 160B probe record. */
+export interface ProbeBlendBufferCacheEntry {
+  readonly generation: number;
+  readonly bytes: Uint8Array;
+}
+
 /**
  * feat-20260608-create-app-param-surface-trim / M1 / D-8 (q8 user lock):
  * fallback clear color when the world carries no Camera entity. Opaque
@@ -145,14 +168,17 @@ export function validateGraphTargetCaptureReadback(input: {
   readonly bytes: Uint8Array;
   readonly expectedByteLength: number;
   readonly sentinel?: Uint8Array;
+  readonly allowZero?: boolean;
 }): GraphTargetCaptureReadbackValidation {
-  const { bytes, expectedByteLength, sentinel } = input;
+  const { bytes, expectedByteLength, sentinel, allowZero = false } = input;
   if (bytes.byteLength !== expectedByteLength)
     return { ok: false, code: 'capture-readback-length' };
   if (sentinel?.every((value, index) => bytes[index] === value)) {
     return { ok: false, code: 'capture-readback-untouched-sentinel' };
   }
-  if (bytes.every((value) => value === 0)) return { ok: false, code: 'capture-readback-empty' };
+  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' };
@@ -182,6 +208,25 @@ export interface GraphTargetCaptureRequest {
   };
 }
 
+/** Renderer-private readback request for the Standard fallback MRT. */
+export interface ReflectionFallbackReadbackRequest {
+  readonly name: string;
+  readonly buffer: Buffer;
+  readonly bytesPerRow: number;
+  readonly width: number;
+  readonly height: number;
+  readonly expected: {
+    readonly format: ResolvedColorTargetDescriptor['format'];
+    readonly width: number;
+    readonly height: number;
+    readonly usage: number;
+    readonly graphGeneration: number;
+    readonly frameId: number;
+    readonly textureIdentity: number;
+  };
+  encoded: boolean;
+}
+
 /**
  * Build a synthetic CameraSnapshot the record stage uses when the world
  * carries no Camera entity. Identity-shaped projection / view inputs
@@ -225,20 +270,6 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
   };
 }
 
-// feat-20260621-merge-directionallightshadow-into-directionallight M3 / m3-t2
-// (D-7): host-clamp the merged DirectionalLight's pcfKernelSize to the nearest
-// valid odd kernel in {1,3,5} before it reaches the View UBO float [128].
-// lighting-directional.wgsl runs a constant-trip-count loop to MAX_PCF_HALF=2
-// (merged 5.3-production-shadow-demos AC-14 variant-free pattern) and clips each
-// iteration to half = (pcfKernelSize-1)/2, so the supported kernel set is
-// {1,3,5} (cap 5). undefined (no shadow fields) defaults to 3.
-export function clampPcfKernelSize(value: number | undefined): number {
-  if (value === undefined) return 3;
-  if (value <= 1) return 1;
-  if (value <= 3) return 3;
-  return 5;
-}
-
 /**
  * Per-RenderSystem mutable frame state.
  *
@@ -258,12 +289,14 @@ export function clampPcfKernelSize(value: number | undefined): number {
  */
 export interface RenderFrameState {
   frameNumber: number;
+  /** Demand for the frame-local Standard fallback MRT. */
+  reflectionFallbackDemand?: boolean;
   /** Monotonic compiled-graph identity used by diagnostic readbacks. */
   graphGeneration: number;
   /** Number of successfully submitted TAA frames; failed attempts do not advance it. */
   successfulTemporalFrameIndex?: number;
   /** The renderer-owned accepted-submit temporal fact consumed by consumers. */
-  temporalFrame?: TemporalFrame;
+  temporalFrame?: TemporalFrame | undefined;
   /** The sole transaction that advances temporal history after queue.submit. */
   readonly temporalFrameTransaction: TemporalFrameTransaction;
   /** Staged input is consumed only by the graph submit owner. */
@@ -276,6 +309,8 @@ export interface RenderFrameState {
     readonly graphGeneration: number;
   } | null;
   graphTargetCapture?: GraphTargetCaptureRequest | undefined;
+  /** One-frame producer-owned copy target for fallback MRT readback. */
+  reflectionFallbackReadback?: ReflectionFallbackReadbackRequest | undefined;
   /** Last successfully rendered static directional shadow atlas token. */
   directionalShadowCache: DirectionalShadowCache | null;
   /** Last successfully submitted camera post-process mode. */
@@ -287,6 +322,8 @@ export interface RenderFrameState {
   /** The sole compiled owner for compute, copy, feature, and raster work. */
   compiledFrameGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
   compiledFrameGraphTopologyKey: string | null;
+  /** Monotonic generation of successfully promoted compiled graphs. */
+  compiledFrameGraphGeneration: number;
   /**
    * Last-known-good graph held while a volume topology candidate is tested.
    * The candidate is promoted only after its command buffer is submitted;
@@ -317,6 +354,10 @@ export interface RenderFrameState {
   readonly retiredCompiledFrameGraphs: Set<CompiledRenderGraph<RenderPipelineFrame>>;
   /** Physical outputs projected by typed graph passes for downstream observers. */
   currentFrameObservationSource: FrameObservationSource | undefined;
+  /** Completed-frame source for the producer-owned fallback MRT. */
+  reflectionFallbackObservationSource?: FrameObservationSource | undefined;
+  /** Completion fence for the producer-owned fallback row/readback promotion. */
+  reflectionFallbackCompletion?: Promise<void> | undefined;
   /** Camera antialias mode for the last successfully submitted graph. */
   lastSuccessfulCameraAntialias: CameraSnapshot['antialias'] | undefined;
   /** Staged TAA GPU state is promoted only after queue.submit succeeds. */
@@ -334,26 +375,43 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+  /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
+  readonly probeBlendBuffers: Map<number, ProbeBlendBufferCacheEntry>;
+  /** One renderer-owned record array; each object selects its 256B-aligned lane. */
+  probeBlendRecordBuffer?: GpuBuffer;
+  probeBlendRecordBufferCapacity: number;
   /** Per-entity vertex buffers for the Standard CPU morph lane. */
   readonly morphBuffers?: Map<number, MorphBufferCacheEntry>;
   readonly hdrpClusterBinScratch: ClusterBinScratch;
   /** Reusable HDRP cluster output buffers; sized once and grown only if the grid/cap changes. */
   hdrpClusterGridScratch: Uint32Array | null;
   hdrpLightIndexListScratch: Uint32Array | null;
-  /** Compute bind group for the optional WebGPU HDRP membership producer. */
-  hdrpClusterMembershipBindGroup: BindGroup | null;
+  /** Device-owned membership binding; layout and device must match the active pipeline. */
+  hdrpClusterMembership: {
+    readonly device: RhiDevice;
+    readonly layout: BindGroupLayout;
+    readonly bindGroup: BindGroup;
+    /** Cluster buffer identity keeps this group aligned with grown bundles. */
+    readonly clusterGridBuffer: Buffer;
+  } | null;
+  /**
+   * Signature of the Standard lighting declaration accepted by the compiled
+   * graph. Payload uploads and membership bindings must match this signature;
+   * a failed candidate never changes it.
+   */
+  standardLightingGraphSignature: string;
+  /** Last prepared Standard transport facts projected for Renderer.inspect(). */
+  standardLightingInspection?: StandardLightingInspection | undefined;
+  /** Last submitted point-shadow atlas budget projection. */
+  pointShadowInspection?: PointShadowInspection | undefined;
   transientInstanceBuffers: InstanceBufferCacheEntry[];
   warnedZeroLightStandard: boolean;
   /**
-   * feax-20260608-multi-light-warn-once M3: once-warn latch for multi-light
-   * overrun per bucket (directional N>1 / point N>4 / spot N>4). Fires at
-   * most once per RenderSystem lifetime per bucket so AI users see a single
-   * actionable console.warn without per-frame flooding (charter P3 explicit
-   * failure: warn-once preserves signal/noise floor).
+   * feat-20260608-multi-light-warn-once M3: once-warn latch for the
+   * single-directional authoring constraint. Standard local lights use the
+   * unified Cluster budget; there is no per-kind local-light cap.
    */
   warnedMultiLightDirectional: boolean;
-  warnedMultiLightPoint: boolean;
-  warnedMultiLightSpot: boolean;
   /**
    * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
    * once-warn latches for >1 Skylight / >1 SkyboxBackground entity. Fire at most
@@ -496,20 +554,14 @@ export interface RenderFrameState {
    * Install-time config projected into `RenderPipelineTopology.config`.
    */
   installedPipelineConfig: RenderPipelineAsset['config'];
-  /**
-   * Whether the configured standard graph resolved to the clustered lane.
-   * Capability gating keeps URP forward bindings on WebGL2 fallback even
-   * when a clustered profile was requested.
-   */
-  isHdrpActive: boolean;
   /**
    * feat-20260608-cluster-lighting M5 / w20 + M6 / w23 + M5 / w22:
-   * once-per-frame fire dedup set for HDRP per-frame fail-soft errors
-   * (`hdrp-light-budget-exceeded`, `hdrp-index-list-overflow`). Cleared
+   * once-per-frame fire dedup set for Standard per-frame fail-soft errors
+   * (`standard-light-budget-exceeded`, `standard-cluster-index-overflow`). Cleared
    * at the end of each frame so the next frame re-fires if the condition
    * persists. Set<string> keyed by RuntimeErrorCode literal.
    */
-  hdrpOncePerFrameFired: Set<string>;
+  standardOncePerFrameFired: Set<string>;
   /**
    * feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-1).
    * Lazily-allocated cube_array shadow atlas owned by the RenderSystem
@@ -646,6 +698,7 @@ export interface DirectionalShadowCache {
   readonly graphTopologyKey: string | null;
   readonly shadowMapSize: number;
   readonly cascadeCount: number;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
   readonly lightViewProj: readonly Float32Array[];
   readonly meshResidencyEpoch: number;
 }
@@ -654,11 +707,11 @@ export interface DirectionalShadowCache {
  * ECS state that can change the contents of a directional shadow map.
  *
  * The ECS-owned RenderReadLease is the only render-facing mutation boundary.
- * Its cursor is intentionally conservative: any published World change
+ * Its version is intentionally conservative: any published World change
  * invalidates the cached atlas, while render never reaches through World for
  * component-clock storage.
  */
 export interface DirectionalShadowWorldState {
   readonly worldIdentity: string;
-  readonly changeCursor: number;
+  readonly version: RenderReadVersion;
 }

package/src/record/frame-targets.ts

@@ -1,6 +1,7 @@
 import type { RhiCanvasContext, Texture, TextureView } from '@forgeax/engine-rhi';
 import type { RenderGraphExecutionPhase } from '../render-contract';
 import type { ExtractedLights } from '../render-system-extract';
+import type { RenderTargetDescriptor } from '../targets/contracts';
 import { resolveDirectionalShadowAtlasGrid } from '../typed-shadow-atlas';
 import { configureSurface, type PipelineState, type RenderSystemInternals } from './render-context';
 
@@ -50,6 +51,21 @@ export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase
   }
 }
 
+export function resolveRenderTargetMipExtent(
+  descriptor: RenderTargetDescriptor,
+  mipLevel: number,
+): { readonly width: number; readonly height: number } {
+  const mipCount =
+    descriptor.mipLevels === 1
+      ? 1
+      : Math.floor(Math.log2(Math.max(descriptor.width, descriptor.height))) + 1;
+  const level = Math.max(0, Math.min(mipLevel, mipCount - 1));
+  return {
+    width: Math.max(1, descriptor.width >> level),
+    height: Math.max(1, descriptor.height >> level),
+  };
+}
+
 export function acquireSwapChainTarget(
   internals: RenderSystemInternals,
   pipelineState: PipelineState,
@@ -112,6 +128,7 @@ export function resolveShadowMapSize(
   internals: RenderSystemInternals,
   lights: ExtractedLights,
 ): number | undefined {
+  if (lights.cascadeCount === undefined) return undefined;
   const requested = lights.shadowMapSize;
   if (!(requested !== undefined && requested > 0)) return requested;
   const cascades = Math.max(1, Math.min(4, Math.round(lights.cascadeCount ?? 1)));