@forgeax/engine-render 0.1.19 → 0.1.20

package/src/renderer-inspect.ts

@@ -0,0 +1,66 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import type { TemporalFrame, TemporalResetReason } from './temporal/frame';
+
+export type TemporalInspectionStatus =
+  | 'authored-off'
+  | 'available'
+  | 'capability-unavailable'
+  | 'temporal-degraded';
+
+export interface TemporalInspection {
+  readonly status: TemporalInspectionStatus;
+  readonly resetReason: TemporalResetReason;
+  readonly historyEpoch: number;
+  readonly deviceEpoch: number;
+  readonly backend: string | undefined;
+  readonly format: TextureFormat | undefined;
+  readonly limits: Readonly<{
+    readonly maxTextureDimension2D?: number;
+    readonly maxTextureDimension3D?: number;
+    readonly maxTextureArrayLayers?: number;
+  }>;
+  readonly compute: 'available' | 'unavailable';
+  readonly storage: 'available' | 'unavailable';
+}
+
+export interface TemporalInspectionInput {
+  readonly authored: boolean;
+  readonly capability: 'available' | 'unavailable';
+  readonly degraded?: boolean;
+  readonly frame?: TemporalFrame;
+  readonly backend?: string;
+  readonly format?: TextureFormat;
+  readonly limits?: Readonly<Record<string, number>>;
+}
+
+export function inspectTemporalFrame(input: TemporalInspectionInput): TemporalInspection {
+  const frame = input.frame;
+  const status: TemporalInspectionStatus = !input.authored
+    ? 'authored-off'
+    : input.capability === 'unavailable'
+      ? 'capability-unavailable'
+      : input.degraded === true
+        ? 'temporal-degraded'
+        : 'available';
+  return Object.freeze({
+    status,
+    resetReason: frame?.resetReason ?? 'none',
+    historyEpoch: frame?.historyEpoch ?? 0,
+    deviceEpoch: frame?.deviceEpoch ?? 0,
+    backend: input.backend,
+    format: input.format,
+    limits: Object.freeze({
+      ...(typeof input.limits?.maxTextureDimension2D === 'number'
+        ? { maxTextureDimension2D: input.limits.maxTextureDimension2D }
+        : {}),
+      ...(typeof input.limits?.maxTextureDimension3D === 'number'
+        ? { maxTextureDimension3D: input.limits.maxTextureDimension3D }
+        : {}),
+      ...(typeof input.limits?.maxTextureArrayLayers === 'number'
+        ? { maxTextureArrayLayers: input.limits.maxTextureArrayLayers }
+        : {}),
+    }),
+    compute: input.capability === 'available' ? 'available' : 'unavailable',
+    storage: input.capability === 'available' ? 'available' : 'unavailable',
+  });
+}

package/src/scene/render-scene.ts

@@ -47,6 +47,7 @@ import {
   type TransmissionDemand,
   type TransmissionDemandOperation,
 } from '../transmission/projection';
+import { VolumetricFog } from '../volume/component';
 import type {
   RenderSceneApplyResult,
   RenderSceneBounds,
@@ -761,6 +762,7 @@ const RENDER_RELEVANT_COMPONENT_IDS = new Set([
   componentId(Skylight),
   componentId(SkyboxBackground),
   componentId(PostProcessParams),
+  componentId(VolumetricFog),
 ]);
 
 const NON_RENDERABLE_TRANSFORM_CONSUMERS = [

package/src/temporal/frame.ts

@@ -0,0 +1,128 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { TemporalFrameSubmitError } from '../errors/render';
+
+export type TemporalResetReason =
+  | 'none'
+  | 'camera-cut'
+  | 'resize'
+  | 'signature-change'
+  | 'depth-discontinuity'
+  | 'out-of-screen'
+  | 'queue-submit-failed'
+  | 'device-recovery';
+
+export interface TemporalFrameInput {
+  readonly frameId: number;
+  readonly currentViewProjection: Float32Array;
+  readonly jitter: readonly [number, number];
+  readonly viewport: { readonly width: number; readonly height: number };
+  /** Current camera origin, retained only as accepted temporal history. */
+  readonly cameraPosition?: readonly [number, number, number];
+  readonly resetReason?: Exclude<TemporalResetReason, 'none' | 'queue-submit-failed'>;
+}
+
+export interface TemporalFrame {
+  readonly frameId: number;
+  readonly currentViewProjection: Float32Array;
+  readonly previousViewProjection: Float32Array | undefined;
+  readonly jitter: readonly [number, number];
+  readonly viewport: { readonly width: number; readonly height: number };
+  readonly currentCameraPosition: readonly [number, number, number];
+  readonly previousCameraPosition: readonly [number, number, number] | undefined;
+  readonly resetReason: TemporalResetReason;
+  readonly historyEpoch: number;
+  readonly deviceEpoch: number;
+}
+
+export interface TemporalSubmitResult {
+  readonly accepted: boolean;
+  readonly reason?: 'queue-submit-failed';
+  readonly resetReason?: Exclude<TemporalResetReason, 'none' | 'queue-submit-failed'>;
+}
+
+export interface TemporalFrameTransaction {
+  stage(input: TemporalFrameInput): void;
+  commit(submit: TemporalSubmitResult): Result<TemporalFrame, TemporalFrameSubmitError>;
+  snapshot(): TemporalFrame;
+}
+
+function copyInput(input: TemporalFrameInput): TemporalFrameInput {
+  return {
+    ...input,
+    currentViewProjection: new Float32Array(input.currentViewProjection),
+    jitter: [input.jitter[0], input.jitter[1]],
+    viewport: { ...input.viewport },
+    ...(input.cameraPosition === undefined
+      ? {}
+      : { cameraPosition: [...input.cameraPosition] as [number, number, number] }),
+  };
+}
+
+function copyFrame(frame: TemporalFrame): TemporalFrame {
+  return {
+    ...frame,
+    currentViewProjection: new Float32Array(frame.currentViewProjection),
+    previousViewProjection:
+      frame.previousViewProjection === undefined
+        ? undefined
+        : new Float32Array(frame.previousViewProjection),
+    jitter: [frame.jitter[0], frame.jitter[1]],
+    viewport: { ...frame.viewport },
+    currentCameraPosition: [...frame.currentCameraPosition] as [number, number, number],
+    previousCameraPosition:
+      frame.previousCameraPosition === undefined
+        ? undefined
+        : ([...frame.previousCameraPosition] as [number, number, number]),
+  };
+}
+
+export function createTemporalFrameTransaction(options: {
+  readonly deviceEpoch: number;
+}): TemporalFrameTransaction {
+  let accepted: TemporalFrame | undefined;
+  let staged: TemporalFrameInput | undefined;
+  let historyEpoch = 0;
+
+  return {
+    stage(input) {
+      staged = copyInput(input);
+    },
+    commit(submit) {
+      if (!submit.accepted) {
+        staged = undefined;
+        return err(new TemporalFrameSubmitError(submit.reason ?? 'queue-submit-failed'));
+      }
+      if (staged === undefined) {
+        return err(new TemporalFrameSubmitError('queue-submit-failed'));
+      }
+
+      const resetReason = submit.resetReason ?? staged.resetReason ?? 'none';
+      const shouldReset = resetReason !== 'none';
+      if (shouldReset) historyEpoch += 1;
+      const next: TemporalFrame = {
+        frameId: staged.frameId,
+        currentViewProjection: new Float32Array(staged.currentViewProjection),
+        previousViewProjection:
+          accepted === undefined || shouldReset
+            ? undefined
+            : new Float32Array(accepted.currentViewProjection),
+        jitter: [staged.jitter[0], staged.jitter[1]],
+        viewport: { ...staged.viewport },
+        currentCameraPosition: staged.cameraPosition ?? [0, 0, 0],
+        previousCameraPosition:
+          accepted === undefined || shouldReset ? undefined : accepted.currentCameraPosition,
+        resetReason,
+        historyEpoch,
+        deviceEpoch: options.deviceEpoch,
+      };
+      accepted = next;
+      staged = undefined;
+      return ok(copyFrame(next));
+    },
+    snapshot() {
+      if (accepted === undefined)
+        throw new Error('TemporalFrame snapshot is unavailable before commit');
+      return copyFrame(accepted);
+    },
+  };
+}

package/src/transmission/__tests__/standard-transmission.dawn.test.ts

@@ -65,12 +65,11 @@ function textureAsset(value: number): TextureAsset {
   const channel = Math.round(value * 255);
   return {
     kind: 'texture',
-    width: 1,
-    height: 1,
+    shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
     format: 'rgba8unorm',
     data: Uint8Array.from([channel, channel, channel, 255]),
     colorSpace: 'linear',
-    mipmap: false,
+    mips: { kind: 'none' },
   };
 }
 

package/src/typed-render-graph-primitives.ts

@@ -215,7 +215,13 @@ export function addTypedScenePass(
         internal.pipelineState,
         internal.validated.length > 0 || options.gpuDriven !== undefined,
         internal.bindGroupCounts,
-        { directionalShadow, spotShadow },
+        {
+          directionalShadow,
+          spotShadow,
+          projector: internal.spotLightProjector?.view ?? internal.volumetricFog?.projectorView,
+          projectorSampler:
+            internal.spotLightProjector?.sampler ?? internal.volumetricFog?.projectorSampler,
+        },
       );
       if (groups.viewBindGroup !== null) {
         options.gpuDriven?.encode(groups.viewBindGroup, pass, resources);
@@ -461,6 +467,10 @@ export interface TypedFullscreenPassOptions {
     readonly key: string;
     readonly target: RenderPipelineTarget;
   }[];
+  /** Optional per-pass copy of the params UBO payload. */
+  readonly paramsTransform?:
+    | ((params: Uint8Array | undefined) => Uint8Array | undefined)
+    | undefined;
 }
 
 export interface TypedTemporalResolveTargets {
@@ -615,6 +625,11 @@ export function addTypedFullscreenPass(
         ...(options.rawSwapchainOutput === undefined
           ? {}
           : { rawSwapchainOutput: options.rawSwapchainOutput }),
+        ...(options.paramsTransform === undefined
+          ? {}
+          : {
+              paramsOverride: options.paramsTransform(frame.postProcessParams.get(options.shader)),
+            }),
       });
     },
   });
@@ -681,8 +696,9 @@ export function addTypedOutputTransformPass(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   input: RenderPipelineTarget,
   output: RenderPipelineTarget,
-  outputOnly = false,
+  options: { readonly outputOnly?: boolean; readonly outputTransform?: boolean } = {},
 ): Result<void, RenderGraphError> {
+  const outputOnly = options.outputOnly ?? false;
   return addTypedFullscreenPass(graph, {
     name: outputOnly ? 'present' : 'output-transform',
     shader: STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
@@ -690,5 +706,19 @@ export function addTypedOutputTransformPass(
     output,
     outputOnly,
     rawSwapchainOutput: outputOnly,
+    ...(options.outputTransform === true
+      ? {
+          paramsTransform: (params: Uint8Array | undefined): Uint8Array | undefined => {
+            if (params === undefined || params.byteLength !== 16) return params;
+            const transformed = params.slice();
+            new DataView(
+              transformed.buffer,
+              transformed.byteOffset,
+              transformed.byteLength,
+            ).setFloat32(12, 1, true);
+            return transformed;
+          },
+        }
+      : {}),
   });
 }

package/src/typed-shadow-atlas.ts

@@ -0,0 +1,17 @@
+export interface DirectionalShadowAtlasGrid {
+  readonly columns: 1 | 2;
+  readonly rows: 1 | 2;
+}
+
+/**
+ * The directional CSM atlas layout is one compact contract for raster writes
+ * and shader reads: 1 -> 1x1, 2 -> 2x1, and 3/4 -> 2x2.
+ */
+export function resolveDirectionalShadowAtlasGrid(
+  cascadeCount: number,
+): DirectionalShadowAtlasGrid {
+  const count = Math.max(1, Math.min(4, Math.round(cascadeCount)));
+  if (count === 1) return { columns: 1, rows: 1 };
+  if (count === 2) return { columns: 2, rows: 1 };
+  return { columns: 2, rows: 2 };
+}

package/src/typed-shadow-passes.ts

@@ -10,6 +10,7 @@ import {
 } from './record/shadow-pass';
 import type { RenderPipelineFrame, RenderPipelineTopology } from './render-pipeline';
 import { createRenderPipelineTarget, type RenderPipelineTarget } from './render-pipeline';
+import { resolveDirectionalShadowAtlasGrid } from './typed-shadow-atlas';
 
 export interface TypedShadowTargets {
   readonly directional: RenderPipelineTarget;
@@ -43,18 +44,18 @@ export function addTypedShadowPasses(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   topology: RenderPipelineTopology,
 ): Result<TypedShadowTargets, RenderGraphError> {
-  const tilesPerSide = Math.ceil(Math.sqrt(topology.shadow.cascadeCount));
+  const atlasGrid = resolveDirectionalShadowAtlasGrid(topology.shadow.cascadeCount);
   const directional = createRenderPipelineTarget(graph, 'directional-shadow-depth', {
     format: 'depth32float',
     size: {
-      width: topology.shadow.mapSize * tilesPerSide,
-      height: topology.shadow.mapSize * tilesPerSide,
+      width: topology.shadow.mapSize * atlasGrid.columns,
+      height: topology.shadow.mapSize * atlasGrid.rows,
     },
   });
   if (!directional.ok) return directional;
   for (let cascade = 0; cascade < topology.shadow.cascadeCount; cascade += 1) {
-    const col = cascade % tilesPerSide;
-    const row = Math.floor(cascade / tilesPerSide);
+    const col = cascade % atlasGrid.columns;
+    const row = Math.floor(cascade / atlasGrid.columns);
     const added = recordShadowPass(
       graph,
       `shadowCascade${cascade}`,

package/src/volume/capability.ts

@@ -0,0 +1,173 @@
+import { Entity, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { Transform } from '@forgeax/engine-scene';
+import { DirectionalLight } from '../components/directional-light';
+import { PointLight } from '../components/point-light';
+import { SpotLight } from '../components/spot-light';
+
+/**
+ * The single capability predicate for the authored volumetric-fog producer.
+ * Shader sources are part of the device-bound bundle: compute/storage alone
+ * is not enough to claim that the three fused graph passes can execute.
+ */
+export function hasVolumetricFogCapability(
+  caps: Pick<RhiCaps, 'compute' | 'storageTexture'>,
+  shaders: unknown,
+): boolean {
+  return caps.compute && caps.storageTexture && shaders !== undefined;
+}
+
+export type VolumetricFogLightKind = 'directional' | 'point' | 'spot';
+// The exact parity authoring mode is the closed `point-spot` pair.
+
+export type VolumetricFogLightResolution =
+  | {
+      readonly status: 'available';
+      readonly entity: EntityHandle;
+      readonly kind: VolumetricFogLightKind;
+    }
+  | {
+      readonly status: 'unresolved';
+      readonly reason: 'missing-entity' | 'wrong-component' | 'ambiguous';
+      readonly entity: EntityHandle;
+      readonly expected: 'DirectionalLight | PointLight | SpotLight';
+      readonly actual: string;
+      readonly hint: string;
+    };
+
+export type VolumetricFogLightPairResolution =
+  | {
+      readonly status: 'available';
+      readonly mode: 'point-spot';
+      readonly point: EntityHandle;
+      readonly spot: EntityHandle;
+    }
+  | {
+      readonly status: 'unresolved';
+      readonly reason: 'missing-entity' | 'same-entity' | 'wrong-component';
+      readonly point: EntityHandle;
+      readonly spot: EntityHandle;
+      readonly expected: 'PointLight + SpotLight in the same World';
+      readonly actual: string;
+      readonly hint: string;
+    };
+
+/** Resolve the narrow official Point+Spot pair without creating a light owner. */
+export function resolveVolumetricFogLightPair(
+  world: World,
+  point: EntityHandle,
+  spot: EntityHandle,
+): VolumetricFogLightPairResolution {
+  const expected = 'PointLight + SpotLight in the same World' as const;
+  if (!world.get(point, Entity).ok || !world.get(spot, Entity).ok) {
+    return {
+      status: 'unresolved',
+      reason: 'missing-entity',
+      point,
+      spot,
+      expected,
+      actual: 'point or spot entity is absent from this World',
+      hint: 'assign two live entities from the same World and retry',
+    };
+  }
+  if (point === spot) {
+    return {
+      status: 'unresolved',
+      reason: 'same-entity',
+      point,
+      spot,
+      expected,
+      actual: 'PointLight and SpotLight share one EntityHandle',
+      hint: 'spawn PointLight and SpotLight on two different entities',
+    };
+  }
+  const pointValid = world.hasComponent(point, PointLight) && world.hasComponent(point, Transform);
+  const spotValid = world.hasComponent(spot, SpotLight) && world.hasComponent(spot, Transform);
+  if (!pointValid || !spotValid) {
+    return {
+      status: 'unresolved',
+      reason: 'wrong-component',
+      point,
+      spot,
+      expected,
+      actual: `pointValid=${pointValid}; spotValid=${spotValid}`,
+      hint: 'attach PointLight and SpotLight with Transform to separate same-World entities',
+    };
+  }
+  return { status: 'available', mode: 'point-spot', point, spot };
+}
+
+/**
+ * Resolve the required VolumetricFog.light reference in its owning World.
+ * PointLight is a valid primary selection for the exact Point+Spot pair.
+ * EntityHandle has no portable world tag, so a handle absent from this World
+ * (the same World contract) is reported as missing-entity;
+ * is reported as missing-entity; callers must not manufacture a light.
+ */
+export function resolveSelectedVolumetricLight(
+  world: World,
+  entity: EntityHandle,
+): VolumetricFogLightResolution {
+  const expected = 'DirectionalLight | PointLight | SpotLight' as const;
+  if (!world.get(entity, Entity).ok) {
+    return {
+      status: 'unresolved',
+      reason: 'missing-entity',
+      entity,
+      expected,
+      actual: 'missing or foreign World entity',
+      hint: 'assign VolumetricFog.light to a live DirectionalLight or SpotLight in this World',
+    };
+  }
+  const hasDirectional = world.hasComponent(entity, DirectionalLight);
+  const hasSpot = world.hasComponent(entity, SpotLight);
+  if (hasDirectional && hasSpot) {
+    return {
+      status: 'unresolved',
+      reason: 'ambiguous',
+      entity,
+      expected,
+      actual: 'DirectionalLight + SpotLight',
+      hint: 'remove one mutually exclusive light component from the selected entity',
+    };
+  }
+  if (hasDirectional) return { status: 'available', entity, kind: 'directional' };
+  if (world.hasComponent(entity, PointLight) && world.hasComponent(entity, Transform)) {
+    return { status: 'available', entity, kind: 'point' };
+  }
+  if (hasSpot && world.hasComponent(entity, Transform)) {
+    return { status: 'available', entity, kind: 'spot' };
+  }
+  const actual = hasSpot
+    ? 'SpotLight without Transform'
+    : world.hasComponent(entity, PointLight)
+      ? 'PointLight'
+      : 'other component';
+  return {
+    status: 'unresolved',
+    reason: 'wrong-component',
+    entity,
+    expected,
+    actual,
+    hint: 'add exactly one supported light component and a Transform for PointLight or SpotLight in the same World',
+  };
+}
+
+export interface IntegratedVolumeResource {
+  /** Logical resolved-volume identity; this is not a physical graph resource. */
+  readonly identity: 'volume-integrated';
+  readonly format: 'rgba16float';
+  readonly stage: 'resolved';
+}
+
+export type VolumeConsumer = 'opaque' | 'transparent' | 'sprite' | 'vfx' | 'custom';
+
+export function resolveIntegratedVolumeConsumer(
+  resource: IntegratedVolumeResource,
+  consumer: VolumeConsumer,
+): { readonly consumer: VolumeConsumer; readonly resource: IntegratedVolumeResource } {
+  // The volume owner supplies this prepared logical resource. Consumers only
+  // receive its identity and format; they never allocate a view or own the
+  // history lifetime here.
+  return { consumer, resource };
+}

package/src/volume/component.ts

@@ -0,0 +1,110 @@
+import { defineComponent, type EntityHandle } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  VolumeDensityShapeMismatchError,
+  type VolumeError,
+  VolumeInvalidBoundsError,
+  VolumeInvalidParametersError,
+  VolumeOwnerConflictError,
+} from '../errors/render';
+
+export interface VolumeDensityBinding {
+  readonly guid: string;
+  readonly generation: number;
+  readonly shape: {
+    readonly viewDimension: '2d' | '2d-array' | '3d';
+    readonly extent: {
+      readonly width: number;
+      readonly height: number;
+      readonly depth?: number;
+      readonly layers?: number;
+    };
+  };
+  readonly format: string;
+  readonly colorSpace?: 'linear' | 'srgb';
+}
+
+export interface VolumeBounds {
+  readonly min: readonly [number, number, number];
+  readonly max: readonly [number, number, number];
+}
+
+export interface VolumetricFogAuthoring {
+  /** Invalid authoring reports closed code, expected, hint, and detail fields. */
+  /** The selected DirectionalLight or PointLight in this World. */
+  readonly light: EntityHandle;
+  /** The optional same-World SpotLight paired with a PointLight. */
+  readonly spotLight?: EntityHandle;
+  readonly density: VolumeDensityBinding;
+  readonly bounds: VolumeBounds;
+  readonly extinction: readonly [number, number, number];
+  readonly albedo: readonly [number, number, number];
+  readonly emission: readonly [number, number, number];
+  readonly anisotropy: number;
+  readonly maxDistance: number;
+  readonly ownerCount?: number;
+}
+
+export type VolumetricFogLightSelection =
+  | { readonly light: EntityHandle; readonly spotLight?: undefined }
+  | { readonly light: EntityHandle; readonly spotLight: EntityHandle };
+
+export interface ValidatedVolumetricFog extends VolumetricFogAuthoring {
+  readonly ownerCount: 1;
+}
+
+export const VolumetricFog = defineComponent('VolumetricFog', {
+  light: { type: 'entity' },
+  spotLight: { type: 'entity' },
+  density: { type: 'shared<TextureAsset>', simulationTransient: true },
+  boundsMin: { type: 'array<f32, 3>' },
+  boundsMax: { type: 'array<f32, 3>' },
+  extinction: { type: 'array<f32, 3>' },
+  albedo: { type: 'array<f32, 3>' },
+  emission: { type: 'array<f32, 3>' },
+  anisotropy: { type: 'f32', default: 0 },
+  maxDistance: { type: 'f32', default: 100 },
+});
+
+function finiteVector(value: readonly [number, number, number]): boolean {
+  return value.every(Number.isFinite);
+}
+
+function validBounds(bounds: VolumeBounds): boolean {
+  if (!finiteVector(bounds.min) || !finiteVector(bounds.max)) return false;
+  return bounds.max.every((value, index) => value > (bounds.min[index] ?? value));
+}
+
+function validRange(
+  value: readonly [number, number, number],
+  min: number,
+  max = Infinity,
+): boolean {
+  return value.every((entry) => Number.isFinite(entry) && entry >= min && entry <= max);
+}
+
+export function validateVolumetricFog(
+  input: VolumetricFogAuthoring,
+): Result<ValidatedVolumetricFog, VolumeError> {
+  const ownerCount = input.ownerCount ?? 1;
+  if (ownerCount !== 1) return err(new VolumeOwnerConflictError(ownerCount));
+  if (input.density.shape.viewDimension !== '3d' || input.density.colorSpace === 'srgb') {
+    return err(
+      new VolumeDensityShapeMismatchError(input.density.guid, input.density.shape.viewDimension),
+    );
+  }
+  if (!validBounds(input.bounds)) return err(new VolumeInvalidBoundsError(input.bounds));
+  if (
+    !validRange(input.extinction, 0) ||
+    !validRange(input.albedo, 0, 1) ||
+    !validRange(input.emission, 0) ||
+    !Number.isFinite(input.anisotropy) ||
+    input.anisotropy <= -1 ||
+    input.anisotropy >= 1 ||
+    !Number.isFinite(input.maxDistance) ||
+    input.maxDistance <= 0
+  ) {
+    return err(new VolumeInvalidParametersError(input));
+  }
+  return ok({ ...input, ownerCount: 1 });
+}

package/src/volume/extract.ts

@@ -0,0 +1,21 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { type VolumeError, VolumeOwnerConflictError } from '../errors/render';
+import {
+  type ValidatedVolumetricFog,
+  type VolumetricFogAuthoring,
+  validateVolumetricFog,
+} from './component';
+
+export type VolumetricFogExtract =
+  | { readonly status: 'off' }
+  | { readonly status: 'available'; readonly fog: ValidatedVolumetricFog };
+
+export function extractVolumetricFog(
+  inputs: readonly VolumetricFogAuthoring[],
+): Result<VolumetricFogExtract, VolumeError> {
+  if (inputs.length === 0) return ok({ status: 'off' });
+  if (inputs.length !== 1) return err(new VolumeOwnerConflictError(inputs.length));
+  const validated = validateVolumetricFog(inputs[0] as VolumetricFogAuthoring);
+  if (!validated.ok) return validated;
+  return ok({ status: 'available', fog: validated.value });
+}