@forgeax/engine-render 0.1.6 → 0.1.19

package/src/environment/signature.ts

@@ -0,0 +1,55 @@
+import type { EnvironmentCandidate, FogCandidate } from '../extract/environment';
+
+export interface EnvironmentSignatureInput {
+  readonly environments: readonly EnvironmentCandidate[];
+  readonly fogs: readonly FogCandidate[];
+  readonly suns: readonly {
+    readonly entityKey: number;
+    readonly direction: readonly [number, number, number];
+    readonly color: readonly [number, number, number];
+    readonly intensity: number;
+  }[];
+}
+
+export interface EnvironmentFactSignatures {
+  readonly environmentSignature: string;
+  readonly fogSignature: string;
+  readonly signature: string;
+}
+
+function sorted<T extends { readonly entityKey: number }>(items: readonly T[]): readonly T[] {
+  return [...items].sort((left, right) => left.entityKey - right.entityKey);
+}
+
+/** Derive a deterministic source signature without retaining GPU objects. */
+export function environmentSignature(input: EnvironmentSignatureInput): string {
+  return JSON.stringify({
+    environments: sorted(input.environments),
+    fogs: sorted(input.fogs),
+    suns: sorted(input.suns),
+  });
+}
+
+/** Signature for Environment and Sun facts, excluding the independent Fog channel. */
+export function environmentOnlySignature(input: EnvironmentSignatureInput): string {
+  return JSON.stringify({
+    environments: sorted(input.environments),
+    suns: sorted(input.suns),
+  });
+}
+
+/** Signature for the independent Fog channel. */
+export function fogOnlySignature(input: Pick<EnvironmentSignatureInput, 'fogs'>): string {
+  return JSON.stringify({ fogs: sorted(input.fogs) });
+}
+
+/** Build all frame signatures from one immutable source fact set. */
+export function environmentFactSignatures(
+  input: EnvironmentSignatureInput,
+): EnvironmentFactSignatures {
+  return {
+    environmentSignature: environmentOnlySignature(input),
+    fogSignature: fogOnlySignature(input),
+    signature: environmentSignature(input),
+  };
+}

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,68 @@ 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);
+}
+
 // ── ShadowInvalidConfigError ──────────────────────────────────────────────
 
 /**
@@ -563,6 +632,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 +1030,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 +1126,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;
@@ -1101,6 +1377,143 @@ export type RendererExpectedOperationError = {
   readonly [Code in RendererOperationErrorCode]: RendererOperationError<Code>;
 }[RendererOperationErrorCode];
 
+// -- Points/Lines admission errors -------------------------------------------
+
+export interface PointsLinesInvalidStyleDetail {
+  readonly entity: number;
+  readonly component: 'Points' | 'Lines' | 'Points/Lines';
+  readonly field: string;
+  readonly value: number | string | undefined;
+  readonly expected: string;
+}
+
+export class PointsLinesInvalidStyleError extends Error {
+  readonly code = 'points-lines-invalid-style' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesInvalidStyleDetail;
+
+  constructor(detail: PointsLinesInvalidStyleDetail) {
+    super(`invalid ${detail.component} style at ${detail.field}`);
+    this.name = 'PointsLinesInvalidStyleError';
+    this.expected = detail.expected;
+    this.hint = `repair entity ${detail.entity} ${detail.component}.${detail.field} and retry admission`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesTopologyMismatchDetail {
+  readonly entity: number;
+  readonly submesh: number;
+  readonly expected: string;
+  readonly actual: string;
+}
+
+export class PointsLinesTopologyMismatchError extends Error {
+  readonly code = 'points-lines-topology-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesTopologyMismatchDetail;
+
+  constructor(detail: PointsLinesTopologyMismatchDetail) {
+    super(`Points/Lines topology mismatch at submesh ${detail.submesh}`);
+    this.name = 'PointsLinesTopologyMismatchError';
+    this.expected = `submesh ${detail.submesh} topology is ${detail.expected}`;
+    this.hint = `rebuild entity ${detail.entity} with ${detail.expected} geometry before retrying Points/Lines admission`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesStyleUnsupportedDetail {
+  readonly lane: string;
+  readonly field: string;
+  readonly member: string;
+  readonly supported: readonly string[];
+}
+
+export class PointsLinesStyleUnsupportedError extends Error {
+  readonly code = 'points-lines-style-unsupported' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesStyleUnsupportedDetail;
+
+  constructor(detail: PointsLinesStyleUnsupportedDetail) {
+    super(`unsupported Points/Lines ${detail.field} member ${detail.member}`);
+    this.name = 'PointsLinesStyleUnsupportedError';
+    this.expected = `${detail.field} is one of ${detail.supported.join(', ')}`;
+    this.hint = `use a supported Points/Lines ${detail.field} member or wait for a later milestone`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesMaterialUnsupportedDetail {
+  readonly entity: number;
+  readonly material: string;
+  readonly pass: string;
+  readonly module: string;
+  readonly reason: string;
+}
+
+export class PointsLinesMaterialUnsupportedError extends Error {
+  readonly code = 'points-lines-material-unsupported' as const;
+  readonly expected = 'one engine-owned unlit forward MaterialAsset pass';
+  readonly hint: string;
+  readonly detail: PointsLinesMaterialUnsupportedDetail;
+
+  constructor(detail: PointsLinesMaterialUnsupportedDetail) {
+    super(`Points/Lines material is unsupported on entity ${detail.entity}`);
+    this.name = 'PointsLinesMaterialUnsupportedError';
+    this.hint = `use Materials.unlit without a shadow-caster pass for entity ${detail.entity}`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesBudgetExceededDetail {
+  readonly lane: string;
+  readonly requested: number;
+  readonly limit: number;
+  readonly unit: 'points' | 'segments' | 'vertices' | 'indices' | 'bytes' | 'draws';
+}
+
+export class PointsLinesBudgetExceededError extends Error {
+  readonly code = 'points-lines-budget-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesBudgetExceededDetail;
+
+  constructor(detail: PointsLinesBudgetExceededDetail) {
+    super(`Points/Lines ${detail.unit} budget exceeded`);
+    this.name = 'PointsLinesBudgetExceededError';
+    this.expected = `${detail.unit} <= ${detail.limit}`;
+    this.hint = `reduce Points/Lines ${detail.unit} or split the entity into bounded equivalent batches`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesPrepareFailedDetail {
+  readonly owner: string;
+  readonly generation: number;
+  readonly stage: 'prepare';
+  readonly cause: string;
+  readonly lastKnownGood: boolean;
+}
+
+export class PointsLinesPrepareFailedError extends Error {
+  readonly code = 'points-lines-prepare-failed' as const;
+  readonly expected = 'the complete Points/Lines candidate validates before publication';
+  readonly hint: string;
+  readonly detail: PointsLinesPrepareFailedDetail;
+
+  constructor(detail: PointsLinesPrepareFailedDetail) {
+    super(`Points/Lines prepare failed at generation ${detail.generation}`);
+    this.name = 'PointsLinesPrepareFailedError';
+    this.hint = detail.lastKnownGood
+      ? 'retain the last known good candidate, repair the producer, and retry prepare'
+      : 'repair the producer and retry prepare; the failed first candidate produces zero draw';
+    this.detail = detail;
+  }
+}
+
 // -- RenderErrorCode / RenderError closed unions --------------------------------
 
 /**
@@ -1119,6 +1532,8 @@ export type RenderError =
   | FrameReceiptStaleError
   | RendererContractFailureError
   | ObservationUnavailableError
+  | SceneDataUnavailableError
+  | TaaUnavailableError
   | ShadowInvalidConfigError
   | EquirectProjectionFailedError
   | HdrpLightBudgetExceededError
@@ -1132,10 +1547,23 @@ export type RenderError =
   | SkinPaletteOverflowError
   | SkinMaterialMismatchError
   | MaterialSkinAttrMissingError
+  | TransmissionCapabilityMissingError
   | RenderFeatureRegistrationConflictError
   | RenderFeatureStageFailedError
   | RenderFeatureCapabilityMissingError
   | RenderFeaturePassOrderConflictError
   | RenderFeaturePreparationFailedError
   | RenderFeaturePreparedStateMismatchError
-  | RenderFeatureDrawRecordingFailedError;
+  | RenderFeatureDrawRecordingFailedError
+  | EnvironmentSourceConflictError
+  | FogCardinalityError
+  | TaaCapsInsufficientError
+  | EnvironmentGenerationFailedError
+  | AtmosphereInvalidParameterError
+  | OwnerStageFailedError
+  | PointsLinesInvalidStyleError
+  | PointsLinesTopologyMismatchError
+  | PointsLinesStyleUnsupportedError
+  | PointsLinesMaterialUnsupportedError
+  | PointsLinesBudgetExceededError
+  | PointsLinesPrepareFailedError;

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