@forgeax/engine-render 0.1.7 → 0.1.20

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

@@ -6,7 +6,7 @@ import type {
   RenderGraphError,
   ResolveContext,
 } from '@forgeax/engine-render-graph';
-import type { TextureView } from '@forgeax/engine-rhi';
+import { RhiError, type TextureView } from '@forgeax/engine-rhi';
 import { ok, type PassKind, type PassSelector, type Result } from '@forgeax/engine-types';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
@@ -26,7 +26,7 @@ import {
   recordBloomBrightPass,
   recordBloomCompositePass,
 } from './record/skybox-post-pass';
-import { STANDARD_TONEMAP_FEATURE_ID } from './render-contract';
+import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from './render-contract';
 import {
   encodeFullscreenPass,
   recordSsaoBlurPass,
@@ -34,6 +34,12 @@ import {
 } from './render-graph-primitives';
 import type { RenderPipelineFrame, RenderPipelineGpuDrivenProjection } from './render-pipeline';
 import { createRenderPipelineTarget, type RenderPipelineTarget } from './render-pipeline';
+import {
+  getTemporalBindGroupResources,
+  getTemporalGpuState,
+  getTemporalParamsBuffer,
+  stageTemporalGpuSubmit,
+} from './temporal/gpu';
 
 function resolvedView(resources: GraphResourceResolver, view: GraphTextureView): TextureView {
   const result = resources.textureView(view);
@@ -41,6 +47,17 @@ function resolvedView(resources: GraphResourceResolver, view: GraphTextureView):
   return result.value;
 }
 
+function throwTemporalEncodeFailure(expected: string, cause?: unknown): never {
+  throw new RhiError({
+    code: 'webgpu-runtime-error',
+    expected,
+    hint:
+      cause === undefined
+        ? 'retry the temporal frame after repairing its GPU resource'
+        : String(cause),
+  });
+}
+
 export function typedFrameClearColor(frame: RenderPipelineFrame): GPUColor {
   return {
     r: frame.clear[0] ?? 0,
@@ -115,6 +132,8 @@ export interface TypedScenePassOptions {
   readonly clearColor?: readonly [number, number, number, number] | undefined;
   readonly colorLoadOp?: GPULoadOp | undefined;
   readonly depthLoadOp?: GPULoadOp | undefined;
+  readonly recordMode?: 'opaque' | 'transmission' | 'transparent' | undefined;
+  readonly transmissionBackdrop?: GraphTextureView | undefined;
   readonly extraAccesses?: readonly GraphAccess[] | undefined;
   readonly gpuDriven?: RenderPipelineGpuDrivenProjection | undefined;
 }
@@ -134,6 +153,9 @@ export function addTypedScenePass(
       resource: target.view,
       usage: 'sampled-read' as const,
     })),
+    ...(options.transmissionBackdrop === undefined
+      ? []
+      : [{ resource: options.transmissionBackdrop, usage: 'sampled-read' as const }]),
     ...(options.extraAccesses ?? []),
     ...(options.gpuDriven?.accesses ?? []),
   ];
@@ -181,6 +203,10 @@ export function addTypedScenePass(
           : resolvedView(resources, options.spotShadow.view);
       const ssao =
         options.ssao === undefined ? undefined : resolvedView(resources, options.ssao.view);
+      const transmissionBackdrop =
+        options.transmissionBackdrop === undefined
+          ? null
+          : resolvedView(resources, options.transmissionBackdrop);
       internal.frameState.currentDirectionalShadowView = directionalShadow ?? null;
       internal.frameState.currentSpotShadowView = spotShadow ?? null;
       const groups = buildPerFrameBindGroups(
@@ -189,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);
@@ -216,6 +248,10 @@ export function addTypedScenePass(
           depthView,
           passKind: options.passKind ?? 'forward',
           ...(options.clearColor === undefined ? {} : { clearColor: options.clearColor }),
+          ...(options.recordMode === undefined ? {} : { recordMode: options.recordMode }),
+          ...(options.transmissionBackdrop === undefined
+            ? {}
+            : { transmissionBackdropView: transmissionBackdrop }),
         },
       );
     },
@@ -261,6 +297,14 @@ export interface TypedBloomTargets {
   readonly blurV: RenderPipelineTarget;
 }
 
+/** The semantic Bloom pass owner; graph inspection consumes these same identities. */
+export const TYPED_BLOOM_PASS_NAMES = {
+  bright: 'bloom-bright',
+  blurH: 'bloom-blur-h',
+  blurV: 'bloom-blur-v',
+  composite: 'bloom-composite',
+} as const;
+
 export function addTypedBloomPasses(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
   targets: TypedBloomTargets,
@@ -274,25 +318,25 @@ export function addTypedBloomPasses(
   };
   const descriptors = [
     {
-      name: 'bloom-bright',
+      name: TYPED_BLOOM_PASS_NAMES.bright,
       reads: [targets.scene],
       write: targets.bright,
       encode: recordBloomBrightPass,
     },
     {
-      name: 'bloom-blur-h',
+      name: TYPED_BLOOM_PASS_NAMES.blurH,
       reads: [targets.bright],
       write: targets.blurH,
       encode: recordBloomBlurHPass,
     },
     {
-      name: 'bloom-blur-v',
+      name: TYPED_BLOOM_PASS_NAMES.blurV,
       reads: [targets.blurH],
       write: targets.blurV,
       encode: recordBloomBlurVPass,
     },
     {
-      name: 'bloom-composite',
+      name: TYPED_BLOOM_PASS_NAMES.composite,
       reads: [targets.scene, targets.blurV],
       write: targets.composited,
       encode: recordBloomCompositePass,
@@ -419,6 +463,116 @@ export interface TypedFullscreenPassOptions {
   readonly outputOnly?: boolean | undefined;
   readonly rawSwapchainOutput?: boolean | undefined;
   readonly depth?: RenderPipelineTarget | undefined;
+  readonly additionalReads?: readonly {
+    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 {
+  readonly scene: RenderPipelineTarget;
+  readonly currentTemporal: RenderPipelineTarget;
+  readonly depth: RenderPipelineTarget;
+  readonly historyColor: RenderPipelineTarget;
+  readonly historyTemporal: RenderPipelineTarget;
+  readonly writeColor: RenderPipelineTarget;
+  readonly writeTemporal: RenderPipelineTarget;
+}
+
+export function addTypedTemporalResolvePass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  targets: TypedTemporalResolveTargets,
+): Result<void, RenderGraphError> {
+  const added = graph.addRasterPass('taa-resolve', {
+    accesses: [
+      { resource: targets.scene.view, usage: 'sampled-read' },
+      { resource: targets.currentTemporal.view, usage: 'sampled-read' },
+      { resource: targets.historyColor.view, usage: 'sampled-read' },
+      { resource: targets.historyTemporal.view, usage: 'sampled-read' },
+      { resource: targets.writeColor.view, usage: 'color-attachment' },
+      { resource: targets.writeTemporal.view, usage: 'color-attachment' },
+    ],
+    colorAttachments: [
+      {
+        view: targets.writeColor.view,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+      },
+      {
+        view: targets.writeTemporal.view,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+      },
+    ],
+    encode: ({ pass, frame, resources }) => {
+      const internal = frame as _InternalRenderPipelineContext;
+      const state = getTemporalGpuState(
+        internal.frameState,
+        frame.runtime.device,
+        (frame.runtime as import('./record/render-context').RenderSystemRuntime).deviceScope,
+        frame.targetW,
+        frame.targetH,
+      );
+      const built = getTemporalBindGroupResources(state);
+      const current = resolvedView(resources, targets.scene.view);
+      const currentTemporal = resolvedView(resources, targets.currentTemporal.view);
+      const historyColor = resolvedView(resources, targets.historyColor.view);
+      const historyTemporal = resolvedView(resources, targets.historyTemporal.view);
+      const params = getTemporalParamsBuffer(state);
+      if (params === undefined || built.sampler === null) {
+        throwTemporalEncodeFailure('TAA resolve has an admitted params buffer and sampler');
+      }
+      const payload = new ArrayBuffer(16);
+      new Float32Array(payload).set([
+        frame.camera.temporal?.currentJitterUv?.[0] ?? 0,
+        frame.camera.temporal?.currentJitterUv?.[1] ?? 0,
+      ]);
+      const words = new Uint32Array(payload);
+      words[2] = state.valid && (frame.camera.temporal?.historyValid ?? true) ? 1 : 0;
+      words[3] = frame.camera.temporal?.temporalFrameIndex ?? 0;
+      const written = frame.runtime.device.queue.writeBuffer(params, 0, new Uint8Array(payload));
+      if (!written.ok)
+        throwTemporalEncodeFailure('TAA resolve params upload succeeds', written.error);
+      const bindGroup = frame.runtime.device.createBindGroup({
+        label: 'taa-resolve-bind-group',
+        layout: built.layout,
+        entries: [
+          { binding: 0, resource: { kind: 'textureView', value: current } },
+          { binding: 1, resource: { kind: 'sampler', value: built.sampler } },
+          { binding: 2, resource: { kind: 'textureView', value: historyColor } },
+          { binding: 3, resource: { kind: 'sampler', value: built.sampler } },
+          { binding: 4, resource: { kind: 'textureView', value: historyTemporal } },
+          { binding: 5, resource: { kind: 'sampler', value: built.sampler } },
+          { binding: 6, resource: { kind: 'textureView', value: currentTemporal } },
+          { binding: 7, resource: { kind: 'sampler', value: built.sampler } },
+          { binding: 8, resource: { kind: 'buffer', value: { buffer: params } } },
+        ] as never,
+      });
+      if (!bindGroup.ok) {
+        throwTemporalEncodeFailure('TAA resolve bind group creation succeeds', bindGroup.error);
+      }
+      const pipeline = frame.runtime.getPostProcessPipeline?.(
+        'forgeax.taa-resolve',
+        built.layout,
+        targets.writeColor.format as GPUTextureFormat,
+      );
+      if (pipeline === null || pipeline === undefined) {
+        throwTemporalEncodeFailure('TAA resolve pipeline is ready before frame encoding');
+      }
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(1, bindGroup.value);
+      pass.draw(3, 1, 0, 0);
+      stageTemporalGpuSubmit(state);
+      internal.frameState.temporalGpuState = state;
+    },
+  });
+  return added;
 }
 
 export function addTypedFullscreenPass(
@@ -432,6 +586,10 @@ export function addTypedFullscreenPass(
       ...(options.depth === undefined
         ? []
         : [{ resource: options.depth.view, usage: 'sampled-read' as const }]),
+      ...(options.additionalReads?.map((read) => ({
+        resource: read.target.view,
+        usage: 'sampled-read' as const,
+      })) ?? []),
     ],
     colorAttachments: [
       {
@@ -454,6 +612,11 @@ export function addTypedFullscreenPass(
           input: options.input,
           output: options.output,
           ldrColor: options.input,
+          'scene-color': options.input,
+          ...(options.depth === undefined ? {} : { 'scene-depth': options.depth }),
+          ...(options.additionalReads === undefined
+            ? {}
+            : Object.fromEntries(options.additionalReads.map((read) => [read.key, read.target]))),
         }),
         outputFormat: options.output.format as GPUTextureFormat,
         ...(options.depth === undefined
@@ -462,6 +625,11 @@ export function addTypedFullscreenPass(
         ...(options.rawSwapchainOutput === undefined
           ? {}
           : { rawSwapchainOutput: options.rawSwapchainOutput }),
+        ...(options.paramsTransform === undefined
+          ? {}
+          : {
+              paramsOverride: options.paramsTransform(frame.postProcessParams.get(options.shader)),
+            }),
       });
     },
   });
@@ -524,18 +692,33 @@ export function addTypedCompositePostEffects(
   return ok(undefined);
 }
 
-export function addTypedTonemapPass(
+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 ? 'output' : 'tonemap',
-    shader: STANDARD_TONEMAP_FEATURE_ID,
+    name: outputOnly ? 'present' : 'output-transform',
+    shader: STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
     input,
     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 });
+}