@forgeax/engine-render 0.1.7 → 0.1.20

package/src/errors/render.ts

@@ -13,6 +13,11 @@
 // SpotLight / PointLightShadow component validators (forward cross-directory
 // import, no cycle -- research Finding C2).
 
+import type {
+  RenderSurfaceFailureDetail,
+  SurfaceFailureCode,
+  SurfaceFailureKind,
+} from '@forgeax/engine-render-graph';
 import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
 import type {
   PreparedKind,
@@ -20,6 +25,8 @@ import type {
   RenderFeatureRecovery,
   RenderFeatureStage,
 } from '../features/vocabulary';
+import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
+import type { TransmissionCapabilityFact } from '../transmission/backdrop';
 
 export interface LifecycleConstructionFailureDetail {
   readonly owner: string;
@@ -47,6 +54,85 @@ export class LifecycleConstructionError extends Error {
   }
 }
 
+const SURFACE_FAILURE_POLICY: Readonly<
+  Record<SurfaceFailureCode, { readonly expected: string; readonly hint: string }>
+> = {
+  'surface-allocation-failed': {
+    expected: 'the required surface resource can be allocated with its declared format and usage',
+    hint: 'inspect the capability detail, release transient resources, and retry the candidate graph',
+  },
+  'surface-attachment-failed': {
+    expected: 'the float target is renderable as the declared attachment',
+    hint: 'verify float color attachment support and retry without hiding the failure',
+  },
+  'surface-sampled-read-failed': {
+    expected: 'the float target can be sampled by the next post-processing stage',
+    hint: 'verify sampled-read support for the declared format before rebuilding the graph',
+  },
+  'surface-view-domain-failed': {
+    expected: 'surface storage and display views preserve their declared color domains',
+    hint: 'repair the explicit format/domain pair and retry the candidate graph',
+  },
+  'surface-raw-endpoint-failed': {
+    expected: 'the surface presentation endpoint has descriptor, acquisition, and validation proof',
+    hint: 'run the concrete presentation probe; keep the last-known-good surface when proof is absent',
+  },
+};
+
+/** Render-surface failure with an exhaustive code and actionable detail. */
+export class RenderSurfaceError<
+  Code extends SurfaceFailureCode = SurfaceFailureCode,
+> extends Error {
+  readonly code: Code;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderSurfaceFailureDetail;
+
+  constructor(code: Code, detail: RenderSurfaceFailureDetail) {
+    const policy = SURFACE_FAILURE_POLICY[code];
+    if (policy === undefined) {
+      throw new Error(`unknown render surface failure code: ${code}`);
+    }
+    super(`[RenderSurfaceError ${code}] expected: ${policy.expected}; hint: ${policy.hint}`);
+    this.name = 'RenderSurfaceError';
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+}
+
+export type { RenderSurfaceFailureDetail, SurfaceFailureCode, SurfaceFailureKind };
+
+export type RenderSurfaceExpectedError = {
+  readonly [Code in SurfaceFailureCode]: RenderSurfaceError<Code>;
+}[SurfaceFailureCode];
+
+/** Construct the closed surface error from its failure-stage discriminant. */
+export function createRenderSurfaceError(
+  kind: SurfaceFailureKind,
+  detail: RenderSurfaceFailureDetail,
+): RenderSurfaceExpectedError {
+  return new RenderSurfaceError(`surface-${kind}-failed` as SurfaceFailureCode, detail);
+}
+
+export interface TemporalFrameSubmitDetail {
+  readonly reason: 'queue-submit-failed';
+}
+
+export class TemporalFrameSubmitError extends Error {
+  readonly code = 'temporal-frame-submit-rejected' as const;
+  readonly expected = 'the staged frame is accepted by queue.submit before temporal facts advance';
+  readonly hint = 'inspect the queue submission and retry the frame after the device is available';
+  readonly detail: TemporalFrameSubmitDetail;
+
+  constructor(reason: 'queue-submit-failed') {
+    super(`temporal-frame-submit-rejected: ${reason}`);
+    this.name = 'TemporalFrameSubmitError';
+    this.detail = { reason };
+  }
+}
+
 // ── ShadowInvalidConfigError ──────────────────────────────────────────────
 
 /**
@@ -563,6 +649,36 @@ export class MaterialSkinAttrMissingError extends Error {
   }
 }
 
+export interface TransmissionCapabilityMissingDetail {
+  readonly material: string;
+  readonly capability: 'transmission';
+  readonly stage: 'prepare' | 'record';
+  readonly lane: 'standard-forward';
+  readonly format: string;
+  readonly missing: readonly TransmissionCapabilityFact[];
+}
+
+export class TransmissionCapabilityMissingError extends Error {
+  readonly code = 'transmission-capability-missing' as const;
+  readonly expected = 'the renderer exposes the transmission capability for this material';
+  readonly hint = 'disable transmission or provide the renderer capability before drawing';
+  readonly detail: TransmissionCapabilityMissingDetail;
+
+  constructor(
+    material: string,
+    stage: 'prepare' | 'record',
+    evidence: {
+      readonly lane: 'standard-forward';
+      readonly format: string;
+      readonly missing: readonly TransmissionCapabilityFact[];
+    },
+  ) {
+    super(`transmission capability is missing for material '${material}'`);
+    this.name = 'TransmissionCapabilityMissingError';
+    this.detail = { material, capability: 'transmission', stage, ...evidence };
+  }
+}
+
 // -- RenderFeature errors ---------------------------------------------------
 
 export type RenderFeatureErrorCode =
@@ -931,6 +1047,63 @@ export class ObservationUnavailableError extends Error {
   }
 }
 
+export type SceneDataUnavailableReason =
+  | 'capability-missing'
+  | 'producer-missing'
+  | 'coverage-incomplete'
+  | 'renderer-recovering';
+export interface SceneDataUnavailableDetail {
+  readonly featureIdentity: string;
+  readonly schema: SceneDataSchemaId;
+  readonly lane: SceneDataLane;
+  readonly reason: SceneDataUnavailableReason;
+  readonly missingContributorIds: readonly string[];
+  readonly omittedMissingContributorCount: number;
+  readonly recovery: 'enable-capability' | 'next-frame' | 'renderer-recover';
+}
+export class SceneDataUnavailableError extends Error {
+  readonly code = 'scene-data-unavailable' as const;
+  readonly expected = 'the requested semantic scene data is available for the active plan';
+  readonly hint: string;
+  readonly detail: SceneDataUnavailableDetail;
+  constructor(detail: SceneDataUnavailableDetail) {
+    const hint =
+      detail.recovery === 'enable-capability'
+        ? 'enable rgba16floatRenderable and retry the current frame'
+        : detail.recovery === 'renderer-recover'
+          ? 'wait for renderer recovery, then retry the frame'
+          : 'restore the producer coverage and retry on the next frame';
+    super(`scene data '${detail.schema}' unavailable for '${detail.featureIdentity}'`);
+    this.name = 'SceneDataUnavailableError';
+    this.hint = hint;
+    this.detail = Object.freeze({
+      ...detail,
+      missingContributorIds: Object.freeze([...detail.missingContributorIds].slice(0, 32)),
+      omittedMissingContributorCount: Math.max(
+        detail.omittedMissingContributorCount,
+        Math.max(0, detail.missingContributorIds.length - 32),
+      ),
+    });
+  }
+}
+
+export class TaaUnavailableError extends Error {
+  readonly code = 'taa-unavailable' as const;
+  readonly expected =
+    'Standard TAA has a renderable rgba16float target and a complete resolve path';
+  readonly hint =
+    'enable rgba16float rendering or select none/fxaa explicitly; do not treat TAA as no-AA';
+  readonly detail: {
+    readonly reason: 'capability' | 'topology' | 'history';
+    readonly observed?: string;
+  };
+  constructor(reason: 'capability' | 'topology' | 'history', observed?: string) {
+    super(`taa-unavailable: ${reason}`);
+    this.name = 'TaaUnavailableError';
+    this.detail = observed === undefined ? { reason } : { reason, observed };
+  }
+}
+
 export interface FrameReceiptStaleDetail {
   readonly frameId: number;
   readonly receiptGeneration: number;
@@ -970,6 +1143,126 @@ export class RendererContractFailureError extends Error {
   }
 }
 
+export interface EnvironmentSourceConflictDetail {
+  readonly owners: readonly {
+    readonly kind: 'image' | 'atmosphere';
+    readonly entityKey: number;
+    readonly sourceKey: string;
+  }[];
+}
+
+export class EnvironmentSourceConflictError extends Error {
+  readonly code = 'environment-source-conflict' as const;
+  readonly expected = 'exactly one environment source owns the frame';
+  readonly hint = 'remove all but one image or atmosphere environment owner';
+  readonly detail: EnvironmentSourceConflictDetail;
+
+  constructor(owners: readonly EnvironmentSourceConflictDetail['owners'][number][]) {
+    super('environment source owners conflict');
+    this.name = 'EnvironmentSourceConflictError';
+    this.detail = { owners: owners.map((owner) => Object.freeze({ ...owner })) };
+  }
+}
+
+export interface FogCardinalityDetail {
+  readonly count: number;
+}
+
+export class FogCardinalityError extends Error {
+  readonly code = 'fog-cardinality' as const;
+  readonly expected = 'zero or one Fog owner contributes to a frame';
+  readonly hint = 'remove extra Fog owners so the resource owner has at most one';
+  readonly detail: FogCardinalityDetail;
+
+  constructor(count: number) {
+    super(`Fog owner cardinality is ${count}`);
+    this.name = 'FogCardinalityError';
+    this.detail = { count };
+  }
+}
+
+export interface TaaCapsInsufficientDetail {
+  readonly required: readonly string[];
+  readonly available: readonly string[];
+}
+
+export class TaaCapsInsufficientError extends Error {
+  readonly code = 'taa-caps-insufficient' as const;
+  readonly expected = 'the backend exposes the capabilities required by TAA';
+  readonly hint = 'select a backend with the required TAA capabilities or disable TAA on Camera';
+  readonly detail: TaaCapsInsufficientDetail;
+
+  constructor(required: readonly string[], available: readonly string[]) {
+    super('TAA capabilities are insufficient');
+    this.name = 'TaaCapsInsufficientError';
+    this.detail = { required: [...required], available: [...available] };
+  }
+}
+
+export interface EnvironmentGenerationFailedDetail {
+  readonly sourceKey: string;
+  readonly stage: 'prepare' | 'build' | 'execute' | 'finish' | 'submit';
+}
+
+export class EnvironmentGenerationFailedError extends Error {
+  readonly code = 'environment-generation-failed' as const;
+  readonly expected = 'the selected environment generation completes its owner stage';
+  readonly hint = 'inspect the stage and sourceKey, then retry after correcting the environment';
+  readonly detail: EnvironmentGenerationFailedDetail;
+
+  constructor(sourceKey: string, stage: EnvironmentGenerationFailedDetail['stage']) {
+    super(`environment generation failed during ${stage}`);
+    this.name = 'EnvironmentGenerationFailedError';
+    this.detail = { sourceKey, stage };
+  }
+}
+
+export interface AtmosphereInvalidParameterDetail {
+  readonly field: string;
+  readonly value: number;
+}
+
+export interface AtmosphereParameterRange {
+  readonly min: number;
+  readonly max: number;
+}
+
+export class AtmosphereInvalidParameterError extends Error {
+  readonly code = 'atmosphere-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AtmosphereInvalidParameterDetail;
+
+  constructor(field: string, value: number, range: AtmosphereParameterRange) {
+    super(`Atmosphere.${field} is invalid`);
+    this.name = 'AtmosphereInvalidParameterError';
+    this.detail = { field, value };
+    const rangeText = Number.isFinite(range.max)
+      ? `[${range.min}, ${range.max}]`
+      : `>= ${range.min}`;
+    this.expected = `Atmosphere.${field} must be finite and ${rangeText}`;
+    this.hint = `set Atmosphere.${field} to a finite value ${rangeText}`;
+  }
+}
+
+export interface OwnerStageFailedDetail {
+  readonly owner: 'environment' | 'temporal' | 'fog' | 'renderer';
+  readonly stage: 'extract' | 'prepare' | 'record' | 'finish' | 'submit';
+}
+
+export class OwnerStageFailedError extends Error {
+  readonly code = 'owner-stage-failed' as const;
+  readonly expected = 'the owner completes its current frame stage';
+  readonly hint = 'inspect the owner and stage, keep the last-known-good frame, and retry';
+  readonly detail: OwnerStageFailedDetail;
+
+  constructor(owner: OwnerStageFailedDetail['owner'], stage: OwnerStageFailedDetail['stage']) {
+    super(`${owner} owner failed during ${stage}`);
+    this.name = 'OwnerStageFailedError';
+    this.detail = { owner, stage };
+  }
+}
+
 export interface RendererOperationCause {
   readonly code: string;
   readonly expected: string;
@@ -1238,6 +1531,105 @@ export class PointsLinesPrepareFailedError extends Error {
   }
 }
 
+export interface VolumeOwnerConflictDetail {
+  readonly ownerCount: number;
+}
+
+export class VolumeOwnerConflictError extends Error {
+  readonly code = 'volume-owner-conflict' as const;
+  readonly expected = 'exactly one global VolumetricFog owner is authored';
+  readonly hint = 'remove additional VolumetricFog owners and retry extraction';
+  readonly detail: VolumeOwnerConflictDetail;
+
+  constructor(ownerCount: number) {
+    super(`volume-owner-conflict: received ${ownerCount} owners`);
+    this.name = 'VolumeOwnerConflictError';
+    this.detail = { ownerCount };
+  }
+}
+
+export interface VolumeDensityShapeMismatchDetail {
+  readonly guid: string;
+  readonly viewDimension: string;
+}
+
+export class VolumeDensityShapeMismatchError extends Error {
+  readonly code = 'volume-density-shape-mismatch' as const;
+  readonly expected = 'density is a linear 3D TextureAsset';
+  readonly hint = 'bind a verified linear texture with viewDimension 3d';
+  readonly detail: VolumeDensityShapeMismatchDetail;
+
+  constructor(guid: string, viewDimension: string) {
+    super(`volume-density-shape-mismatch: ${viewDimension} density is not 3d`);
+    this.name = 'VolumeDensityShapeMismatchError';
+    this.detail = { guid, viewDimension };
+  }
+}
+
+export interface VolumeInvalidBoundsDetail {
+  readonly min: readonly [number, number, number];
+  readonly max: readonly [number, number, number];
+}
+
+export class VolumeInvalidBoundsError extends Error {
+  readonly code = 'volume-invalid-bounds' as const;
+  readonly expected = 'bounds are finite and max is greater than min on every axis';
+  readonly hint = 'set finite non-degenerate volume bounds';
+  readonly detail: VolumeInvalidBoundsDetail;
+
+  constructor(bounds: VolumeInvalidBoundsDetail) {
+    super('volume-invalid-bounds: bounds must be finite and non-degenerate');
+    this.name = 'VolumeInvalidBoundsError';
+    this.detail = bounds;
+  }
+}
+
+export interface VolumeInvalidParametersDetail {
+  readonly field: string;
+  readonly value: unknown;
+}
+
+export class VolumeInvalidParametersError extends Error {
+  readonly code = 'volume-invalid-parameters' as const;
+  readonly expected = 'volume parameters remain finite and inside their closed ranges';
+  readonly hint = 'repair extinction, albedo, emission, anisotropy, or maxDistance';
+  readonly detail: VolumeInvalidParametersDetail;
+
+  constructor(input: { readonly maxDistance?: number; readonly anisotropy?: number }) {
+    const field =
+      input.maxDistance !== undefined && input.maxDistance <= 0 ? 'maxDistance' : 'parameters';
+    const value = field === 'maxDistance' ? input.maxDistance : input.anisotropy;
+    super(`volume-invalid-parameters: ${field} is outside the authored range`);
+    this.name = 'VolumeInvalidParametersError';
+    this.detail = { field, value };
+  }
+}
+
+export type VolumeError =
+  | VolumeOwnerConflictError
+  | VolumeDensityShapeMismatchError
+  | VolumeInvalidBoundsError
+  | VolumeInvalidParametersError;
+
+export interface ProjectorBindingDetail {
+  readonly guid: string;
+  readonly status: 'pending' | 'invalid' | 'bind-failed';
+}
+
+export class ProjectorBindingError extends Error {
+  readonly code = 'projector-binding-failed' as const;
+  readonly expected = 'authored projector is accepted and bound for both surface and volume';
+  readonly hint =
+    'inspect the projector Meta/Pack receipt, repair the source, and retry with the same GUID';
+  readonly detail: ProjectorBindingDetail;
+
+  constructor(guid: string, status: ProjectorBindingDetail['status']) {
+    super(`projector binding failed for ${guid}: ${status}`);
+    this.name = 'ProjectorBindingError';
+    this.detail = { guid, status };
+  }
+}
+
 // -- RenderErrorCode / RenderError closed unions --------------------------------
 
 /**
@@ -1256,6 +1648,8 @@ export type RenderError =
   | FrameReceiptStaleError
   | RendererContractFailureError
   | ObservationUnavailableError
+  | SceneDataUnavailableError
+  | TaaUnavailableError
   | ShadowInvalidConfigError
   | EquirectProjectionFailedError
   | HdrpLightBudgetExceededError
@@ -1269,6 +1663,7 @@ export type RenderError =
   | SkinPaletteOverflowError
   | SkinMaterialMismatchError
   | MaterialSkinAttrMissingError
+  | TransmissionCapabilityMissingError
   | RenderFeatureRegistrationConflictError
   | RenderFeatureStageFailedError
   | RenderFeatureCapabilityMissingError
@@ -1276,9 +1671,17 @@ export type RenderError =
   | RenderFeaturePreparationFailedError
   | RenderFeaturePreparedStateMismatchError
   | RenderFeatureDrawRecordingFailedError
+  | EnvironmentSourceConflictError
+  | FogCardinalityError
+  | TaaCapsInsufficientError
+  | EnvironmentGenerationFailedError
+  | AtmosphereInvalidParameterError
+  | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError
   | PointsLinesStyleUnsupportedError
   | PointsLinesMaterialUnsupportedError
   | PointsLinesBudgetExceededError
-  | PointsLinesPrepareFailedError;
+  | PointsLinesPrepareFailedError
+  | ProjectorBindingError
+  | VolumeError;

package/src/extract/camera.ts

@@ -0,0 +1,78 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { Transform } from '@forgeax/engine-scene';
+import {
+  antialiasFromF32,
+  bloomEnabledFromF32,
+  Camera,
+  cameraProjectionFromF32,
+  tonemapFromF32,
+} from '../components/camera';
+import { MotionBlur } from '../components/motion-blur';
+import type { CameraSnapshot } from '../render-contract';
+import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
+
+function readWorldMatrix(world: World, entity: EntityHandle): Float32Array | undefined {
+  const view = readRenderArrayView(world, entity, Transform, 'world');
+  return view === undefined ? undefined : new Float32Array(view);
+}
+
+/** Extract the selected camera once at the frame boundary. */
+export function extractCameraSnapshots(world: World): CameraSnapshot[] {
+  const cameras: CameraSnapshot[] = [];
+  const cameraEntities: number[] = [];
+  const cameraQuery = world
+    .query({ read: [Camera], optional: [MotionBlur], with: [Transform] })
+    .unwrap();
+  for (const row of cameraQuery) {
+    const cam = row.get(Camera);
+    const motionBlur = row.get(MotionBlur);
+    const entity = row.entity as EntityHandle;
+    const worldMat = readWorldMatrix(world, entity);
+    if (worldMat === undefined) continue;
+    cameras.push({
+      entityKey: entity as number,
+      historyVersion: cam.historyVersion,
+      position: mat4.getTranslation(vec3.create(), worldMat),
+      world: worldMat,
+      fov: cam.fov,
+      aspect: cam.aspect,
+      near: cam.near,
+      far: cam.far,
+      projection: cameraProjectionFromF32(cam.projection),
+      orthoLeft: cam.left,
+      orthoRight: cam.right,
+      orthoBottom: cam.bottom,
+      orthoTop: cam.top,
+      tonemap: tonemapFromF32(cam.tonemap),
+      exposure: cam.exposure,
+      whitePoint: cam.whitePoint,
+      antialias: antialiasFromF32(cam.antialias),
+      bloom: bloomEnabledFromF32(cam.bloom),
+      bloomThreshold: cam.bloomThreshold,
+      bloomIntensity: cam.bloomIntensity,
+      bloomBlurRadius: cam.bloomBlurRadius,
+      clearColor: [
+        cam.clearColor[0] ?? 0,
+        cam.clearColor[1] ?? 0,
+        cam.clearColor[2] ?? 0,
+        cam.clearColor[3] ?? 1,
+      ],
+      ...(motionBlur === undefined
+        ? {}
+        : {
+            motionBlur: {
+              shutterAngle: motionBlur.shutterAngle,
+              maxRadiusPixels: motionBlur.maxRadiusPixels,
+              sampleCount: motionBlur.sampleCount,
+            },
+          }),
+    });
+    cameraEntities.push(entity as number);
+  }
+  const selected = selectActiveCameraIndex(cameraEntities, getActiveCamera(world)?.entity);
+  if (selected < 0) return cameras;
+  const camera = cameras[selected];
+  return camera === undefined ? cameras : [camera];
+}