@forgeax/engine-render 0.1.19 → 0.1.21

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 });
+}

package/src/volume/inspection.ts

@@ -0,0 +1,78 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import type { VolumeRecoveryState, VolumeSelectedLightFacts } from './recovery';
+import type { VolumetricFogResourceFacts } from './resources';
+
+export type VolumetricFogInspectionStatus = 'off' | 'available' | 'unavailable' | 'degraded';
+
+export type VolumetricFogResourceStage = 'none' | 'candidate' | 'accepted' | 'lkg' | 'recovering';
+
+export interface VolumetricFogInspection {
+  readonly status: VolumetricFogInspectionStatus;
+  readonly resourceStage: VolumetricFogResourceStage;
+  readonly guid: string | undefined;
+  readonly generation: number | undefined;
+  readonly digest: string | undefined;
+  readonly candidateGeneration: number | undefined;
+  readonly candidateDigest: string | undefined;
+  readonly lkgGeneration: number | undefined;
+  readonly candidateFailure: VolumeRecoveryState['candidateFailure'];
+  readonly deviceEpoch: number;
+  readonly format: TextureFormat | undefined;
+  readonly passCount: number;
+  readonly sampleCount: number;
+  readonly memoryBytes: number;
+  readonly resourceFacts: VolumetricFogResourceFacts | undefined;
+  readonly selectedLight: VolumeSelectedLightFacts | undefined;
+  readonly candidateSelectedLight: VolumeSelectedLightFacts | undefined;
+}
+
+export interface VolumetricFogInspectionInput {
+  readonly authored: boolean;
+  readonly capability: 'available' | 'unavailable';
+  readonly degraded?: boolean;
+  readonly recovery?: VolumeRecoveryState;
+  readonly acceptedDigest?: string;
+  readonly format?: TextureFormat;
+  readonly passCount?: number;
+  readonly sampleCount?: number;
+  readonly memoryBytes?: number;
+  readonly resourceFacts?: VolumetricFogResourceFacts;
+}
+
+function resourceStage(input: VolumetricFogInspectionInput): VolumetricFogResourceStage {
+  if (!input.authored || input.recovery === undefined) return 'none';
+  if (input.recovery.status === 'candidate') return 'candidate';
+  if (input.recovery.status === 'recovering') return 'recovering';
+  if (input.recovery.status === 'degraded') return 'lkg';
+  return 'accepted';
+}
+
+export function inspectVolumetricFog(input: VolumetricFogInspectionInput): VolumetricFogInspection {
+  const recovery = input.recovery;
+  const status: VolumetricFogInspectionStatus = !input.authored
+    ? 'off'
+    : input.capability === 'unavailable'
+      ? 'unavailable'
+      : input.degraded === true || recovery?.status === 'degraded'
+        ? 'degraded'
+        : 'available';
+  return Object.freeze({
+    status,
+    resourceStage: resourceStage(input),
+    guid: recovery?.guid,
+    generation: recovery?.generation,
+    digest: input.acceptedDigest,
+    candidateGeneration: recovery?.candidateGeneration,
+    candidateDigest: recovery?.candidateDigest,
+    lkgGeneration: recovery?.lkgGeneration,
+    candidateFailure: recovery?.candidateFailure,
+    deviceEpoch: recovery?.deviceEpoch ?? 0,
+    format: input.format,
+    passCount: input.passCount ?? 0,
+    sampleCount: input.sampleCount ?? 0,
+    memoryBytes: input.memoryBytes ?? 0,
+    resourceFacts: input.resourceFacts,
+    selectedLight: recovery?.selectedLight,
+    candidateSelectedLight: recovery?.candidateSelectedLight,
+  });
+}