@forgeax/engine-render 0.1.7 → 0.1.20

package/src/record/frame-lighting.ts

@@ -5,6 +5,7 @@
 import { mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import {
   type BindGroup,
+  type BindGroupEntry,
   type BindGroupLayout,
   RhiError,
   type TextureView,
@@ -87,6 +88,8 @@ export function buildPerFrameBindGroups(
   graphTargets?: {
     readonly directionalShadow?: TextureView | undefined;
     readonly spotShadow?: TextureView | undefined;
+    readonly projector?: TextureView | undefined;
+    readonly projectorSampler?: import('@forgeax/engine-rhi').Sampler | undefined;
   },
   includeView = true,
 ): {
@@ -150,6 +153,9 @@ export function buildPerFrameBindGroups(
         graphSpotShadowView !== undefined
           ? graphSpotShadowView
           : pipelineState.shadowFallbackTextureView;
+      const projectorAvailable = pipelineState.projectorAvailable !== false;
+      const b11View = graphTargets?.projector ?? pipelineState.defaultWhiteTextureView;
+      const b12Sampler = graphTargets?.projectorSampler ?? pipelineState.defaultSampler;
       viewBindGroup = getOrCreateFromChain(
         frameState.viewBindGroupCache,
         [
@@ -161,110 +167,118 @@ export function buildPerFrameBindGroups(
           b5View,
           pipelineState.shadowParamsBuffer,
           b8View,
+          ...(projectorAvailable ? [b11View, b12Sampler] : []),
           pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
         ],
         'view-main',
         () => {
-          const viewBindGroupResult = internals.device.createBindGroup({
-            label: 'pbr-view-bg',
-            layout: pipelineState.viewBindGroupLayout,
-            entries: [
-              {
-                binding: 0,
-                resource: {
-                  kind: 'buffer',
-                  value: { buffer: pipelineState.viewUniformBuffer, size: VIEW_UNIFORM_BYTES },
-                },
+          const entries: BindGroupEntry[] = [
+            {
+              binding: 0,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: pipelineState.viewUniformBuffer, size: VIEW_UNIFORM_BYTES },
               },
-              {
-                binding: 1,
-                resource: {
-                  kind: 'buffer',
-                  value: { buffer: pipelineState.pointLightsBuffer },
-                },
+            },
+            {
+              binding: 1,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: pipelineState.pointLightsBuffer },
               },
-              {
-                binding: 2,
-                resource: {
-                  kind: 'buffer',
-                  value: { buffer: pipelineState.spotLightsBuffer },
-                },
+            },
+            {
+              binding: 2,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: pipelineState.spotLightsBuffer },
               },
-              {
-                binding: 3,
-                resource: {
-                  kind: 'textureView',
-                  value: b3View,
-                },
+            },
+            {
+              binding: 3,
+              resource: {
+                kind: 'textureView',
+                value: b3View,
               },
-              {
-                binding: 4,
-                resource: {
-                  kind: 'sampler',
-                  value: shadowSampler,
-                },
+            },
+            {
+              binding: 4,
+              resource: {
+                kind: 'sampler',
+                value: shadowSampler,
               },
-              // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1:
-              // cube_array shadow atlas view (real ShadowAtlas when point
-              // shadows are active; else 1x1x6 fallback).
-              {
-                binding: 5,
-                resource: {
-                  kind: 'textureView',
-                  value: b5View,
-                },
+            },
+            // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1:
+            // cube_array shadow atlas view (real ShadowAtlas when point
+            // shadows are active; else 1x1x6 fallback).
+            {
+              binding: 5,
+              resource: {
+                kind: 'textureView',
+                value: b5View,
               },
-              // 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
-              // with shadowAtlasLayer === N. Updated per frame from
-              // `pointShadowSnapshots` below.
-              {
-                binding: 6,
-                resource: {
-                  kind: 'buffer',
-                  value: { buffer: pipelineState.shadowParamsBuffer },
-                },
+            },
+            // 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
+            // with shadowAtlasLayer === N. Updated per frame from
+            // `pointShadowSnapshots` below.
+            {
+              binding: 6,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: pipelineState.shadowParamsBuffer },
               },
-              // feat-20260613-csm-cascaded-shadow-maps M5 / w28 (rebased to
-              // binding 7 on 2026-06-13 to make room for point-shadow 5/6):
-              // forward shaders declare binding 7 in common.wgsl (shared
-              // view BGL) but never reference it; only shadow_caster.wgsl
-              // reads it. Host writes a stable singleton buffer so every
-              // forward bind group entry stays populated.
-              {
-                binding: 7,
-                resource: {
-                  kind: 'buffer',
-                  value: { buffer: pipelineState.shadowCasterCascadeBuffer },
-                },
+            },
+            // feat-20260613-csm-cascaded-shadow-maps M5 / w28 (rebased to
+            // binding 7 on 2026-06-13 to make room for point-shadow 5/6):
+            // forward shaders declare binding 7 in common.wgsl (shared
+            // view BGL) but never reference it; only shadow_caster.wgsl
+            // reads it. Host writes a stable singleton buffer so every
+            // forward bind group entry stays populated.
+            {
+              binding: 7,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: pipelineState.shadowCasterCascadeBuffer },
               },
-              // feat-20260625-spot-light-shadow-mapping M3 / w21 (D-5):
-              // spot shadow 2D atlas (real spotShadowDepth view when spot
-              // shadows run this frame, else the 1x1 depth fallback). Always-on.
-              {
-                binding: 8,
-                resource: {
-                  kind: 'textureView',
-                  value: b8View,
-                },
+            },
+            // feat-20260625-spot-light-shadow-mapping M3 / w21 (D-5):
+            // spot shadow 2D atlas (real spotShadowDepth view when spot
+            // shadows run this frame, else the 1x1 depth fallback). Always-on.
+            {
+              binding: 8,
+              resource: {
+                kind: 'textureView',
+                value: b8View,
               },
-              {
-                binding: 10,
-                resource: {
-                  kind: 'buffer',
-                  value: {
-                    buffer: pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
-                    size: POINTS_LINES_VIEW_BYTES,
-                  },
+            },
+            {
+              binding: 10,
+              resource: {
+                kind: 'buffer',
+                value: {
+                  buffer: pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+                  size: POINTS_LINES_VIEW_BYTES,
                 },
               },
-              // feat-20260625-spot-light-shadow-mapping w25: the per-spot
-              // fragment-read lightViewProj matrices fold into the View UBO
-              // (binding 0, `view.spotLightViewProj`) — no standalone binding 9
-              // (WebGL2 fragment uniform-buffer budget). binding 10 is the
-              // dedicated vertex-only Points/Lines viewport UBO.
-            ],
+            },
+            ...(projectorAvailable
+              ? [
+                  { binding: 11, resource: { kind: 'textureView' as const, value: b11View } },
+                  { binding: 12, resource: { kind: 'sampler' as const, value: b12Sampler } },
+                ]
+              : []),
+            // feat-20260625-spot-light-shadow-mapping w25: the per-spot
+            // fragment-read lightViewProj matrices fold into the View UBO
+            // (binding 0, `view.spotLightViewProj`) — no standalone binding 9
+            // (WebGL2 fragment uniform-buffer budget). binding 10 is the
+            // dedicated vertex-only Points/Lines viewport UBO.
+          ];
+          const viewBindGroupResult = internals.device.createBindGroup({
+            label: 'pbr-view-bg',
+            layout: pipelineState.viewBindGroupLayout,
+            entries,
           });
           if (!viewBindGroupResult.ok) throw viewBindGroupResult.error;
           return viewBindGroupResult.value;

package/src/record/frame-snapshot.ts

@@ -6,7 +6,16 @@ import { vec3 } from '@forgeax/engine-math';
 import type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';
 import type { Texture } from '@forgeax/engine-rhi';
 import type { ClusterBinScratch } from '../cluster-binner';
+import type { EnvironmentGeneration } from '../environment/generation';
+import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { GpuBuffer } from '../gpu-resource';
+import type { TemporalGpuState } from '../temporal/gpu';
+import type { TemporalView } from '../temporal/view';
+
+export type TemporalCommitOutcome =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'off'; readonly view: TemporalView }
+  | { readonly kind: 'taa'; readonly view: TemporalView };
 
 /**
  * feat-20260708-composited-multi-world-rendering M1 / D-1 / D-9:
@@ -54,7 +63,7 @@ import type { MaterialRenderState, RenderPipelineAsset } from '@forgeax/engine-t
 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,
@@ -64,6 +73,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):
@@ -84,6 +100,88 @@ export interface FrameObservationSource {
   readonly backendId: string;
 }
 
+/** Internal test/diagnostic view of one compiled graph color target. */
+export interface CurrentGraphTarget {
+  readonly name: string;
+  readonly texture: Texture;
+  /** Stable opaque identity for this RHI handle during the renderer lifetime. */
+  readonly textureIdentity: number;
+  readonly descriptor: ResolvedColorTargetDescriptor;
+  readonly frameId: number;
+  /** Monotonic identity of the compiled graph that owns this texture. */
+  readonly graphGeneration: number;
+}
+
+const textureIdentities = new WeakMap<object, number>();
+let nextTextureIdentity = 1;
+
+/**
+ * Project an opaque RHI texture handle to a stable diagnostic identity.
+ * RHI handles intentionally expose no serializable fields; object identity is
+ * the only valid comparison boundary for a copy-time capture.
+ */
+export function getTextureIdentity(texture: Texture): number {
+  const object = texture as object;
+  const existing = textureIdentities.get(object);
+  if (existing !== undefined) return existing;
+  const identity = nextTextureIdentity++;
+  textureIdentities.set(object, identity);
+  return identity;
+}
+
+export type GraphTargetCaptureReadbackValidation =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly code:
+        | 'capture-readback-length'
+        | 'capture-readback-untouched-sentinel'
+        | 'capture-readback-empty'
+        | 'capture-readback-non-finite';
+    };
+
+/** Validate a mapped rgba16float capture before a consumer decodes its values. */
+export function validateGraphTargetCaptureReadback(input: {
+  readonly bytes: Uint8Array;
+  readonly expectedByteLength: number;
+  readonly sentinel?: Uint8Array;
+}): GraphTargetCaptureReadbackValidation {
+  const { bytes, expectedByteLength, sentinel } = 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' };
+  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' };
+  }
+  return { ok: true };
+}
+
+/** 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;
+    };
+  };
+}
+
 /**
  * Build a synthetic CameraSnapshot the record stage uses when the world
  * carries no Camera entity. Identity-shaped projection / view inputs
@@ -160,22 +258,79 @@ export function clampPcfKernelSize(value: number | undefined): number {
  */
 export interface RenderFrameState {
   frameNumber: number;
+  /** 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;
+  /** 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. */
-  readonly perFrameGraph?: {
+  perFrameGraph?: {
     readonly getColorTargetDescriptor: (key: string) => ResolvedColorTargetDescriptor | undefined;
     readonly getColorTargetView: (key: string) => TextureView | undefined;
     readonly getColorTargetTexture: (key: string) => Texture | undefined;
+    readonly graphGeneration: number;
   } | null;
+  graphTargetCapture?: GraphTargetCaptureRequest | undefined;
   /** Last successfully rendered static directional shadow atlas token. */
   directionalShadowCache: DirectionalShadowCache | null;
+  /** Last successfully submitted camera post-process mode. */
+  lastSuccessfulBloom: 'off' | 'on';
+  /** Bloom record receipts staged by this frame; cleared on abort. */
+  bloomFrameReceipts?: BloomFrameReceipts | undefined;
   /** Set by a directional shadow pass when this frame refreshed the atlas. */
   directionalShadowCacheRecorded: boolean;
   /** The sole compiled owner for compute, copy, feature, and raster work. */
   compiledFrameGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
   compiledFrameGraphTopologyKey: string | null;
+  /**
+   * 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;
+  /** Camera antialias mode for the last successfully submitted graph. */
+  lastSuccessfulCameraAntialias: CameraSnapshot['antialias'] | undefined;
+  /** Staged TAA GPU state is promoted only after queue.submit succeeds. */
+  temporalGpuState: TemporalGpuState | undefined;
+  /** Last successful TAA GPU state; candidate replacement stays staged until submit. */
+  activeTemporalGpuState: TemporalGpuState | undefined;
+  /** Submitted temporal generations retained until their queue fence resolves. */
+  readonly retiringTemporalGpuStates: Set<TemporalGpuState>;
+  /** Last successful projection; candidate frames never overwrite it. */
+  lastSuccessfulTemporalView: TemporalView | undefined;
+  pendingTemporalCommit: TemporalCommitOutcome;
+  /** Staged environment generation is promoted only after queue.submit succeeds. */
+  environmentGeneration: EnvironmentGeneration | undefined;
+  readonly environmentLifecycle: EnvironmentLifecycle | undefined;
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
@@ -342,10 +497,9 @@ export interface RenderFrameState {
    */
   installedPipelineConfig: RenderPipelineAsset['config'];
   /**
-   * feat-20260608-cluster-lighting M2 / w10: HDRP active flag.
-   * True iff the currently installed RenderPipelineAsset has
-   * `pipelineId === 'forgeax::hdrp'`. URP-only code paths gate on
-   * `!isHdrpActive` so HDRP demos do not double-count light contributions.
+   * 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;
   /**
@@ -432,6 +586,16 @@ export interface BindGroupCounts {
   keys: string[];
 }
 
+/**
+ * Successful Bloom record operations staged for the current frame. These
+ * counters are promoted only after the shared renderer queue submission.
+ */
+export interface BloomFrameReceipts {
+  readonly uploadCount: number;
+  readonly bindGroupCount: number;
+  readonly encodeCount: number;
+}
+
 /**
  * A renderable resolved against the AssetRegistry for the current frame:
  * its source snapshot, the GPU mesh handles, the row index used to correlate

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 { resolveDirectionalShadowAtlasGrid } from '../typed-shadow-atlas';
 import { configureSurface, type PipelineState, type RenderSystemInternals } from './render-context';
 
 export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase {
@@ -20,9 +21,12 @@ export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase
     case 'lighting':
       return 'record/graph-execute/lighting';
     case 'forward':
+    case 'transmission-forward':
       return 'record/graph-execute/forward';
-    case 'tonemap':
-      return 'record/graph-execute/tonemap';
+    case 'output-transform':
+      return 'record/graph-execute/output-transform';
+    case 'present':
+      return 'record/graph-execute/present';
     case 'debug-overlay':
       return 'record/graph-execute/debug-overlay';
     case 'shadow':
@@ -55,17 +59,23 @@ export function acquireSwapChainTarget(
 
   let currentTextureResult = canvasContext.getCurrentTexture();
   if (!currentTextureResult.ok) {
-    pipelineState.perPassResources.configured = false;
     const configured = configureSurface(
       canvasContext,
       internals.device,
       pipelineState.format,
       pipelineState.colorAttachmentFormat,
     );
-    if (configured.ok) {
-      pipelineState.perPassResources.configured = true;
-      (globalThis as Record<string, unknown>).__forgeaxSwapChainFormat = pipelineState.format;
+    if (!configured.ok) {
+      internals.errorRegistry.fire(configured.error);
+      internals.healthRegistry.fire({
+        reason: 'internal-fault',
+        detail: { message: 'surface configure candidate failed; current frame skipped' },
+        recoverable: true,
+      });
+      return null;
     }
+    pipelineState.perPassResources.configured = true;
+    (globalThis as Record<string, unknown>).__forgeaxSwapChainFormat = pipelineState.format;
     const retry = canvasContext.getCurrentTexture();
     if (!retry.ok) {
       internals.errorRegistry.fire(retry.error);
@@ -105,14 +115,17 @@ export function resolveShadowMapSize(
   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));
 }