@forgeax/engine-render 0.1.19 → 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,12 +68,11 @@ 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';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
-import type { CameraSnapshot } from '../render-contract';
+import type { CameraSnapshot, VolumetricFogFrameContext } from '../render-contract';
 import type { RenderPipeline as RenderPipelineDef, RenderPipelineFrame } from '../render-pipeline';
 import type {
   DispatchEntry,
@@ -73,6 +82,13 @@ import type {
   SpotLightSnapshot,
 } from '../render-system-extract';
 import type { ShadowAtlas } from '../shadow-atlas';
+import type {
+  TemporalFrame,
+  TemporalFrameInput,
+  TemporalFrameTransaction,
+} from '../temporal/frame';
+import type { VolumetricFogInspection } from '../volume/inspection';
+import type { VolumeTemporalSignature } from '../volume/temporal';
 
 /**
  * feat-20260608-create-app-param-surface-trim / M1 / D-8 (q8 user lock):
@@ -218,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.
  *
@@ -255,6 +257,12 @@ export interface RenderFrameState {
   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;
+  /** The sole transaction that advances temporal history after queue.submit. */
+  readonly temporalFrameTransaction: TemporalFrameTransaction;
+  /** Staged input is consumed only by the graph submit owner. */
+  temporalFrameInput: TemporalFrameInput | undefined;
   /** Optional graph resource lookup used by low-level record helpers and tests. */
   perFrameGraph?: {
     readonly getColorTargetDescriptor: (key: string) => ResolvedColorTargetDescriptor | undefined;
@@ -274,6 +282,35 @@ 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;
+   * failed encoding/finish/submit restores this graph and its topology key.
+   */
+  volumetricFogPreviousGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
+  volumetricFogPreviousGraphKey: string | null;
+  volumetricFogCandidateGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
+  /** Two renderer-owned parameter slots; only the pending slot is writable. */
+  volumetricFogParamsBuffers: [Buffer | null, Buffer | null];
+  /** Candidate parameter slot, promoted only after queue submission succeeds. */
+  volumetricFogParamsPendingSlot: 0 | 1 | null;
+  /** Parameter slot consumed by the last accepted volume frame. */
+  volumetricFogParamsAcceptedSlot: 0 | 1 | null;
+  /** CPU copy of the accepted parameter payload for degraded-frame staging. */
+  volumetricFogAcceptedParams: Float32Array | undefined;
+  /** CPU copy of the current candidate payload before submit. */
+  volumetricFogPendingParams: Float32Array | undefined;
+  /** Last candidate/accepted volume projection exposed through inspect(). */
+  volumetricFogInspection: VolumetricFogInspection;
+  /** Accepted volume POD/context retained while a later candidate degrades. */
+  volumetricFogAccepted: import('../render-system-extract').ExtractedVolumetricFog | undefined;
+  volumetricFogAcceptedContext: VolumetricFogFrameContext | undefined;
+  /** Accepted graph identity and ping-pong slot for temporal volume history. */
+  volumetricFogHistoryGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
+  volumetricFogHistorySlot: 0 | 1 | null;
+  volumetricFogHistorySignature: VolumeTemporalSignature | null;
   readonly retiredCompiledFrameGraphs: Set<CompiledRenderGraph<RenderPipelineFrame>>;
   /** Physical outputs projected by typed graph passes for downstream observers. */
   currentFrameObservationSource: FrameObservationSource | undefined;
@@ -300,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;
   /**
@@ -456,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
@@ -606,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,8 @@
 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';
 
 export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase {
@@ -49,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,
@@ -111,17 +128,21 @@ 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)));
-  const tilesPerSide = Math.ceil(Math.sqrt(cascades));
+  const atlasGrid = resolveDirectionalShadowAtlasGrid(cascades);
   const maxDimension = internals.device.limits.maxTextureDimension2D;
   if (!(maxDimension > 0)) return Math.floor(requested);
   const depthTextureDimension =
     internals.device.caps?.backendKind === 'wgpu-webgl2'
       ? Math.max(1, Math.floor(maxDimension / 2))
       : maxDimension;
-  const maxPerTile = Math.max(1, Math.floor(depthTextureDimension / tilesPerSide));
+  const maxPerTile = Math.max(
+    1,
+    Math.floor(depthTextureDimension / Math.max(atlasGrid.columns, atlasGrid.rows)),
+  );
   return Math.max(1, Math.min(Math.floor(requested), maxPerTile));
 }