@forgeax/engine-render 0.1.27 → 0.1.29

package/src/components/camera.ts

@@ -43,6 +43,179 @@ export const CAMERA_PROJECTION_PERSPECTIVE = 0;
 /** Numeric encoding of orthographic projection (schema value for `projection`). */
 export const CAMERA_PROJECTION_ORTHOGRAPHIC = 1;
 
+/** Closed public exposure authoring contract shared by all camera routes. */
+export type CameraExposure =
+  | { readonly kind: 'manual'; readonly multiplier: number }
+  | {
+      readonly kind: 'auto';
+      readonly fallback: number;
+      readonly compensationEv: number;
+      readonly rangeEv: readonly [min: number, max: number];
+      readonly rates: readonly [up: number, down: number];
+    };
+
+/** Numeric encoding of manual exposure in the Camera SoA column. */
+export const CAMERA_EXPOSURE_MODE_MANUAL = 0;
+/** Numeric encoding of GPU-adapted exposure in the Camera SoA column. */
+export const CAMERA_EXPOSURE_MODE_AUTO = 1;
+
+/** Product-supported white-balance temperature range in Kelvin. */
+export const CAMERA_TEMPERATURE_MIN = 1000;
+export const CAMERA_TEMPERATURE_MAX = 40000;
+/** Product-supported normalized tint range. */
+export const CAMERA_TINT_MIN = -1;
+export const CAMERA_TINT_MAX = 1;
+
+/** Closed validation failures for the Camera authoring/column boundary. */
+export type CameraErrorCode =
+  | 'camera-exposure-invalid'
+  | 'camera-color-grading-invalid'
+  | 'camera-exposure-mode-invalid'
+  | 'camera-tonemap-invalid'
+  | 'camera-antialias-invalid'
+  | 'camera-bloom-invalid';
+
+export interface CameraErrorDetail {
+  readonly field: string;
+  readonly actual: number | string;
+  readonly expected: string;
+}
+
+/** Structured Camera error; callers can branch on the closed `code` union. */
+export class CameraError<Code extends CameraErrorCode = CameraErrorCode> extends Error {
+  readonly code: Code;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: CameraErrorDetail;
+
+  constructor(code: Code, field: string, actual: number | string, expected: string, hint: string) {
+    super(`${code}: ${field}=${String(actual)}; expected ${expected}`);
+    this.name = 'CameraError';
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = Object.freeze({ field, actual, expected });
+  }
+}
+
+function actualValue(value: unknown): number | string {
+  if (typeof value === 'number' || typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function cameraError<Code extends CameraErrorCode>(
+  code: Code,
+  field: string,
+  actual: unknown,
+  expected: string,
+  hint: string,
+): CameraError<Code> {
+  return new CameraError(code, field, actualValue(actual), expected, hint);
+}
+
+function finitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+/** Validate the closed exposure union before it is projected into columns. */
+export function validateCameraExposure(exposure: CameraExposure): CameraExposure {
+  if (typeof exposure !== 'object' || exposure === null) {
+    throw cameraError(
+      'camera-exposure-invalid',
+      'value',
+      exposure,
+      'an object with kind manual or auto',
+      'choose one member of the CameraExposure union',
+    );
+  }
+  if (exposure.kind === 'manual') {
+    if (!finitePositive(exposure.multiplier)) {
+      throw cameraError(
+        'camera-exposure-invalid',
+        'multiplier',
+        exposure.multiplier,
+        'a finite number greater than zero',
+        'set Camera.exposure to a positive finite manual multiplier',
+      );
+    }
+    return exposure;
+  }
+  if (exposure.kind === 'auto') {
+    const [min, max] = exposure.rangeEv;
+    const [up, down] = exposure.rates;
+    if (
+      !finitePositive(exposure.fallback) ||
+      !Number.isFinite(exposure.compensationEv) ||
+      !Number.isFinite(min) ||
+      !Number.isFinite(max) ||
+      min > max ||
+      !Number.isFinite(up) ||
+      !Number.isFinite(down) ||
+      up < 0 ||
+      down < 0
+    ) {
+      throw cameraError(
+        'camera-exposure-invalid',
+        'auto',
+        JSON.stringify(exposure),
+        'finite fallback/compensation, an ordered range, and non-negative rates',
+        'inspect fallback, compensationEv, rangeEv, and rates before rebuilding the camera',
+      );
+    }
+    return exposure;
+  }
+  throw cameraError(
+    'camera-exposure-invalid',
+    'kind',
+    (exposure as { readonly kind?: unknown }).kind,
+    "'manual' or 'auto'",
+    'choose one member of the CameraExposure union',
+  );
+}
+
+/** Validate the Camera-owned white-balance and LUT authoring fields. */
+export function validateCameraColorGrading(
+  temperature: number,
+  tint: number,
+  colorLutStrength: number,
+): void {
+  if (
+    !Number.isFinite(temperature) ||
+    temperature < CAMERA_TEMPERATURE_MIN ||
+    temperature > CAMERA_TEMPERATURE_MAX
+  ) {
+    throw cameraError(
+      'camera-color-grading-invalid',
+      'temperature',
+      temperature,
+      `a finite value in [${CAMERA_TEMPERATURE_MIN}, ${CAMERA_TEMPERATURE_MAX}]`,
+      'set Camera.temperature to a supported Kelvin value',
+    );
+  }
+  if (!Number.isFinite(tint) || tint < CAMERA_TINT_MIN || tint > CAMERA_TINT_MAX) {
+    throw cameraError(
+      'camera-color-grading-invalid',
+      'tint',
+      tint,
+      `a finite value in [${CAMERA_TINT_MIN}, ${CAMERA_TINT_MAX}]`,
+      'set Camera.tint to a normalized value between -1 and 1',
+    );
+  }
+  if (!Number.isFinite(colorLutStrength) || colorLutStrength < 0 || colorLutStrength > 1) {
+    throw cameraError(
+      'camera-color-grading-invalid',
+      'colorLutStrength',
+      colorLutStrength,
+      'a finite value in [0, 1]',
+      'set Camera.colorLutStrength to zero to disable the LUT or a blend in [0, 1]',
+    );
+  }
+}
+
 /**
  * Map a `camera.projection` numeric value to the closed `CameraProjection`
  * string-literal union. Values other than 0 / 1 fall back to `'perspective'`
@@ -152,7 +325,13 @@ export function tonemapToU32(mode: Tonemap): number {
     case 'none':
       return TONEMAP_NONE;
   }
-  throw new RangeError(`Invalid tonemap mode: ${String(mode)}.`);
+  throw cameraError(
+    'camera-tonemap-invalid',
+    'tonemap',
+    mode,
+    'one of the closed Tonemap values',
+    'select a supported Camera tonemap mode',
+  );
 }
 
 /**
@@ -192,8 +371,12 @@ export function antialiasFromF32(value: number): Antialias {
   if (value === ANTIALIAS_FXAA) return 'fxaa';
   if (value === ANTIALIAS_MSAA) return 'msaa';
   if (value === ANTIALIAS_TAA) return 'taa';
-  throw new RangeError(
-    `Invalid antialias value: ${value}. Expected ${ANTIALIAS_NONE} (none), ${ANTIALIAS_FXAA} (fxaa), ${ANTIALIAS_MSAA} (msaa), or ${ANTIALIAS_TAA} (taa).`,
+  throw cameraError(
+    'camera-antialias-invalid',
+    'antialias',
+    value,
+    `${ANTIALIAS_NONE}, ${ANTIALIAS_FXAA}, ${ANTIALIAS_MSAA}, or ${ANTIALIAS_TAA}`,
+    'select a supported Camera antialias mode',
   );
 }
 
@@ -205,8 +388,8 @@ export function antialiasFromF32(value: number): Antialias {
  *   `'off'` - default; no bloom post-processing (zero-overhead opt-out path)
  *   `'on'`  - bloom bright-pass + separable blur + composite pipeline
  *
- * Bloom is a discrete enum (0/1) — illegal values fail-fast with RangeError
- * (charter P3), matching antialiasFromF32 precedent.
+ * Bloom is a discrete enum (0/1) — illegal values fail-fast with the closed
+ * CameraError contract (charter P3), matching antialiasFromF32 precedent.
  */
 export type BloomEnabled = 'off' | 'on';
 
@@ -222,8 +405,12 @@ export const BLOOM_ENABLED = 1;
 export function bloomEnabledFromF32(value: number): BloomEnabled {
   if (value === BLOOM_DISABLED) return 'off';
   if (value === BLOOM_ENABLED) return 'on';
-  throw new RangeError(
-    `Invalid bloom value: ${value}. Expected ${BLOOM_DISABLED} (off) or ${BLOOM_ENABLED} (on).`,
+  throw cameraError(
+    'camera-bloom-invalid',
+    'bloom',
+    value,
+    `${BLOOM_DISABLED} or ${BLOOM_ENABLED}`,
+    'select Camera bloom off or on',
   );
 }
 
@@ -313,7 +500,15 @@ export const Camera = defineComponent('Camera', {
   top: { type: 'f32', default: 1 },
   tonemap: { type: 'f32', default: 0 },
   exposure: { type: 'f32', default: 1.0 },
+  exposureMode: { type: 'f32', default: CAMERA_EXPOSURE_MODE_MANUAL },
+  compensationEv: { type: 'f32', default: 0 },
+  rangeEv: { type: 'array<f32, 2>', default: new Float32Array([-8, 8]) },
+  rates: { type: 'array<f32, 2>', default: new Float32Array([3, 1]) },
   whitePoint: { type: 'f32', default: 4.0 },
+  temperature: { type: 'f32', default: 6504 },
+  tint: { type: 'f32', default: 0 },
+  colorLut: { type: 'shared<TextureAsset>', default: 0 as never },
+  colorLutStrength: { type: 'f32', default: 0 },
   antialias: { type: 'f32', default: 0 },
   historyVersion: { type: 'u32', default: 0 },
   bloom: { type: 'f32', default: 0 },
@@ -356,6 +551,79 @@ export const Camera = defineComponent('Camera', {
 export type CameraData = ShapeOf<SchemaOf<typeof Camera>>;
 type CameraPod = CameraData;
 
+/** Project the Camera SoA columns back into the public closed union. */
+export function cameraExposureFromColumns(
+  input: Pick<CameraData, 'exposureMode' | 'exposure' | 'compensationEv' | 'rangeEv' | 'rates'>,
+): CameraExposure {
+  if (input.exposureMode === CAMERA_EXPOSURE_MODE_MANUAL) {
+    return validateCameraExposure({ kind: 'manual', multiplier: input.exposure });
+  }
+  if (input.exposureMode === CAMERA_EXPOSURE_MODE_AUTO) {
+    return validateCameraExposure({
+      kind: 'auto',
+      fallback: input.exposure,
+      compensationEv: input.compensationEv,
+      rangeEv: [input.rangeEv[0] ?? -8, input.rangeEv[1] ?? 8],
+      rates: [input.rates[0] ?? 3, input.rates[1] ?? 1],
+    });
+  }
+  throw cameraError(
+    'camera-exposure-mode-invalid',
+    'exposureMode',
+    input.exposureMode,
+    `${CAMERA_EXPOSURE_MODE_MANUAL} or ${CAMERA_EXPOSURE_MODE_AUTO}`,
+    'set Camera.exposureMode to the manual or auto encoding',
+  );
+}
+
+function cameraExposureColumns(
+  exposure: CameraExposure,
+): Pick<CameraData, 'exposureMode' | 'exposure' | 'compensationEv' | 'rangeEv' | 'rates'> {
+  const checked = validateCameraExposure(exposure);
+  if (checked.kind === 'manual') {
+    return {
+      exposureMode: CAMERA_EXPOSURE_MODE_MANUAL,
+      exposure: checked.multiplier,
+      compensationEv: 0,
+      rangeEv: new Float32Array([-8, 8]),
+      rates: new Float32Array([3, 1]),
+    };
+  }
+  return {
+    exposureMode: CAMERA_EXPOSURE_MODE_AUTO,
+    exposure: checked.fallback,
+    compensationEv: checked.compensationEv,
+    rangeEv: new Float32Array(checked.rangeEv),
+    rates: new Float32Array(checked.rates),
+  };
+}
+
+interface CameraColorGradingOpts {
+  exposure?: CameraExposure;
+  temperature?: number;
+  tint?: number;
+  colorLut?: CameraPod['colorLut'];
+  colorLutStrength?: number;
+}
+
+function cameraColorGradingColumns(
+  opts: CameraColorGradingOpts,
+): ReturnType<typeof cameraExposureColumns> &
+  Pick<CameraData, 'temperature' | 'tint' | 'colorLut' | 'colorLutStrength'> {
+  const exposure = opts.exposure ?? { kind: 'manual', multiplier: 1 };
+  const temperature = opts.temperature ?? 6504;
+  const tint = opts.tint ?? 0;
+  const colorLutStrength = opts.colorLutStrength ?? 0;
+  validateCameraColorGrading(temperature, tint, colorLutStrength);
+  return {
+    ...cameraExposureColumns(exposure),
+    temperature,
+    tint,
+    colorLut: opts.colorLut ?? (0 as CameraPod['colorLut']),
+    colorLutStrength,
+  };
+}
+
 // ─── Camera factory functions (w13 SSOT refactoring) ─────────────────────
 //
 // Standalone factory functions that return 20-field CameraPod objects
@@ -396,6 +664,11 @@ interface CameraPerspectiveOpts {
    * receive aspect-sync regardless of this flag.
    */
   autoAspect?: boolean;
+  exposure?: CameraExposure;
+  temperature?: number;
+  tint?: number;
+  colorLut?: CameraPod['colorLut'];
+  colorLutStrength?: number;
 }
 
 interface CameraOrthographicOpts {
@@ -405,6 +678,11 @@ interface CameraOrthographicOpts {
   top: number;
   near?: number;
   far?: number;
+  exposure?: CameraExposure;
+  temperature?: number;
+  tint?: number;
+  colorLut?: CameraPod['colorLut'];
+  colorLutStrength?: number;
 }
 
 /**
@@ -474,6 +752,7 @@ export function perspective(opts: CameraPerspectiveOpts): CameraPod {
     far: opts.far ?? 100,
     projection: CAMERA_PROJECTION_PERSPECTIVE,
     ...(opts.autoAspect !== undefined ? { autoAspect: opts.autoAspect } : {}),
+    ...cameraColorGradingColumns(opts),
   };
 }
 
@@ -513,5 +792,6 @@ export function orthographic(opts: CameraOrthographicOpts): CameraPod {
     right: opts.right,
     bottom: opts.bottom,
     top: opts.top,
+    ...cameraColorGradingColumns(opts),
   };
 }

package/src/components/index.ts

@@ -27,6 +27,7 @@ export {
   type SceneInstanceOverrideRecord,
   type SceneInstanceState,
 } from './scene-instance';
+export * from './screen-space-reflection';
 export {
   SKYBOX_MODE_CUBEMAP,
   SkyboxBackground,

package/src/components/instances.ts

@@ -1,23 +1,50 @@
+// @forgeax/engine-render - renderer-owned large instance association.
+//
+// The ECS component deliberately carries only a stable collection identity.
+// Matrix bytes, revision, capacity, dirty ranges, GPU residency and fallback
+// policy belong to InstanceCollectionStore, exposed from the same Renderer.
+// This keeps large payloads out of the ECS managed BufferPool while retaining
+// ordinary query and entity-lifetime semantics.
+//
+// Authoring example:
+//
+//   const transforms = new Float32Array(instanceCount * 16);
+//   for (let index = 0; index < instanceCount; index += 1) {
+//     const offset = index * 16;
+//     transforms[offset] = 1;
+//     transforms[offset + 5] = 1;
+//     transforms[offset + 10] = 1;
+//     transforms[offset + 15] = 1;
+//   }
+//   const collection = renderer.instances.create({
+//     transforms,
+//   }).unwrap();
+//   world.spawn(
+//     { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+//     { component: MeshRenderer, data: {} },
+//     { component: Instances, data: { collectionId: collection.collectionId } },
+//   );
+//
+// Updates stay on the renderer owner and publish one revision:
+//
+//   renderer.instances.update(collection.collectionId, {
+//     start: 12,
+//     transforms: patch,
+//   });
+//
+// Render extraction snapshots the validated packed column-major matrices once
+// per frame. Direct, GPU-driven and fallback lanes consume that same detached
+// projection; callers never split one logical collection into ECS chunks.
+
 import { defineComponent } from '@forgeax/engine-ecs';
+import type { InstanceCollectionData } from '../instances';
 
-/**
- * World-owned local transforms for one explicit instanced renderable.
- * Packed column-major mat4 values compose as entityWorld * instanceLocal.
- * ECS owns copying, mutation and entity lifetime, including large arrays.
- * Renderer extraction derives its own snapshot and GPU residency; neither
- * authoring nor glTF SceneAsset lowering requires a Renderer identity.
- *
- * @example
- * const transforms = new Float32Array(20_000 * 16);
- * for (let i = 0; i < 20_000; i++) {
- *   transforms[i * 16] = transforms[i * 16 + 5] =
- *     transforms[i * 16 + 10] = transforms[i * 16 + 15] = 1;
- * }
- * const entity = world.spawn({ component: Instances, data: { transforms } }).unwrap();
- * world.set(entity, Instances, { transforms }).unwrap();
- */
+/** Per-entity association with a renderer-owned instance collection. */
 export const Instances = defineComponent('Instances', {
-  transforms: { type: 'array<f32>' },
+  collectionId: { type: 'u32', default: 0 },
 });
 
-export type InstancesData = { readonly transforms: Float32Array };
+/** Type-level hint for the `data` object at the Instances spawn site. */
+export type InstancesData = InstanceCollectionData;
+
+export type { InstanceCollectionId } from '../instances';

package/src/components/scene-instance.ts

@@ -37,7 +37,8 @@
 //     `world.get(root, SceneInstance)` path as another component)
 
 import { defineComponent, type EntityHandle } from '@forgeax/engine-ecs';
-import type { LocalEntityId, MountOverride } from '@forgeax/engine-types';
+import type { MountOverride } from '@forgeax/engine-scene';
+import type { LocalEntityId } from '@forgeax/engine-types';
 
 /**
  * Per-component, per-field override record carried in `SceneInstanceState`.

package/src/components/screen-space-reflection.ts

@@ -0,0 +1,21 @@
+// @forgeax/engine-render - ScreenSpaceReflection authoring component.
+//
+// The component is an opt-in camera effect. It carries only the three
+// bounded authoring values; all graph, resource, history, and backend state
+// remains renderer-owned.
+
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/**
+ * Schema-derived ScreenSpaceReflection authoring data.
+ *
+ * The defaults are conservative and are validated against the active camera
+ * view range before a spatial candidate is admitted.
+ */
+export const ScreenSpaceReflection = defineComponent('ScreenSpaceReflection', {
+  maxDistance: { type: 'f32', default: 40 },
+  thickness: { type: 'f32', default: 0.2 },
+  maxRoughness: { type: 'f32', default: 0.6 },
+});
+
+export type ScreenSpaceReflectionData = ShapeOf<SchemaOf<typeof ScreenSpaceReflection>>;

package/src/components/sprite-animation.ts

@@ -31,8 +31,8 @@
 // Why array<f32> (variable) and not array<f32, N> (fixed) for regions?
 // The length `frameCount * 4` is data-dependent: `frameCount` is itself a
 // per-entity column read at runtime, not a schema-time literal. Same
-// shape as M1 `Instances.transforms: 'array<f32>'` whose length depends
-// on the live instance count; D-6 codifies the precedent.
+// shape as the renderer-owned 3D instance collection snapshot whose length
+// depends on the live instance count; the owners remain separate.
 //
 // dt accumulator clock model (requirements section 2.5 q6 + plan-strategy
 // section 2 D-5):
@@ -53,7 +53,7 @@
 //
 // 4-step recipe (charter F1 progressive disclosure — minimum walk-cycle
 // host code; full demo lands in M6 hello-sprite-atlas):
-//   1. Build atlas via `forgeax-engine-remote-asset atlas --input <glob> --name <prefix> --output <dir>`
+//   1. Build atlas via `forgeax asset atlas --input <glob> --name <prefix> --output <dir> --root <project>`
 //      (M5 build-time hook); load the emitted `<name>.atlas.png` plus
 //      `<name>.atlas.meta.json` sidecar.
 //   2. Register the sprite material referencing the atlas

package/src/components/sprite-instances.ts

@@ -41,7 +41,7 @@
 //   composes per instance:
 //     world_position[i] = entity_world * instances_local[i] * vertex_position
 //   `SpriteInstances.transforms[i*16..i*16+15]` is interpreted as a local-
-//   space transform under the entity, exactly like `Instances.transforms`.
+//   space transform under the entity, matching the 3D collection projection.
 //   Set the entity's `Transform` to identity to make `instances_local[i]`
 //   directly world-space.
 //