@forgeax/engine-render 0.1.20 → 0.1.21

package/src/record/frame-snapshot.ts

@@ -4,11 +4,21 @@
 import type { World } from '@forgeax/engine-ecs';
 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 +68,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';
@@ -225,20 +234,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.
  *
@@ -287,6 +282,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;
@@ -340,8 +337,24 @@ export interface RenderFrameState {
   /** 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;
   /**
@@ -496,20 +509,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 +653,7 @@ export interface DirectionalShadowCache {
   readonly graphTopologyKey: string | null;
   readonly shadowMapSize: number;
   readonly cascadeCount: number;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
   readonly lightViewProj: readonly Float32Array[];
   readonly meshResidencyEpoch: number;
 }

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)));