@forgeax/engine-render 0.1.19 → 0.1.20

package/src/record/frame.ts

@@ -4,12 +4,13 @@
 import { HANDLE_NINESLICE_QUAD, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
-import { mat4 } from '@forgeax/engine-math';
+import { mat4, vec3 } from '@forgeax/engine-math';
 import {
   type CurrentFrameObservationLease,
   createCurrentFrameObservationLease,
 } from '@forgeax/engine-render-graph';
 import {
+  type Buffer,
   err,
   ok,
   type Result,
@@ -25,12 +26,22 @@ import { ObservationUnavailableError, type ObservationUnavailableReason } from '
 import type { FogFrame } from '../extract/environment';
 import type { GpuDrivenProduction, PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
 import { GpuBuffer } from '../gpu-resource';
-import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_VERTEX } from '../gpu-usage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_UNIFORM,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
 import { disposeTransientInstanceBuffers } from '../instance-buffer-cache';
-import type { CameraSnapshot, RenderRecordPhase } from '../render-contract';
+import type {
+  CameraSnapshot,
+  RenderRecordPhase,
+  SpotLightProjectorFrameContext,
+  VolumetricFogFrameContext,
+} from '../render-contract';
 import type {
   DispatchEntry,
   ExtractedLights,
+  ExtractedVolumetricFog,
   MaterialSnapshot,
   RenderableSnapshot,
   SkyboxSnapshot,
@@ -43,6 +54,9 @@ import {
   TRANSPARENT_SORT_MODE_LAYER_Z,
 } from '../systems/transparent-sort-config';
 import type { TransmissionDemand } from '../transmission/projection';
+import { hasVolumetricFogCapability } from '../volume/capability';
+import { inspectVolumetricFogResources, VOLUMETRIC_FOG_PARAMS_BYTES } from '../volume/resources';
+import { resolveVolumeTemporalReset, type VolumeTemporalSignature } from '../volume/temporal';
 import {
   buildPerFrameBindGroups,
   prepareFrameLighting,
@@ -188,12 +202,14 @@ export async function observeCurrentFrame(
 }
 
 import { createTemporalView, resolveTemporalReset } from '../temporal/view';
+import { inspectVolumetricFog } from '../volume/inspection';
 import {
   acquireSwapChainTarget,
   graphExecutionPhase,
   resolveShadowMapSize,
   resolveSpotShadowMapSize,
 } from './frame-targets';
+import type { GpuTimingCapture } from './gpu-timing';
 import {
   computeProjectionMatrix,
   computeViewMatrix,
@@ -210,6 +226,7 @@ import {
   ensureCompiledFrameGraph,
   executeCompiledFrameGraph,
   type RenderFeatureGraphCandidate,
+  settleVolumetricFogGraphCandidate,
 } from './typed-frame-graph';
 import { writePointsLinesViewUbo, writeViewUbo } from './view-ubo';
 
@@ -294,6 +311,703 @@ function runRecordProfilePhase<T>(
   return runner === undefined ? action() : runner(phase, action);
 }
 
+const VOLUMETRIC_FOG_PASS_COUNT = 4;
+
+type VolumetricFogParamsSlot = 0 | 1;
+
+function nextVolumetricFogParamsSlot(frameState: RenderFrameState): VolumetricFogParamsSlot {
+  const accepted = frameState.volumetricFogParamsAcceptedSlot;
+  const pending = frameState.volumetricFogParamsPendingSlot;
+  if (pending !== null && pending !== accepted) return pending;
+  return accepted === null ? 0 : accepted === 0 ? 1 : 0;
+}
+
+function stageVolumetricFogParams(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  params: Float32Array,
+): Buffer | undefined {
+  const slot = nextVolumetricFogParamsSlot(frameState);
+  let buffer = frameState.volumetricFogParamsBuffers[slot];
+  if (buffer === null) {
+    const created = internals.device.createBuffer({
+      label: `volumetric-fog-params-${slot}`,
+      size: VOLUMETRIC_FOG_PARAMS_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!created.ok) {
+      internals.errorRegistry.fire(created.error);
+      return undefined;
+    }
+    buffer = created.value;
+    frameState.volumetricFogParamsBuffers[slot] = buffer;
+  }
+  const written = internals.device.queue.writeBuffer(buffer, 0, params);
+  if (!written.ok) {
+    internals.errorRegistry.fire(written.error);
+    return undefined;
+  }
+  frameState.volumetricFogParamsPendingSlot = slot;
+  frameState.volumetricFogPendingParams = new Float32Array(params);
+  return buffer;
+}
+
+/** Retire parameter buffers only after the submit that stopped using them. */
+function retireVolumetricFogParams(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+): void {
+  const buffers = frameState.volumetricFogParamsBuffers;
+  frameState.volumetricFogParamsBuffers = [null, null];
+  frameState.volumetricFogParamsPendingSlot = null;
+  frameState.volumetricFogParamsAcceptedSlot = null;
+  frameState.volumetricFogAcceptedParams = undefined;
+  frameState.volumetricFogPendingParams = undefined;
+  const live = buffers.filter((buffer): buffer is Buffer => buffer !== null);
+  if (live.length === 0) return;
+  const device = internals.device;
+  const release = (): void => {
+    for (const buffer of live) {
+      const destroyed = device.destroyBuffer(buffer);
+      if (!destroyed.ok) internals.errorRegistry.fire(destroyed.error);
+    }
+  };
+  try {
+    void device.queue.onSubmittedWorkDone().then(release, release);
+  } catch {
+    release();
+  }
+}
+
+function volumeRevision(values: readonly number[]): number {
+  let hash = 2166136261;
+  for (const value of values) {
+    const quantized = Number.isFinite(value) ? Math.round(value * 1_000_000) : 0;
+    hash = Math.imul(hash ^ quantized, 16777619) >>> 0;
+  }
+  return hash;
+}
+
+function volumeTemporalSignature(
+  fog: ExtractedVolumetricFog,
+  prepared: VolumetricFogFrameContext,
+  camera: CameraSnapshot,
+  lights: ExtractedLights,
+  width: number,
+  height: number,
+): VolumeTemporalSignature {
+  const authored = fog.fog;
+  const directional = lights.directional;
+  const cameraRevision = volumeRevision([
+    ...camera.world,
+    camera.fov,
+    camera.aspect,
+    camera.near,
+    camera.far,
+    camera.orthoLeft,
+    camera.orthoRight,
+    camera.orthoBottom,
+    camera.orthoTop,
+  ]);
+  const fogRevision =
+    authored === undefined
+      ? 0
+      : volumeRevision([
+          ...authored.bounds.min,
+          ...authored.bounds.max,
+          ...authored.extinction,
+          ...authored.albedo,
+          ...authored.emission,
+          authored.anisotropy,
+          authored.maxDistance,
+        ]);
+  const selectedSpot =
+    fog.spotLightEntity === undefined
+      ? fog.lightKind === 'spot'
+        ? lights.spot.find((spot) => spot.entity === fog.lightEntity)
+        : undefined
+      : lights.spot.find((spot) => spot.entity === fog.spotLightEntity);
+  const selectedPoint =
+    fog.pointLightEntity === undefined
+      ? fog.lightKind === 'point'
+        ? lights.point.find((point) => point.entity === fog.lightEntity)
+        : undefined
+      : lights.point.find((point) => point.entity === fog.pointLightEntity);
+  const selectedDirectional =
+    fog.lightKind === 'directional' && directional?.entity === fog.lightEntity
+      ? directional
+      : undefined;
+  const lightRevision =
+    selectedSpot === undefined && selectedPoint === undefined && selectedDirectional === undefined
+      ? 0
+      : volumeRevision(
+          selectedSpot === undefined && selectedPoint === undefined
+            ? selectedDirectional === undefined
+              ? []
+              : [
+                  ...selectedDirectional.direction,
+                  ...selectedDirectional.color,
+                  selectedDirectional.intensity,
+                  ...(lights.lightViewProj?.flatMap((matrix) => [...matrix]) ?? []),
+                ]
+            : [
+                ...(selectedPoint === undefined
+                  ? []
+                  : [
+                      ...selectedPoint.position,
+                      ...selectedPoint.color,
+                      selectedPoint.intensity,
+                      selectedPoint.invRangeSquared,
+                      selectedPoint.shadowAtlasLayer ?? -1,
+                      selectedPoint.shadowNear ?? 0,
+                      selectedPoint.shadowFar ?? 0,
+                    ]),
+                ...(selectedSpot === undefined
+                  ? []
+                  : [
+                      ...selectedSpot.position,
+                      ...selectedSpot.direction,
+                      ...selectedSpot.color,
+                      selectedSpot.intensity,
+                      selectedSpot.invRangeSquared,
+                      selectedSpot.cosInner,
+                      selectedSpot.cosOuter,
+                      selectedSpot.depthBias ?? 0.005,
+                      selectedSpot.normalBias ?? 0.05,
+                      selectedSpot.pcfKernelSize ?? 3,
+                      selectedSpot.shadowAtlasTile,
+                      ...(selectedSpot.lightViewProj === undefined
+                        ? []
+                        : [...selectedSpot.lightViewProj]),
+                    ]),
+              ],
+        );
+  return {
+    cameraRevision,
+    fogRevision,
+    lightRevision,
+    densityGeneration: prepared.densityGeneration,
+    width,
+    height,
+    ...(fog.lightKind === undefined ? {} : { lightKind: fog.lightKind }),
+    ...(fog.lightEntity === undefined ? {} : { lightEntity: fog.lightEntity }),
+    ...(fog.pointLightEntity === undefined ? {} : { pointLightEntity: fog.pointLightEntity }),
+    ...(fog.spotLightEntity === undefined ? {} : { spotLightEntity: fog.spotLightEntity }),
+    ...(fog.projector === undefined ? {} : { projector: fog.projector }),
+    lightShadowRevision: lightRevision,
+  };
+}
+
+function resolveVolumetricFogHistoryContext(
+  frameState: RenderFrameState,
+  graph: import('@forgeax/engine-render-graph').CompiledRenderGraph<
+    import('../render-pipeline').RenderPipelineFrame
+  >,
+  fog: ExtractedVolumetricFog,
+  prepared: VolumetricFogFrameContext,
+  camera: CameraSnapshot,
+  lights: ExtractedLights,
+  width: number,
+  height: number,
+): { readonly context: VolumetricFogFrameContext; readonly signature: VolumeTemporalSignature } {
+  const signature = volumeTemporalSignature(fog, prepared, camera, lights, width, height);
+  const acceptedGraph = frameState.volumetricFogHistoryGraph;
+  const acceptedSlot = frameState.volumetricFogHistorySlot;
+  const previousSignature = frameState.volumetricFogHistorySignature;
+  let reset = acceptedGraph !== graph || acceptedSlot === null || previousSignature === null;
+  if (!reset && previousSignature !== null) {
+    const temporal = frameState.temporalFrame;
+    const previousResetReason = temporal?.resetReason;
+    const reprojection =
+      previousResetReason === 'out-of-screen'
+        ? 'out-of-screen'
+        : previousResetReason === 'depth-discontinuity'
+          ? 'depth-discontinuity'
+          : undefined;
+    reset = resolveVolumeTemporalReset(previousSignature, signature, {
+      taaEnabled: camera.antialias === 'taa',
+      ...(reprojection === undefined ? {} : { reprojection }),
+    }).reset;
+  }
+  const historyReadSlot = reset ? null : acceptedSlot;
+  const historyWriteSlot = reset || acceptedSlot === null ? 0 : acceptedSlot === 0 ? 1 : 0;
+  return {
+    context: {
+      ...prepared,
+      historyReadSlot,
+      historyWriteSlot,
+      historyValid: historyReadSlot !== null,
+    },
+    signature,
+  };
+}
+
+/**
+ * Resolve the authored density POD into the renderer-owned GPU resources used
+ * by the graph.  This is deliberately a pull operation: a missing/stale
+ * handle or failed upload produces a structured error and leaves the graph
+ * candidate disabled for this frame rather than binding a synthetic density.
+ */
+function prepareVolumetricFogFrame(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  world: World,
+  worlds: readonly World[],
+  fog: ExtractedVolumetricFog | undefined,
+  lights: ExtractedLights,
+  volumeCapability: boolean,
+  projector: SpotLightProjectorFrameContext | undefined,
+): VolumetricFogFrameContext | undefined {
+  if (
+    !volumeCapability ||
+    fog?.status !== 'available' ||
+    fog.fog === undefined ||
+    fog.densityHandle === undefined ||
+    fog.densityAsset === undefined ||
+    (fog.lightKind === 'spot'
+      ? lights.spot.find((light) => light.entity === fog.lightEntity) === undefined
+      : fog.lightKind === 'point'
+        ? lights.point.find((light) => light.entity === fog.lightEntity) === undefined
+        : lights.directional === undefined)
+  ) {
+    return undefined;
+  }
+  const ownerWorld = worlds[fog.worldId ?? 0] ?? world;
+  const resident = internals.gpuStore.ensureResident(
+    fog.densityHandle,
+    fog.densityAsset,
+    ownerWorld,
+  );
+  if (!resident.ok || !('texture' in resident.value)) {
+    if (!resident.ok) {
+      internals.errorRegistry.fire(
+        resident.error instanceof RhiError
+          ? resident.error
+          : new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'volumetric density residency to resolve a GPU texture',
+              hint: 'repair the authored TextureAsset payload and retry the next frame',
+              detail: { error: resident.error },
+            }),
+      );
+    }
+    return undefined;
+  }
+  const params = new Float32Array(32);
+  params.set(fog.fog.bounds.min, 0);
+  params.set(fog.fog.bounds.max, 4);
+  params.set(fog.fog.extinction, 8);
+  params.set(fog.fog.albedo, 12);
+  params.set(fog.fog.emission, 16);
+  const selectedPoint =
+    fog.pointLightEntity === undefined
+      ? undefined
+      : lights.point.find((light) => light.entity === fog.pointLightEntity);
+  const selectedSpot =
+    fog.spotLightEntity === undefined
+      ? fog.lightKind === 'spot'
+        ? lights.spot.find((light) => light.entity === fog.lightEntity)
+        : undefined
+      : lights.spot.find((light) => light.entity === fog.spotLightEntity);
+  const lightDirection =
+    selectedSpot?.direction ?? lights.directional?.direction ?? vec3.create(0, -1, 0);
+  const lightColor = selectedSpot?.color ?? lights.directional?.color ?? vec3.create(0, 0, 0);
+  if (lightDirection === undefined || lightColor === undefined) return undefined;
+  params.set(lightDirection, 20);
+  // Reuse the vec4 padding lane as the renderer-owned frame phase for
+  // sub-froxel jitter. The temporal resolver consumes it without growing the
+  // public fog component or allocating another uniform buffer.
+  params[23] = frameState.frameNumber % 1024;
+  const selectedSpotIndex =
+    selectedSpot === undefined
+      ? -1
+      : lights.spot.findIndex((light) => light.entity === selectedSpot.entity);
+  params.set(lightColor, 24);
+  params[19] =
+    selectedPoint === undefined
+      ? -1
+      : lights.point.findIndex((light) => light.entity === selectedPoint.entity);
+  params[27] = selectedSpotIndex;
+  params[28] = fog.fog.maxDistance;
+  params[29] = fog.fog.anisotropy;
+  params[30] =
+    selectedPoint !== undefined && selectedSpot !== undefined
+      ? 3
+      : selectedPoint !== undefined
+        ? 1
+        : selectedSpot !== undefined
+          ? 2
+          : 0;
+  // The temporal shader reads this lane after the record stage resolves the
+  // accepted graph/slot. It is overwritten on the next queue-visible frame;
+  // the first candidate deliberately starts with history disabled.
+  params[31] =
+    frameState.temporalFrame !== undefined && frameState.temporalFrame.resetReason === 'none'
+      ? 1
+      : 0;
+
+  const paramsBuffer = stageVolumetricFogParams(internals, frameState, params);
+  if (paramsBuffer === undefined) return undefined;
+  return {
+    densityTexture: resident.value.texture.handle,
+    densityView: resident.value.view,
+    paramsBuffer,
+    densityGeneration: resident.value.receipt.generation,
+    historyReadSlot: null,
+    historyWriteSlot: 0,
+    historyValid: false,
+    ...(projector === undefined
+      ? {}
+      : {
+          projectorTexture: projector.texture,
+          projectorView: projector.view,
+          projectorSampler: projector.sampler,
+        }),
+  };
+}
+
+/**
+ * Resolve the SpotLight-owned cookie independently of volumetric fog. Surface
+ * lighting must keep the authored projector when the fog component is absent;
+ * otherwise the view bind group silently falls back to white and changes the
+ * direct-light energy on the floor. A fog-selected projector is preferred so
+ * the surface and volume lanes consume one identity, with the first authored
+ * projector as the deterministic scene fallback.
+ */
+function prepareSpotLightProjectorFrame(
+  internals: RenderSystemInternals,
+  world: World,
+  worlds: readonly World[],
+  lights: ExtractedLights,
+  fog: ExtractedVolumetricFog | undefined,
+): SpotLightProjectorFrameContext | undefined {
+  const preferred =
+    fog?.projectorHandle === undefined
+      ? undefined
+      : lights.spot.find((light) => light.projectorHandle === fog.projectorHandle);
+  const source =
+    preferred ??
+    lights.spot.find(
+      (light) =>
+        light.projectorHandle !== undefined &&
+        light.projectorAsset !== undefined &&
+        light.lightViewProj !== undefined,
+    );
+  if (
+    source === undefined ||
+    source.projectorHandle === undefined ||
+    source.projectorAsset === undefined
+  ) {
+    return undefined;
+  }
+  const ownerWorld = worlds[fog?.worldId ?? 0] ?? world;
+  const resident = internals.gpuStore.ensureResident(
+    source.projectorHandle,
+    source.projectorAsset,
+    ownerWorld,
+  );
+  if (!resident.ok || !('texture' in resident.value)) {
+    if (!resident.ok) {
+      internals.errorRegistry.fire(
+        resident.error instanceof RhiError
+          ? resident.error
+          : new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'SpotLight projector residency to resolve a GPU texture',
+              hint: 'repair the authored projector TextureAsset payload and retry the next frame',
+              detail: { error: resident.error },
+            }),
+      );
+    }
+    return undefined;
+  }
+  const sampler = internals.device.createSampler({
+    label: 'spot-projector-linear-clamp',
+    minFilter: 'linear',
+    magFilter: 'linear',
+    mipmapFilter: 'linear',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+    addressModeW: 'clamp-to-edge',
+  });
+  if (!sampler.ok) {
+    internals.errorRegistry.fire(sampler.error);
+    return undefined;
+  }
+  return {
+    texture: resident.value.texture.handle,
+    view: resident.value.view,
+    sampler: sampler.value,
+  };
+}
+
+/** Stage the accepted parameter payload into the writable slot for a degraded
+ * source frame. This keeps the accepted GPU buffer immutable until submit
+ * succeeds while still allowing the LKG graph to update its history flag. */
+function stageAcceptedVolumetricFogFrame(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  accepted: VolumetricFogFrameContext | undefined,
+): VolumetricFogFrameContext | undefined {
+  if (accepted === undefined) return undefined;
+  const params = frameState.volumetricFogAcceptedParams;
+  if (params === undefined) return accepted;
+  const paramsBuffer = stageVolumetricFogParams(internals, frameState, new Float32Array(params));
+  if (paramsBuffer === undefined) return accepted;
+  return { ...accepted, paramsBuffer };
+}
+
+function updateVolumetricFogInspection(
+  frameState: RenderFrameState,
+  fog: ExtractedVolumetricFog | undefined,
+  lights: ExtractedLights,
+  prepared: VolumetricFogFrameContext | undefined,
+  submitted: boolean,
+  volumeCapability: boolean,
+  volumeSubmissionAttempted: boolean,
+): void {
+  const resourceFacts =
+    frameState.compiledFrameGraph === undefined || frameState.compiledFrameGraph === null
+      ? undefined
+      : inspectVolumetricFogResources(frameState.compiledFrameGraph.inspect(), {
+          parameterBufferCount: frameState.volumetricFogParamsBuffers.filter(
+            (buffer) => buffer !== null,
+          ).length,
+        });
+  const graphSampleCount = resourceFacts?.sampleCount ?? 0;
+  const graphMemoryBytes = resourceFacts?.totalBytes ?? 0;
+  const previous = frameState.volumetricFogInspection;
+  const accepted = frameState.volumetricFogAccepted;
+  const acceptedLkg =
+    accepted === undefined
+      ? undefined
+      : {
+          guid: accepted.guid ?? previous.guid,
+          generation: accepted.generation ?? previous.generation,
+          digest: accepted.digest ?? previous.digest,
+          deviceEpoch: previous.deviceEpoch,
+          format: previous.format ?? accepted.densityAsset?.format ?? fog?.densityAsset?.format,
+          passCount: previous.passCount > 0 ? previous.passCount : VOLUMETRIC_FOG_PASS_COUNT,
+          sampleCount: previous.sampleCount > 0 ? previous.sampleCount : graphSampleCount,
+          memoryBytes: previous.memoryBytes > 0 ? previous.memoryBytes : graphMemoryBytes,
+          resourceFacts: previous.resourceFacts ?? resourceFacts,
+          lightEntity: accepted.lightEntity,
+          lightKind: accepted.lightKind,
+          pointLightEntity: accepted.pointLightEntity,
+          spotLightEntity: accepted.spotLightEntity,
+          projector: accepted.projector,
+        };
+
+  const candidateIdentity =
+    fog?.guid === undefined || fog.generation === undefined
+      ? undefined
+      : {
+          guid: fog.guid,
+          generation: fog.generation,
+          digest: fog.digest,
+        };
+  const selectedLightAvailable =
+    fog?.lightKind === 'spot'
+      ? lights.spot.some((light) => light.entity === fog.lightEntity)
+      : fog?.lightKind === 'point'
+        ? lights.point.some(
+            (light) => light.entity === (fog.pointLightEntity ?? fog.lightEntity),
+          ) &&
+          (fog.spotLightEntity === undefined ||
+            lights.spot.some((light) => light.entity === fog.spotLightEntity))
+        : fog?.lightKind === 'directional'
+          ? lights.directional?.entity === fog.lightEntity
+          : lights.directional !== undefined;
+  const capability = volumeCapability && selectedLightAvailable ? 'available' : 'unavailable';
+
+  const inspectAccepted = (status: 'accepted' | 'degraded', candidateFailure?: 'submit-failed') => {
+    if (
+      acceptedLkg === undefined ||
+      acceptedLkg.guid === undefined ||
+      acceptedLkg.generation === undefined
+    ) {
+      return false;
+    }
+    const recovery = {
+      guid: acceptedLkg.guid,
+      generation: acceptedLkg.generation,
+      deviceEpoch: acceptedLkg.deviceEpoch,
+      status,
+      ...(status === 'degraded' ? { lkgGeneration: acceptedLkg.generation } : {}),
+      ...(candidateIdentity === undefined
+        ? {}
+        : {
+            candidateGeneration: candidateIdentity.generation,
+            ...(candidateIdentity.digest === undefined
+              ? {}
+              : { candidateDigest: candidateIdentity.digest }),
+          }),
+      ...(acceptedLkg.lightEntity === undefined || acceptedLkg.lightKind === undefined
+        ? {}
+        : {
+            selectedLight: {
+              entity: acceptedLkg.lightEntity,
+              kind: acceptedLkg.lightKind,
+              revision: 0,
+              shadowTile: -1,
+              ...(acceptedLkg.pointLightEntity === undefined
+                ? {}
+                : { pointLightEntity: acceptedLkg.pointLightEntity }),
+              ...(acceptedLkg.spotLightEntity === undefined
+                ? {}
+                : { spotLightEntity: acceptedLkg.spotLightEntity }),
+              ...(acceptedLkg.projector === undefined ? {} : { projector: acceptedLkg.projector }),
+            },
+          }),
+      ...(candidateFailure === undefined ? {} : { candidateFailure }),
+    } satisfies import('../volume/recovery').VolumeRecoveryState;
+    frameState.volumetricFogInspection = inspectVolumetricFog({
+      authored: true,
+      capability: 'available',
+      degraded: status === 'degraded',
+      recovery,
+      ...(acceptedLkg.digest === undefined ? {} : { acceptedDigest: acceptedLkg.digest }),
+      ...(acceptedLkg.format === undefined ? {} : { format: acceptedLkg.format }),
+      passCount: acceptedLkg.passCount,
+      sampleCount: acceptedLkg.sampleCount,
+      memoryBytes: acceptedLkg.memoryBytes,
+      ...(acceptedLkg.resourceFacts === undefined
+        ? {}
+        : { resourceFacts: acceptedLkg.resourceFacts }),
+    });
+    return true;
+  };
+
+  if (fog === undefined || fog.status === 'off') {
+    // A failed fog-off candidate must not erase the inspection/LKG that is
+    // still being rendered. The accepted projection is retired only after a
+    // successful no-volume submission below.
+    if (!submitted && volumeSubmissionAttempted && inspectAccepted('degraded', 'submit-failed')) {
+      return;
+    }
+    if (!submitted && volumeSubmissionAttempted) return;
+    if (!submitted) return;
+    frameState.volumetricFogInspection = inspectVolumetricFog({
+      authored: false,
+      capability: 'available',
+    });
+    return;
+  }
+
+  const authored = fog.status === 'available' || fog.status === 'degraded';
+
+  // A successfully submitted available candidate is the only path that may
+  // become the new accepted projection. This call runs after graph settlement
+  // so the inspection and the graph/context observe the same transaction.
+  if (
+    submitted &&
+    fog.status === 'available' &&
+    prepared !== undefined &&
+    capability === 'available'
+  ) {
+    const recovery =
+      candidateIdentity === undefined
+        ? undefined
+        : {
+            guid: candidateIdentity.guid,
+            generation: candidateIdentity.generation,
+            deviceEpoch: previous.deviceEpoch,
+            status: 'accepted' as const,
+            ...(fog.lightEntity === undefined || fog.lightKind === undefined
+              ? {}
+              : {
+                  selectedLight: {
+                    entity: fog.lightEntity,
+                    kind: fog.lightKind,
+                    revision: 0,
+                    shadowTile:
+                      lights.spot.find((spot) => spot.entity === fog.spotLightEntity)
+                        ?.shadowAtlasTile ??
+                      lights.spot.find((spot) => spot.entity === fog.lightEntity)
+                        ?.shadowAtlasTile ??
+                      -1,
+                    ...(fog.pointLightEntity === undefined
+                      ? {}
+                      : { pointLightEntity: fog.pointLightEntity }),
+                    ...(fog.spotLightEntity === undefined
+                      ? {}
+                      : { spotLightEntity: fog.spotLightEntity }),
+                    ...(fog.projector === undefined ? {} : { projector: fog.projector }),
+                  },
+                }),
+          };
+    frameState.volumetricFogInspection = inspectVolumetricFog({
+      authored: true,
+      capability,
+      ...(recovery === undefined ? {} : { recovery }),
+      ...(candidateIdentity?.digest === undefined
+        ? {}
+        : { acceptedDigest: candidateIdentity.digest }),
+      ...(fog.densityAsset?.format === undefined ? {} : { format: fog.densityAsset.format }),
+      passCount: VOLUMETRIC_FOG_PASS_COUNT,
+      sampleCount: graphSampleCount,
+      memoryBytes: graphMemoryBytes,
+      ...(resourceFacts === undefined ? {} : { resourceFacts }),
+    });
+    return;
+  }
+
+  // A submitted degraded source (or an available source whose residency
+  // preparation failed) is rendered through the previously accepted graph.
+  // Keep that LKG resource fact visible instead of projecting a zero-resource
+  // candidate merely because the current source could not be prepared.
+  if (
+    submitted &&
+    acceptedLkg !== undefined &&
+    (fog.status === 'degraded' || prepared === undefined)
+  ) {
+    if (inspectAccepted('degraded')) return;
+  }
+
+  // Any candidate that reached encode/submit but failed must project the LKG,
+  // never the unsubmitted candidate. The candidate identity remains visible so
+  // recovery tooling can distinguish the rejected bytes from the frame being
+  // rendered.
+  if (!submitted && volumeSubmissionAttempted && inspectAccepted('degraded', 'submit-failed')) {
+    return;
+  }
+
+  // A degraded source that has no LKG is still a diagnostic, but it must not
+  // claim accepted resources. Keep its identity in the candidate stage.
+  const candidateRecovery =
+    candidateIdentity === undefined
+      ? undefined
+      : {
+          guid: candidateIdentity.guid,
+          generation: candidateIdentity.generation,
+          deviceEpoch: previous.deviceEpoch,
+          status: 'candidate' as const,
+          candidateGeneration: candidateIdentity.generation,
+          ...(candidateIdentity.digest === undefined
+            ? {}
+            : { candidateDigest: candidateIdentity.digest }),
+          ...(!submitted && volumeSubmissionAttempted
+            ? { candidateFailure: 'submit-failed' as const }
+            : {}),
+        };
+  frameState.volumetricFogInspection = inspectVolumetricFog({
+    authored,
+    capability,
+    degraded: fog.status === 'degraded' || capability === 'unavailable',
+    ...(candidateRecovery === undefined ? {} : { recovery: candidateRecovery }),
+    ...(acceptedLkg?.digest === undefined ? {} : { acceptedDigest: acceptedLkg.digest }),
+    ...(fog.densityAsset?.format === undefined
+      ? acceptedLkg?.format === undefined
+        ? {}
+        : { format: acceptedLkg.format }
+      : { format: fog.densityAsset.format }),
+    passCount: 0,
+    sampleCount: 0,
+    memoryBytes: 0,
+  });
+}
+
 export function recordFrame(
   internals: RenderSystemInternals,
   world: World,
@@ -331,6 +1045,8 @@ export function recordFrame(
   fogSignature = '',
   environmentReady = true,
   transmissionDemand?: TransmissionDemand,
+  volumetricFog?: ExtractedVolumetricFog,
+  timingCapture?: GpuTimingCapture,
 ): boolean {
   // The `try / finally` wrapper advances `frameState.frameNumber` exactly
   // once per `recordFrame` invocation regardless of which early-return
@@ -361,6 +1077,11 @@ export function recordFrame(
     );
     activeCameras = [makeZeroCameraFallbackSnapshot()];
   }
+  let submitted = false;
+  let volumeInspectionReady = false;
+  let volumeSubmissionAttempted = false;
+  let preparedVolumetricFogForInspection: VolumetricFogFrameContext | undefined;
+  let volumeCapabilityForInspection = false;
   try {
     // Case D: N>1 Camera => fire onError, use first hit (D-S7).
     if (activeCameras.length > 1) {
@@ -494,6 +1215,64 @@ export function recordFrame(
     const effectiveShadowMapSize = resolveShadowMapSize(internals, lights);
     const effectiveSpotShadowMapSize = resolveSpotShadowMapSize(internals, lights);
     const graphShadowMapSize = effectiveShadowMapSize ?? effectiveSpotShadowMapSize;
+    const volumeCapability = hasVolumetricFogCapability(
+      internals.device.caps,
+      internals.volumetricFogShaders,
+    );
+    volumeInspectionReady = true;
+    volumeCapabilityForInspection = volumeCapability;
+
+    const preparedSpotLightProjector = prepareSpotLightProjectorFrame(
+      internals,
+      world,
+      worlds,
+      lights,
+      volumetricFog,
+    );
+
+    const preparedVolumetricFog = prepareVolumetricFogFrame(
+      internals,
+      frameState,
+      world,
+      worlds,
+      volumetricFog,
+      lights,
+      volumeCapability,
+      preparedSpotLightProjector,
+    );
+    preparedVolumetricFogForInspection = preparedVolumetricFog;
+    // A degraded authored snapshot must keep consuming the last accepted GPU
+    // projection.  The current source is still surfaced as a diagnostic, but
+    // it must not replace the graph/context that produced the last good frame.
+    // An absent component is different: a successful no-volume frame retires
+    // the accepted projection and compiles the normal graph.
+    const acceptedFallback =
+      volumeCapability && volumetricFog !== undefined && preparedVolumetricFog === undefined
+        ? frameState.volumetricFogAccepted
+        : undefined;
+    const acceptedFallbackContext =
+      acceptedFallback === undefined
+        ? undefined
+        : stageAcceptedVolumetricFogFrame(
+            internals,
+            frameState,
+            frameState.volumetricFogAcceptedContext,
+          );
+    const graphVolumetricFog = volumeCapability
+      ? preparedVolumetricFog === undefined
+        ? acceptedFallback
+        : volumetricFog
+      : undefined;
+    const baseVolumetricFogContext = preparedVolumetricFog ?? acceptedFallbackContext;
+    // A volume graph replacement is provisional whenever it can affect the
+    // accepted volume projection. This includes authoring degradation (which
+    // consumes the LKG graph), an authored replacement, and an explicit
+    // fog-off transition. Non-volume frames retain the legacy immediate graph
+    // retirement path.
+    const volumeTopologyCandidate =
+      (graphVolumetricFog?.status === 'available' && baseVolumetricFogContext !== undefined) ||
+      (graphVolumetricFog === undefined && frameState.volumetricFogAccepted !== undefined) ||
+      (volumetricFog?.status === 'degraded' && acceptedFallback !== undefined);
 
     let preparedGpuDriven: PreparedGpuDrivenFrame | undefined;
     if (gpuDriven !== undefined) {
@@ -533,6 +1312,8 @@ export function recordFrame(
         featureGraphCandidate,
         cameras.length === 0,
         transmissionDemand,
+        graphVolumetricFog,
+        volumeTopologyCandidate,
       ),
     );
     if (preflightGraph === null) return false;
@@ -623,6 +1404,35 @@ export function recordFrame(
           : { kind: 'taa', view: temporalView };
     const recordCamera: CameraSnapshot =
       temporalView === undefined ? camera : { ...camera, temporal: temporalView };
+    let activeVolumetricFogContext: VolumetricFogFrameContext | undefined;
+    let activeVolumetricFogSignature: VolumeTemporalSignature | undefined;
+    if (graphVolumetricFog?.status === 'available' && baseVolumetricFogContext !== undefined) {
+      const resolvedHistory = resolveVolumetricFogHistoryContext(
+        frameState,
+        preflightGraph,
+        graphVolumetricFog,
+        baseVolumetricFogContext,
+        camera,
+        lights,
+        targetW,
+        targetH,
+      );
+      activeVolumetricFogContext = resolvedHistory.context;
+      activeVolumetricFogSignature = resolvedHistory.signature;
+      const historyFlag = new Float32Array([activeVolumetricFogContext.historyValid ? 1 : 0]);
+      if (frameState.volumetricFogPendingParams !== undefined) {
+        frameState.volumetricFogPendingParams[31] = historyFlag[0] ?? 0;
+      }
+      const historyFlagWritten = internals.device.queue.writeBuffer(
+        activeVolumetricFogContext.paramsBuffer,
+        31 * Float32Array.BYTES_PER_ELEMENT,
+        historyFlag,
+      );
+      if (!historyFlagWritten.ok) {
+        internals.errorRegistry.fire(historyFlagWritten.error);
+        return false;
+      }
+    }
 
     const depthView: TextureView | null = null;
     // feat-20260709 M3 / D-3: clear-color read from the active CameraSnapshot's
@@ -772,7 +1582,18 @@ export function recordFrame(
     // feat-20260531-skybox-env-background M2 / w6: gate relaxed from
     // `validatedOrdered.length > 0` to include skybox-only frames
     // (plan-strategy D-3, R-3).
-    if (validatedOrdered.length > 0 || skyboxActive) {
+    const currentViewProjection = mat4.create();
+    mat4.multiply(
+      currentViewProjection,
+      computeProjectionMatrix(camera),
+      computeViewMatrix(camera),
+    );
+    if (
+      validatedOrdered.length > 0 ||
+      skyboxActive ||
+      activeVolumetricFogContext !== undefined ||
+      preparedVolumetricFog !== undefined
+    ) {
       runRecordProfilePhase(profilePhase, 'record/uploads', () => {
         // View UBO + CSM/spot-shadow matrix pack: assembled + uploaded in one
         // queue.writeBuffer round-trip. Extracted to view-ubo.ts (M3/w18) so
@@ -922,6 +1743,15 @@ export function recordFrame(
       geometryColorResolveView,
       ldrSpriteColorView,
       postProcessParams: framePostProcessParams,
+      ...(internals.volumetricFogShaders === undefined
+        ? {}
+        : { volumetricFogShaders: internals.volumetricFogShaders }),
+      ...(activeVolumetricFogContext === undefined
+        ? {}
+        : { volumetricFog: activeVolumetricFogContext }),
+      ...(preparedSpotLightProjector === undefined
+        ? {}
+        : { spotLightProjector: preparedSpotLightProjector }),
       dispatch: transparentDispatch,
       hdrpClusterBindGroup,
       hdrpClusterMembershipBindGroup,
@@ -935,7 +1765,21 @@ export function recordFrame(
       directionalShadowCacheReuse: directionalShadowCache.reuse,
       ...(profilePhase !== undefined ? { profilePhase } : {}),
     };
-    const submitted = runRecordProfilePhase(profilePhase, 'record/graph-execute', () =>
+    const stagedTemporalFrame = {
+      frameId: frameState.frameNumber,
+      currentViewProjection: new Float32Array(currentViewProjection),
+      jitter: [0, 0] as [number, number],
+      viewport: { width: targetW, height: targetH },
+      cameraPosition: [
+        camera.position[0] ?? 0,
+        camera.position[1] ?? 0,
+        camera.position[2] ?? 0,
+      ] as [number, number, number],
+    };
+    frameState.temporalFrameInput = stagedTemporalFrame;
+    frameState.temporalFrameTransaction.stage(stagedTemporalFrame);
+    volumeSubmissionAttempted = volumeTopologyCandidate || activeVolumetricFogContext !== undefined;
+    submitted = runRecordProfilePhase(profilePhase, 'record/graph-execute', () =>
       executeCompiledFrameGraph(
         internals,
         frameState,
@@ -944,6 +1788,7 @@ export function recordFrame(
         profilePhase === undefined
           ? undefined
           : (pass, encode) => profilePhase(graphExecutionPhase(pass.name), encode),
+        timingCapture,
       ),
     );
     if (submitted && !directionalShadowCache.reuse) {
@@ -951,8 +1796,66 @@ export function recordFrame(
         ? directionalShadowCache.next
         : null;
     }
+    if (submitted) {
+      if (graphVolumetricFog === undefined) {
+        frameState.volumetricFogAccepted = undefined;
+        frameState.volumetricFogAcceptedContext = undefined;
+        frameState.volumetricFogHistoryGraph = null;
+        frameState.volumetricFogHistorySlot = null;
+        frameState.volumetricFogHistorySignature = null;
+        retireVolumetricFogParams(internals, frameState);
+      } else if (
+        activeVolumetricFogContext !== undefined &&
+        activeVolumetricFogSignature !== undefined
+      ) {
+        // Temporal history is graph-owned state. Promote the write slot only
+        // after queue submission succeeds; a failed candidate keeps the
+        // accepted graph/context/slot and retries into the same pending slot.
+        frameState.volumetricFogHistoryGraph = preflightGraph;
+        frameState.volumetricFogHistorySlot = activeVolumetricFogContext.historyWriteSlot;
+        frameState.volumetricFogHistorySignature = activeVolumetricFogSignature;
+        if (frameState.volumetricFogParamsPendingSlot !== null) {
+          frameState.volumetricFogParamsAcceptedSlot = frameState.volumetricFogParamsPendingSlot;
+          frameState.volumetricFogAcceptedParams =
+            frameState.volumetricFogPendingParams === undefined
+              ? undefined
+              : new Float32Array(frameState.volumetricFogPendingParams);
+          frameState.volumetricFogParamsPendingSlot = null;
+          frameState.volumetricFogPendingParams = undefined;
+        }
+        if (volumetricFog?.status === 'available' && preparedVolumetricFog !== undefined) {
+          frameState.volumetricFogAccepted = volumetricFog;
+          frameState.volumetricFogAcceptedContext = activeVolumetricFogContext;
+        } else if (acceptedFallback !== undefined) {
+          // The current authored source is degraded, so keep the old accepted
+          // POD while advancing the LKG graph's ping-pong slot.
+          frameState.volumetricFogAcceptedContext = activeVolumetricFogContext;
+        }
+      } else if (volumetricFog?.status === 'available' && preparedVolumetricFog !== undefined) {
+        // Defensive fallback for a volume graph that was accepted before the
+        // temporal context could be resolved; do not manufacture history.
+        frameState.volumetricFogAccepted = volumetricFog;
+        frameState.volumetricFogAcceptedContext = preparedVolumetricFog;
+      }
+    }
     return submitted;
   } finally {
+    // Volume topology replacements are provisional until the queue submission
+    // succeeds. This runs for every early-return path as well, so a swapchain,
+    // encoder, or graph failure cannot leave a non-submitted candidate as the
+    // next frame's accepted graph.
+    settleVolumetricFogGraphCandidate(frameState, submitted);
+    if (volumeInspectionReady && (submitted || volumeSubmissionAttempted)) {
+      updateVolumetricFogInspection(
+        frameState,
+        volumetricFog,
+        lights,
+        preparedVolumetricFogForInspection,
+        submitted,
+        volumeCapabilityForInspection,
+        volumeSubmissionAttempted,
+      );
+    }
     frameState.frameNumber += 1;
     // feat-20260608-cluster-lighting M5 / w22: clear HDRP once-per-frame fired
     // set so the next frame re-fires if the condition persists.