@forgeax/engine-render 0.1.19 → 0.1.20

package/src/record/typed-frame-graph.ts

@@ -40,14 +40,14 @@ import {
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
   GPU_TEXTURE_USAGE_TEXTURE_BINDING,
 } from '../gpu-texture-usage';
-import { STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
+import { resolveVolumetricFogProfile, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
 import type { CameraSnapshot } from '../render-contract';
 import type {
   RenderPipelineFeatureTarget,
   RenderPipelineFrame,
   RenderPipelineTopology,
 } from '../render-pipeline';
-import type { ExtractedLights } from '../render-system-extract';
+import type { ExtractedLights, ExtractedVolumetricFog } from '../render-system-extract';
 import {
   abortTemporalGpuSubmit,
   commitTemporalGpuSubmit,
@@ -60,8 +60,11 @@ import {
 } from '../temporal/gpu';
 import { isSceneDataTarget } from '../temporal/scene-data';
 import type { TransmissionDemand } from '../transmission/projection';
+import { hasVolumetricFogCapability } from '../volume/capability';
+import { deriveVolumetricFogExtent, deriveVolumetricFogResolvedExtent } from '../volume/resources';
 import { buildPerFrameBindGroups } from './frame-lighting';
 import { getTextureIdentity, type RenderFrameState } from './frame-snapshot';
+import type { GpuTimingCapture } from './gpu-timing';
 import type { PipelineState, RenderSystemInternals } from './render-context';
 import { resolveSurfaceFormatPair, resolveSurfaceProfile } from './render-context';
 
@@ -329,6 +332,7 @@ function topologyOf(
   gpuDriven: PreparedGpuDrivenFrame | undefined,
   featureGraphCandidate: RenderFeatureGraphCandidate | undefined,
   transmissionDemand: TransmissionDemand | undefined,
+  volumetricFog: ExtractedVolumetricFog | undefined,
 ): Result<RenderPipelineTopology, RhiError> {
   const cascadeCount = Math.max(1, Math.min(4, Math.round(lights.cascadeCount ?? 1))) as
     | 1
@@ -365,6 +369,21 @@ function topologyOf(
             ]),
           ],
         };
+  const volumeCapability = hasVolumetricFogCapability(
+    internals.device.caps,
+    internals.volumetricFogShaders,
+  );
+  const selectedVolumeLight =
+    volumetricFog?.lightKind === 'spot'
+      ? lights.spot.find((light) => light.entity === volumetricFog.lightEntity)
+      : volumetricFog?.lightKind === 'point'
+        ? lights.point.find((light) => light.entity === volumetricFog.lightEntity)
+        : volumetricFog?.lightKind === 'directional' &&
+            lights.directional?.entity === volumetricFog.lightEntity
+          ? lights.directional
+          : volumetricFog?.lightKind === undefined
+            ? lights.directional
+            : undefined;
   return ok({
     pipelineId: STANDARD_PIPELINE_ID,
     standardProfile: internals.standardProfile,
@@ -398,6 +417,47 @@ function topologyOf(
         ).length,
       ),
     },
+    volumetricFog:
+      volumetricFog?.status === 'available' &&
+      volumetricFog.densityAsset?.shape.viewDimension === '3d' &&
+      camera.tonemap !== 'none' &&
+      selectedVolumeLight !== undefined &&
+      volumeCapability
+        ? (() => {
+            const volumeProfile = resolveVolumetricFogProfile(internals.standardProfile ?? {});
+            return {
+              enabled: true,
+              format: volumetricFog.densityAsset.format,
+              extent: {
+                width: volumetricFog.densityAsset.shape.extent.width,
+                height: volumetricFog.densityAsset.shape.extent.height,
+                depth: volumetricFog.densityAsset.shape.extent.depth,
+              },
+              froxelExtent: deriveVolumetricFogExtent(
+                { width, height },
+                volumeProfile.depth,
+                volumeProfile.tileSize,
+              ),
+              resolvedExtent: deriveVolumetricFogResolvedExtent(
+                { width, height },
+                volumeProfile.tileSize,
+              ),
+              lightKind: volumetricFog.lightKind,
+              lightEntity: volumetricFog.lightEntity,
+              pointLightEntity: volumetricFog.pointLightEntity,
+              spotLightEntity: volumetricFog.spotLightEntity,
+              ...(volumetricFog.projector === undefined
+                ? {}
+                : {
+                    projector: {
+                      guid: volumetricFog.projector.guid,
+                      generation: volumetricFog.projector.generation,
+                      revision: volumetricFog.projector.revision,
+                    },
+                  }),
+            };
+          })()
+        : { enabled: false },
     lane: {
       compute: internals.device.caps.compute,
       storageBuffer: internals.device.caps.storageBuffer,
@@ -610,6 +670,32 @@ function retire(
     .catch(() => undefined);
 }
 
+/**
+ * Settle a volume topology candidate after the command buffer outcome is
+ * known. A graph that failed to encode, finish, or submit must never become
+ * the next frame's accepted graph: retire it and restore the prior graph (or
+ * leave the renderer without a graph when this was the first attempt).
+ */
+export function settleVolumetricFogGraphCandidate(
+  frameState: RenderFrameState,
+  submitted: boolean,
+): void {
+  const candidate = frameState.volumetricFogCandidateGraph ?? null;
+  if (candidate === null) return;
+  const previous = frameState.volumetricFogPreviousGraph ?? null;
+  const previousKey = frameState.volumetricFogPreviousGraphKey ?? null;
+  if (submitted) {
+    if (previous !== null && previous !== candidate) retire(frameState, previous);
+  } else {
+    if (candidate !== previous) retire(frameState, candidate);
+    frameState.compiledFrameGraph = previous;
+    frameState.compiledFrameGraphTopologyKey = previousKey;
+  }
+  frameState.volumetricFogPreviousGraph = null;
+  frameState.volumetricFogPreviousGraphKey = null;
+  frameState.volumetricFogCandidateGraph = null;
+}
+
 export function ensureCompiledFrameGraph(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
@@ -623,6 +709,8 @@ export function ensureCompiledFrameGraph(
   featureGraphCandidate?: RenderFeatureGraphCandidate,
   clearOnly = false,
   transmissionDemand?: TransmissionDemand,
+  volumetricFog?: ExtractedVolumetricFog,
+  volumeTopologyCandidate = false,
 ): CompiledRenderGraph<RenderPipelineFrame> | null {
   const surfaceWidth = Math.max(1, width);
   const surfaceHeight = Math.max(1, height);
@@ -631,7 +719,7 @@ export function ensureCompiledFrameGraph(
   if (!projectedFeaturePlans.ok) {
     reportRenderFeatureGraphError(internals, projectedFeaturePlans.error);
     featureGraphCandidate?.onRejected?.();
-    return frameState.compiledFrameGraph;
+    return volumeTopologyCandidate ? null : frameState.compiledFrameGraph;
   }
   const topologyResult = topologyOf(
     internals,
@@ -646,11 +734,12 @@ export function ensureCompiledFrameGraph(
     gpuDriven,
     featureGraphCandidate,
     transmissionDemand,
+    volumetricFog,
   );
   if (!topologyResult.ok) {
     internals.errorRegistry.fire(topologyResult.error);
     featureGraphCandidate?.onRejected?.();
-    return frameState.compiledFrameGraph;
+    return volumeTopologyCandidate ? null : frameState.compiledFrameGraph;
   }
   const topology = topologyResult.value;
   const key = JSON.stringify(topology);
@@ -658,6 +747,10 @@ export function ensureCompiledFrameGraph(
     if (featureGraphCandidate !== undefined) {
       commitFeatureCandidate(internals, featureGraphCandidate);
     }
+    // A candidate flag only describes a possible topology replacement. When
+    // the derived key is unchanged there is no replacement to stage: reuse the
+    // accepted graph so dynamic volume history/imported views can advance and
+    // a queue-submit failure can still publish the LKG diagnostic.
     return frameState.compiledFrameGraph;
   }
 
@@ -701,7 +794,7 @@ export function ensureCompiledFrameGraph(
   if (!built.ok) {
     internals.errorRegistry.fire(built.error);
     featureGraphCandidate?.onRejected?.();
-    return frameState.compiledFrameGraph;
+    return volumeTopologyCandidate ? null : frameState.compiledFrameGraph;
   }
   const compiled = builder.compile({
     device: internals.device,
@@ -713,6 +806,11 @@ export function ensureCompiledFrameGraph(
     return frameState.compiledFrameGraph;
   }
   const previous = frameState.compiledFrameGraph;
+  if (volumeTopologyCandidate) {
+    frameState.volumetricFogPreviousGraph = previous;
+    frameState.volumetricFogPreviousGraphKey = frameState.compiledFrameGraphTopologyKey;
+    frameState.volumetricFogCandidateGraph = compiled.value;
+  }
   frameState.compiledFrameGraph = compiled.value;
   frameState.compiledFrameGraphTopologyKey = key;
   const compiledTargets = compiled.value as CompiledGraphTargetAccess;
@@ -727,7 +825,7 @@ export function ensureCompiledFrameGraph(
   if (featureGraphCandidate !== undefined) {
     commitFeatureCandidate(internals, featureGraphCandidate);
   }
-  if (previous !== null) retire(frameState, previous);
+  if (!volumeTopologyCandidate && previous !== null) retire(frameState, previous);
   return compiled.value;
 }
 
@@ -737,15 +835,41 @@ export function executeCompiledFrameGraph(
   frame: RenderPipelineFrame,
   encoder: RhiCommandEncoder,
   runPass?: import('@forgeax/engine-render-graph').RenderGraphPassRunner,
+  timingCapture?: GpuTimingCapture,
 ): boolean {
   const graph = frameState.compiledFrameGraph;
-  if (graph === null) return false;
+  const rejectTemporalFrame = (): void => {
+    if (frameState.temporalFrameInput === undefined) return;
+    frameState.temporalFrameTransaction.commit({ accepted: false });
+    frameState.temporalFrameInput = undefined;
+  };
+  if (graph === null) {
+    timingCapture?.discard();
+    settleVolumetricFogGraphCandidate(frameState, false);
+    rejectTemporalFrame();
+    return false;
+  }
+  const timedRunPass =
+    timingCapture === undefined
+      ? runPass
+      : (
+          pass: import('@forgeax/engine-render-graph').RenderGraphPassExecution,
+          encode: () => void,
+        ) => {
+          timingCapture.beforePass(pass.name, encoder);
+          try {
+            if (runPass === undefined) encode();
+            else runPass(pass, encode);
+          } finally {
+            timingCapture.afterPass(pass.name, encoder);
+          }
+        };
   type PreparedCommand = { readonly command: CommandBuffer };
   let preparedCommand: PreparedCommand = { command: undefined as never };
   const transaction = executeRendererFrameTransaction<PreparedCommand>({
     build: () => ({ ok: true, value: { command: undefined as never } }),
     execute: () => {
-      const executed = graph.execute(frame, runPass);
+      const executed = graph.execute(frame, timedRunPass);
       if (!executed.ok) {
         internals.errorRegistry.fire(executed.error);
         return { ok: false, stage: 'execute' };
@@ -887,8 +1011,14 @@ export function executeCompiledFrameGraph(
         );
         return { ok: false, stage: 'finish' };
       }
+      const resolved = timingCapture?.resolve(encoder);
+      if (resolved !== undefined && !resolved.ok) {
+        timingCapture?.discard();
+        return { ok: false, stage: 'finish' };
+      }
       const finished = encoder.finish();
       if (!finished.ok) {
+        timingCapture?.discard();
         internals.errorRegistry.fire(finished.error);
         return { ok: false, stage: 'finish' };
       }
@@ -898,9 +1028,11 @@ export function executeCompiledFrameGraph(
     submit: () => {
       const submitted = internals.device.queue.submit([preparedCommand.command]);
       if (!submitted.ok) {
+        timingCapture?.discard();
         internals.errorRegistry.fire(submitted.error);
         return { ok: false, stage: 'submit' };
       }
+      timingCapture?.markSubmitted();
       return { ok: true, value: undefined };
     },
     commit: () => {
@@ -974,6 +1106,7 @@ export function executeCompiledFrameGraph(
       }
     },
     abort: (failure) => {
+      timingCapture?.discard();
       frameState.bloomFrameReceipts = undefined;
       if (frameState.environmentGeneration !== undefined) {
         frameState.environmentLifecycle?.recordStageFailure(
@@ -996,5 +1129,7 @@ export function executeCompiledFrameGraph(
       }
     },
   });
+  settleVolumetricFogGraphCandidate(frameState, transaction.ok);
+  if (!transaction.ok) rejectTemporalFrame();
   return transaction.ok;
 }

package/src/render-contract.ts

@@ -16,6 +16,7 @@ import type {
   RhiInstance,
   RhiRenderPassEncoder,
   RenderPipeline as RhiRenderPipeline,
+  Sampler,
   Texture,
   TextureFormat,
   TextureView,
@@ -43,7 +44,9 @@ export type { PointsLinesInspection } from './points-lines/inspection';
 import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
 import type { StandardProfile } from './pipeline/standard-profile';
 import type { PostProcessError } from './post-process-errors';
+import type { VolumeTimingObservation } from './record/gpu-timing';
 import type { TemporalView } from './temporal/view';
+import type { VolumetricFogInspection } from './volume/inspection';
 
 export type RenderResult<T, E> =
   | { readonly ok: true; readonly value: T }
@@ -118,6 +121,14 @@ export type { TemporalView } from './temporal/view';
 interface RenderPipelineStateView {
   readonly format: TextureFormat;
   readonly colorAttachmentFormat: TextureFormat;
+  /** Renderer-owned View UBO shared by Standard lighting, shadows, and fog. */
+  readonly viewUniformBuffer: Buffer;
+  /** Renderer-owned SpotLight std430 buffer shared by Standard and volume. */
+  readonly pointLightsBuffer: Buffer;
+  readonly spotLightsBuffer: Buffer;
+  /** Fallback resources keep the shared view layout valid when no projector is authored. */
+  readonly defaultWhiteTextureView: TextureView;
+  readonly defaultSampler: Sampler;
 }
 
 /**
@@ -127,6 +138,16 @@ interface RenderPipelineStateView {
  */
 interface RenderPipelineRuntime {
   readonly device: RhiDevice;
+  /** Runtime-owned shader module factory used by built-in graph producers. */
+  readonly shaderModuleFactory?: {
+    createShaderModule(input: {
+      readonly code: string;
+      readonly label?: string | undefined;
+    }): import('@forgeax/engine-types').Result<
+      import('@forgeax/engine-rhi').ShaderModule,
+      RhiError
+    >;
+  };
   readonly errorRegistry: { fire(error: RendererError): void };
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly lookupPostProcess?: (id: string) => PostProcessShaderEntry | undefined;
@@ -170,6 +191,52 @@ export interface RenderPipelineContext {
   readonly msaaActive: boolean;
   readonly geometryColorResolveView: TextureView | null;
   readonly ldrSpriteColorView: TextureView | null;
+  /** Renderer-owned volume resources prepared from the authored ECS snapshot. */
+  readonly volumetricFog?: VolumetricFogFrameContext;
+  /** Renderer-owned SpotLight projector resources, independent of fog. */
+  readonly spotLightProjector?: SpotLightProjectorFrameContext;
+  /** Build-time composed utility sources for the renderer-owned volume passes. */
+  readonly volumetricFogShaders?: VolumetricFogShaderSources;
+}
+
+/** Stable utility entry-point sources emitted by the shader manifest. */
+export interface VolumetricFogShaderSources {
+  readonly inject: string;
+  readonly temporal: string;
+  readonly integrate: string;
+  readonly composite: string;
+}
+
+/**
+ * GPU resources for one validated volumetric-fog candidate.  The record stage
+ * owns residency and parameter uploads; graph passes consume this narrow view
+ * and never reach into AssetRegistry or World.
+ */
+export interface VolumetricFogFrameContext {
+  readonly densityTexture: Texture;
+  readonly densityView: TextureView;
+  readonly paramsBuffer: Buffer;
+  readonly densityGeneration: number;
+  /** Accepted graph-owned history slot; null means first frame/reset. */
+  readonly historyReadSlot: 0 | 1 | null;
+  /** Pending graph-owned history slot; promoted only after queue.submit succeeds. */
+  readonly historyWriteSlot: 0 | 1;
+  readonly historyValid: boolean;
+  /** Accepted SpotLight projector resources resolved by the GPU residency owner. */
+  readonly projectorTexture?: Texture;
+  readonly projectorView?: TextureView;
+  readonly projectorSampler?: Sampler;
+}
+
+/**
+ * GPU resources for the single surface SpotLight projector binding. The
+ * projector is a SpotLight-owned cookie and therefore remains available when
+ * volumetric fog is disabled; volume integration may reuse the same tuple.
+ */
+export interface SpotLightProjectorFrameContext {
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly sampler: Sampler;
 }
 
 /**
@@ -274,6 +341,7 @@ export interface FrameReceiptObservation {
   readonly frameId: number;
   readonly deviceGeneration: number;
   readonly include: readonly ('timings' | 'draws' | 'bindings')[];
+  readonly timings?: VolumeTimingObservation;
 }
 
 /** Stable backend facts for the Standard output transform projection. */
@@ -342,6 +410,8 @@ export interface RenderInspection {
     readonly frameId: number;
     readonly deviceGeneration: number;
   };
+  /** Renderer-owned authored volume projection and submit/LKG state. */
+  readonly volumetricFog?: VolumetricFogInspection;
   readonly features: readonly string[];
   /** Truthful lifecycle facts for every registered declarative feature. */
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
@@ -577,6 +647,8 @@ export interface RendererOptions {
   readonly standardProfile?: RenderProfile | undefined;
   /** Explicit profiler capability shared by App and Render. */
   readonly profiler?: Profiler | undefined;
+  /** Explicitly request timestamp-query for receipt-bound GPU profiling. */
+  readonly captureGpuTimings?: boolean | undefined;
   /** Optional host-owned RHI lifecycle instrumentation, such as recording. */
   readonly rhiInstrumentation?: RhiBackendInstrumentation | undefined;
   // feat-20260608-create-app-param-surface-trim / M1 / AC-02: `clearColor`

package/src/render-data.ts

@@ -15,7 +15,6 @@
 // GPU-resource kind would surface as a `tsc -b` exhaustiveness error at the
 // switch rather than a silent fallthrough (AC-06).
 
-import { numMipLevels } from '@forgeax/engine-assets-runtime';
 import {
   bytesPerRow as blockBytesPerRow,
   blockParamsForFormat,
@@ -29,9 +28,11 @@ import { err, ok, type Result } from '@forgeax/engine-rhi';
 import {
   ASSET_ERROR_HINTS,
   type AssetError,
+  deriveTextureLayout,
   type MeshAsset,
   type Submesh,
   type TextureAsset,
+  type TextureShape,
 } from '@forgeax/engine-types';
 import {
   GPU_TEXTURE_USAGE_COPY_DST,
@@ -88,12 +89,16 @@ export interface MeshRenderData {
   readonly submeshes: readonly Submesh[];
 }
 
-/** Descriptor for a 2D texture's GPU resource (projected from POD). */
+/** Descriptor for a sampled texture's GPU resource (projected from POD). */
 export interface TextureRenderData {
   /** Logical width retained for existing projection consumers. */
   readonly width: number;
   /** Logical height retained for existing projection consumers. */
   readonly height: number;
+  /** Authored shape; the residency layer must preserve this view dimension. */
+  readonly shape: TextureShape;
+  /** Array layers for `2d-array`, depth slices for `3d`, otherwise one. */
+  readonly depthOrArrayLayers: number;
   /** Authored content extent; TextureAsset remains the logical asset SSOT. */
   readonly logicalExtent: TextureExtent;
   /** GPU allocation extent, derived from format + logicalExtent. */
@@ -105,10 +110,10 @@ export interface TextureRenderData {
   readonly usage: number;
   /**
    * Row pitch for the BASE mip (level 0) the store passes to `writeTexture`.
-   * Uncompressed: `width * 4` (RGBA8). Block-compressed: the block-padded
-   * `ceil(width / blockW) * bytesPerBlock` (feat-20260707 M5 / w35, AC-08).
-   * The per-mip layout for a multi-level compressed upload comes from
-   * {@link deriveMipUploadLayout}.
+   * Derived from the canonical texture layout, so format-specific uncompressed
+   * widths (for example R8 density) and block-compressed widths stay aligned
+   * with the upload contract. The per-mip layout for a multi-level compressed
+   * upload comes from {@link deriveMipUploadLayout}.
    */
   readonly bytesPerRow: number;
   /** True iff `format` is a block-compressed format (drives the store's upload arm). */
@@ -262,6 +267,8 @@ export function deriveRenderDataMesh(mesh: MeshAsset): Result<MeshRenderData, As
  * inconsistent (a `-srgb` format requires an `srgb` colorSpace and vice versa).
  */
 export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRenderData, AssetError> {
+  const width = tex.shape.extent.width;
+  const height = tex.shape.extent.height;
   const isSrgbFormat = tex.format.endsWith('-srgb');
   const expectedColorSpace: 'srgb' | 'linear' = isSrgbFormat ? 'srgb' : 'linear';
   if (tex.colorSpace !== expectedColorSpace) {
@@ -275,14 +282,23 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
   }
 
   const compressed = isCompressedFormat(tex.format);
+  const layout = deriveTextureLayout({ shape: tex.shape, format: tex.format, mips: tex.mips });
+  if (!layout.ok) {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: layout.error.expected,
+        hint: layout.error.hint,
+      }),
+    );
+  }
   // feat-20260707 M5 / w35 (AC-09, D-9): a block-compressed texture cannot have
   // its mips GPU-generated (F-7). An OFFLINE chain baked into `data`
   // (mipLevelCount > 1, e.g. a KTX2 level chain) is the normal compressed path
   // and passes; requesting RUNTIME mip generation (`mipmap:true` with no offline
   // chain) fails fast with a self-recovery hint (fail-fast at the projection
   // layer -- producer self-validate).
-  const hasOfflineMipChain = (tex.mipLevelCount ?? 1) > 1;
-  if (compressed && tex.mipmap === true && !hasOfflineMipChain) {
+  if (compressed && tex.mips.kind === 'generate') {
     return err(
       projectionError({
         code: 'mipgen-unsupported-compressed-format',
@@ -296,15 +312,19 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
   // Uncompressed: runtime mip-gen count from the pixel size. Compressed: the
   // level count is authored (offline chain) -- honour the POD's mipLevelCount,
   // never re-derive it from the size (a compressed chain may stop early).
-  const mipLevelCount = compressed
-    ? Math.max(1, tex.mipLevelCount ?? 1)
-    : tex.mipmap
-      ? numMipLevels(tex)
-      : 1;
+  const mipLevelCount = layout.value.levels.length;
 
-  const uncompressedBytesPerTexel =
-    tex.format === 'rgba32float' ? 16 : tex.format === 'rgba16float' ? 8 : 4;
-  if (!compressed && tex.data.byteLength < tex.width * tex.height * uncompressedBytesPerTexel) {
+  const baseLevel = layout.value.levels[0];
+  if (baseLevel === undefined) {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: 'texture layout contains a base mip level',
+        hint: ASSET_ERROR_HINTS['invalid-source-format'],
+      }),
+    );
+  }
+  if (!compressed && tex.data.byteLength < baseLevel.byteLength) {
     return err(
       projectionError({
         code: 'invalid-source-format',
@@ -318,8 +338,8 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
   // from the format, not aggregate payload length: imported images may retain
   // trailing decoder bytes and offline mip chains contain more than the base mip.
   const bytesPerRow = compressed
-    ? (blockBytesPerRow(tex.format, tex.width) ?? tex.width * 4)
-    : tex.width * uncompressedBytesPerTexel;
+    ? (blockBytesPerRow(tex.format, width) ?? baseLevel.bytesPerRow)
+    : baseLevel.bytesPerRow;
 
   // Compressed formats are not renderable -- RENDER_ATTACHMENT would fail
   // createTexture validation, and the runtime mipmap blit (which needs it) never
@@ -333,9 +353,16 @@ export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRender
       GPU_TEXTURE_USAGE_COPY_SRC;
 
   return ok({
-    width: tex.width,
-    height: tex.height,
-    ...deriveTextureExtent(tex.format, tex.width, tex.height),
+    width,
+    height,
+    shape: tex.shape,
+    depthOrArrayLayers:
+      tex.shape.viewDimension === '2d'
+        ? 1
+        : tex.shape.viewDimension === '2d-array'
+          ? tex.shape.extent.layers
+          : tex.shape.extent.depth,
+    ...deriveTextureExtent(tex.format, width, height),
     format: tex.format,
     mipLevelCount,
     usage,
@@ -373,8 +400,9 @@ export function deriveRenderDataCubemap(source: TextureAsset): Result<CubeRender
       }),
     );
   }
+  const sourceHeight = source.shape.viewDimension === '2d' ? source.shape.extent.height : 0;
   return ok({
-    cubeFaceSize: source.height,
+    cubeFaceSize: sourceHeight,
     outputFormat: 'rgba16float',
     needsHalfConversion: source.format === 'rgba32float',
     cubeUsage:

package/src/render-pipeline.ts

@@ -141,6 +141,48 @@ export interface RenderPipelineTopology {
     readonly pointFaceSize: number;
     readonly spotCount: number;
   };
+  /**
+   * Authored volume topology facts.  Identity/generation/digest are runtime
+   * residency facts and deliberately do not participate in graph topology.
+   */
+  readonly volumetricFog?: {
+    readonly enabled: boolean;
+    readonly lightKind?: 'directional' | 'point' | 'spot' | undefined;
+    readonly lightEntity?: number | undefined;
+    readonly pointLightEntity?: number | undefined;
+    readonly spotLightEntity?: number | undefined;
+    readonly projector?:
+      | {
+          readonly guid: string;
+          readonly generation: number;
+          readonly revision: number;
+        }
+      | undefined;
+    readonly format?: TextureFormat | undefined;
+    readonly extent?:
+      | {
+          readonly width: number;
+          readonly height: number;
+          readonly depth: number;
+        }
+      | undefined;
+    /** Renderer-owned froxel grid derived from the compiled surface extent. */
+    readonly froxelExtent?:
+      | {
+          readonly width: number;
+          readonly height: number;
+          readonly depth: number;
+        }
+      | undefined;
+    /** Renderer-owned 2D resolve/history extent derived from the same profile. */
+    readonly resolvedExtent?:
+      | {
+          readonly width: number;
+          readonly height: number;
+          readonly depth: number;
+        }
+      | undefined;
+  };
   readonly lane: {
     readonly compute: boolean;
     readonly storageBuffer: boolean;
@@ -257,6 +299,8 @@ export function importRenderPipelineSurface(
 }
 
 export interface RenderPipelineFeatureTarget {
+  /** Optional semantic alias when a pipeline exposes multiple color roles. */
+  readonly name?: string;
   readonly kind: RenderFeatureTargetKind;
   readonly texture: GraphTexture;
   readonly view: GraphTextureView;