lecodes-sdk 2.4.7 → 2.4.9

package/src/gl/Camera.ts

@@ -1,20 +1,49 @@
-// The scene camera — a Node (so position / lookAt / transform all work) plus projection reads and
-// screen↔world ray helpers. Created and attached by Scene. Ported from worker/src/components/Camera.ts.
+// A camera — a Node (so position / lookAt / transform all work) plus its lens. The scene camera is created and attached
+// by Scene (`_attach`: its projection, exposure and the screen↔world ray helpers are the screen's); a SECONDARY camera is
+// `new Camera(options)`, a plain node until `renderToTexture` gives it a render view of its scene (RenderTexture.ts,
+// creator-gl renderview.cpp), started once the node is in a scene (Node.ts awaitScene). Ported from
+// worker/src/components/Camera.ts.
 
 import { Vec3 } from "../math/vec"
 import { Aspect } from "../core/Aspect"
-import { Node, type NodeTweenProps } from "./Node"
+import { Node, awaitScene, type NodeTweenProps } from "./Node"
 import { Ray } from "./Ray"
+import { RenderTexture, makeRenderTexture, startRenderView } from "./RenderTexture"
 import { DOM_GL_CAMERA, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
 import type { Animation } from "../animate/tween/Animation"
 
-/** Animatable camera props on top of the node transform. */
+/** Animatable camera props on top of the node transform. `fov` / `near` / `far` are the SCENE camera's: on a secondary
+ *  camera they throw (set them directly — they are live — or from `animate({ onUpdate })`). */
 export type CameraTweenProps = NodeTweenProps & {
   fov?: number | number[],
   near?: number | number[],
   far?: number | number[],
 }
 
+/** `new Camera(options)`: a SECONDARY camera's lens and what its view draws (the scene's own camera is `scene.camera`). */
+export type CameraOptions = {
+  /** Vertical field of view in degrees (default 60). Live: `camera.fov`. */
+  fov?: number
+  /** Near clip distance in metres (default 0.01). Live: `camera.near`. */
+  near?: number
+  /** Far clip distance in metres (default 1000). Live: `camera.far`. */
+  far?: number
+  /** The layers its view draws, a bit mask over `Node.layer` (default 0xff = everything): a renderable is drawn when its
+   *  layers share a bit with these — the player's own body left out of a mirror. Fixed when the view starts. */
+  layers?: number
+  /** Shadows in its view (default `true`): the view renders shadow maps of its own each time it draws. Fixed when the
+   *  view starts. */
+  shadows?: boolean
+}
+
+/** `camera.renderToTexture(options)`: the picture's size. */
+export type RenderToTextureOptions = {
+  /** Texels wide, 1..4096 (default 256). */
+  width?: number
+  /** Texels tall, 1..4096 (default 256). */
+  height?: number
+}
+
 /** @internal `camera.follow(node)`: copies the node's world pose onto the camera every LATE frame
  *  (order 1000 — after every other aspect has moved things). One per camera; lives on the target. */
 export class CameraFollowRig extends Aspect<"__cameraFollow"> {
@@ -31,16 +60,33 @@ export class CameraFollowRig extends Aspect<"__cameraFollow"> {
 /** Projection every host starts a scene with (creator-gl scene.cpp / the lite core agree on these). */
 export const CAMERA_DEFAULTS = { fov: 60, near: 0.01, far: 1000 }
 
+/** A texture side: a whole number, 1 at least (the host refuses more than 4096). */
+const side = (n: number): number => Math.max(1, Math.floor(n))
+
+/**
+ * A camera: a Node (position, `lookAt`, parenting — it looks down its −Z) with a lens, `fov` / `near` / `far`. Two kinds:
+ *  - THE SCENE CAMERA, `scene.camera`: made by the Scene, it draws the screen. Its exposure, `projectionMatrix` and the
+ *    ray helpers (`getRay`, `getViewDirection`) are the screen's, and its projection tweens (`animateTo({ fov })`).
+ *  - A SECONDARY camera, `new Camera({ fov, layers, shadows })`: a plain node until `renderToTexture({ width, height })`
+ *    gives it a second view of its scene, drawn into a texture every frame the scene is on show — a rear-view mirror, a
+ *    monitor, a security camera. Place it like any node (`car.add(mirrorCam)`); its lens is live (`mirrorCam.fov = 50`),
+ *    its view's schedule is `enabled` / `everyNth`. A cube of light for reflections is a `ReflectionProbe`.
+ */
 export class Camera extends Node {
+  /** The scene this camera draws the screen of (Scene `_attach`); -1 = a secondary camera. */
   private _sceneId = -1
 
-  /** Tween `fov` / `near` / `far` (a zoom, a dolly) and the transform — see {@link Node.animateTo}. */
+  /** Tween `fov` / `near` / `far` (a zoom, a dolly — the scene camera's) and the transform — see {@link Node.animateTo}. */
   override animateTo(props: CameraTweenProps & TweenMeta): Animation { return super.animateTo(props) }
   override animateFrom(props: CameraTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
-  /** @internal The projection channels address the SCENE (one camera per scene on the host). */
+  /** @internal The projection channels address the SCENE (one camera per scene on the host): a render view's
+   *  projection has no tween writer, so a secondary camera's throw. */
   override _tweenChannel(prop: string): TweenChannel | null {
     if (prop === "fov" || prop === "near" || prop === "far") {
-      const id = () => (this._sceneId < 0 ? 0 : this._sceneId + 1)   // scene ids start at 0; 0 = unaddressable
+      if (this._sceneId < 0) {
+        throw new Error(`Camera: a secondary camera's "${prop}" is not animatable (the tween core drives the scene camera's projection only) — set camera.${prop} directly, it is live: per frame, or animate({ from, to, onUpdate: (v) => { camera.${prop} = v } })`)
+      }
+      const id = () => this._sceneId + 1   // scene ids start at 0; 0 = unaddressable
       const commit = (v: unknown) => {
         if (prop === "fov") this._fov = v as number
         else if (prop === "near") this._near = v as number
@@ -51,11 +97,12 @@ export class Camera extends Node {
     }
     return super._tweenChannel(prop)
   }
-  /** Live projection matrix (updated by the host when the viewport/fov changes). */
+  /** The scene camera's live projection matrix (updated by the host when the viewport / fov changes). A secondary
+   *  camera's stays zero: its projection is `fov` / `near` / `far` at its texture's aspect. */
   readonly projectionMatrix = new Float32Array(16)
 
-  // Projection the app asked for (host defaults until it does). The host owns the aspect and
-  // re-applies these on every viewport change, so they are set, not maintained.
+  // Projection the app asked for (host defaults until it does). The scene camera's host owns the aspect and re-applies
+  // these on every viewport change, so they are set, not maintained; a secondary camera's are its view's.
   private _fov = CAMERA_DEFAULTS.fov
   private _near = CAMERA_DEFAULTS.near
   private _far = CAMERA_DEFAULTS.far
@@ -69,7 +116,29 @@ export class Camera extends Node {
   private _ev = 0
   private _exposureSet = false
 
-  /** @internal — Scene wires the camera to its native scene id + projection callback. */
+  // A secondary camera's view (renderToTexture): what it draws with, fixed when it starts, and its schedule.
+  private readonly _layers: number
+  private readonly _shadows: boolean
+  private _enabled = true
+  private _everyNth = 1
+  /** @internal The texture `renderToTexture` made (held: it lives as long as the camera does). */
+  _texture: RenderTexture | null = null
+  /** @internal The render view's owned handle (`_view.id` = the engine's view id), null until the view starts: it lives
+   *  exactly as long as this camera holds it. */
+  _view: Handle | null = null
+
+  /** A SECONDARY camera (`scene.camera` is the scene's own): a plain node until `renderToTexture`. `options`: its lens
+   *  (live after, through `fov` / `near` / `far`) and what its view draws (`layers`, `shadows` — fixed). */
+  constructor(options: CameraOptions = {}) {
+    super()
+    if (options.fov !== undefined) this._fov = options.fov
+    if (options.near !== undefined) this._near = options.near
+    if (options.far !== undefined) this._far = options.far
+    this._layers = (options.layers ?? 0xff) & 0xff
+    this._shadows = options.shadows !== false
+  }
+
+  /** @internal — Scene wires the camera to its native scene id + projection callback: the SCENE camera. */
   _attach(sceneId: number): void {
     this._sceneId = sceneId
     _creator.attachCameraToAR(sceneId, this.id, (mat) => {
@@ -79,11 +148,90 @@ export class Camera extends Node {
     if (this._exposureSet) this._applyExposure()
   }
 
+  /** @internal What only the scene camera has (the screen's ray helpers): a clear throw on a secondary camera. */
+  private _sceneOnly(what: string): void {
+    if (this._sceneId < 0) throw new Error(`camera.${what}: the scene camera's (scene.camera) — a secondary camera has no screen to pick through`)
+  }
+  /** @internal What only a secondary camera has (a render view): a clear throw on the scene camera. */
+  private _secondaryOnly(what: string): void {
+    if (this._sceneId >= 0) throw new Error(`camera.${what}: the scene camera draws the screen, every frame its scene is on show — a second view is a new Camera() with renderToTexture`)
+  }
+
+  /**
+   * Draw this camera's view of its scene into a new 2D texture of `width × height` texels (default 256 × 256): the
+   * tone-mapped picture as the screen would show it (LDR) — `screen.material.map = cam.renderToTexture({ ... })`. The
+   * camera holds it (`camera.texture`).
+   *
+   * THE VIEW starts once the camera is in a scene (added to one, or under a node that is — at once if it already is)
+   * and draws every frame that scene is on show, after the frame's update passes (aspects, physics, animation: this
+   * frame's poses) and before the scene's own picture. It sees the scene's renderables, lights, environment and sky (not
+   * its overlays) from the camera's WORLD pose (scale ignored) through `fov` / `near` / `far` at the texture's aspect,
+   * with the `layers` and `shadows` the camera was made with, at the scene camera's exposure; its post-processing is the
+   * engine's default tone mapping (the scene's grading, bloom and the rest are not mirrored). Moving the camera to
+   * another scene later does not move the view.
+   *
+   * COST: every render is another pass over the scene — with `shadows`, its own shadow maps too. Keep the texture small,
+   * draw less often (`everyNth`), leave out what the view does not need (`layers`), and turn it off out of sight
+   * (`enabled = false`).
+   *
+   * Calling it again REPLACES the texture and the view: the previous view stops at once, its texture keeps its last
+   * picture while something still shows it. Throws on the scene camera, and on a host without render textures (the web
+   * hosts, for now).
+   */
+  renderToTexture(options: RenderToTextureOptions = {}): RenderTexture {
+    this._secondaryOnly("renderToTexture")
+    const texture = makeRenderTexture("camera.renderToTexture", side(options.width ?? 256), side(options.height ?? 256), 0)
+    if (this._view) {   // replaced: the old view stops now; its handle goes with this reference
+      _creator.setRenderViewOptions?.(this._view.id, false, 1, 6)
+      this._view = null
+    }
+    this._texture = texture
+    awaitScene(this)
+    return texture
+  }
+
+  /** @internal Node.ts awaitScene: the camera is in scene `sceneId` — start its view into its texture. */
+  _bindView(sceneId: number): void {
+    const texture = this._texture
+    if (this._view || !texture) return
+    this._view = startRenderView("camera", sceneId, texture, this.id, this._layers, this._fov, this._near, this._far, this._shadows)
+    if (this._view && (!this._enabled || this._everyNth !== 1)) this._sendSchedule()
+  }
+
+  /** The texture `renderToTexture` made — the latest, null before one. */
+  get texture(): RenderTexture | null { return this._texture }
+
+  /** Whether this secondary camera's view draws (default `true`). Off keeps the last picture in its texture and costs
+   *  nothing — a mirror out of sight; back on, it renders on the next frame drawn. The scene camera always draws (reads
+   *  `true`; setting it throws). */
+  get enabled(): boolean { return this._enabled }
+  set enabled(on: boolean) {
+    this._secondaryOnly("enabled")
+    this._enabled = on
+    this._sendSchedule()
+  }
+  /** Render this secondary camera's view once every N frames DRAWN (default 1 = every frame). The count restarts with
+   *  each change: the next frame drawn renders, then one in every N. The scene camera draws every frame (reads 1;
+   *  setting it throws). */
+  get everyNth(): number { return this._everyNth }
+  set everyNth(n: number) {
+    this._secondaryOnly("everyNth")
+    this._everyNth = Math.max(1, Math.floor(n))
+    this._sendSchedule()
+  }
+
+  /** @internal Send the whole schedule (`setRenderViewOptions` restarts the count, so the next frame drawn renders). */
+  private _sendSchedule(): void {
+    if (this._view) _creator.setRenderViewOptions?.(this._view.id, this._enabled, this._everyNth, 6)
+  }
+
   /** Exposure compensation in stops (default 0): +1 doubles how bright the scene renders, −2
    *  quarters it. The one exposure knob most games need — a dark interior, a flash of white, or eye
    *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
    *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
-   *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+   *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. The
+   *  scene camera's: a secondary camera's view renders at its scene camera's exposure (what is set on
+   *  a secondary camera is kept, unused). */
   /** The camera's EV100 with the compensation in: log2(aperture² / shutterSpeed x 100 / iso) - compensation. Sunny 16 is
    *  ~15; a lit surface of luminance L lands on screen at L / (1.2 x 2^ev100). */
   get ev100(): number {
@@ -99,7 +247,7 @@ export class Camera extends Node {
 
   /** The physical camera: `aperture` in f-stops, `shutterSpeed` in seconds, `iso`, plus the same
    *  `compensation` in stops — any subset, one call. `camera.setExposure({ iso: 400 })` is two stops
-   *  brighter than the default f/16 · 1/125 · ISO 100. */
+   *  brighter than the default f/16 · 1/125 · ISO 100. The scene camera's (as `exposureCompensation`). */
   setExposure(exposure: { aperture?: number, shutterSpeed?: number, iso?: number, compensation?: number }): this {
     if (exposure.aperture !== undefined) this._exposure.aperture = exposure.aperture
     if (exposure.shutterSpeed !== undefined) this._exposure.shutterSpeed = exposure.shutterSpeed
@@ -117,17 +265,25 @@ export class Camera extends Node {
     _creator.setCameraExposure?.(this._sceneId, e.aperture, e.shutterSpeed, e.iso * 2 ** this._ev)
   }
 
-  /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. */
-  get fov(): number { return _creator.getCameraFov(this._sceneId, 0) }
+  /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. Live on both kinds: a
+   *  secondary camera's reaches its view at the next render (before `renderToTexture`, the view's starting value). */
+  get fov(): number { return this._sceneId >= 0 ? _creator.getCameraFov(this._sceneId, 0) : this._fov }
   set fov(degrees: number) { this._fov = degrees; this._projSet = true; this._applyProjection() }
-  get horizontalFov(): number { return _creator.getCameraFov(this._sceneId, 1) }
+  /** The horizontal field of view in degrees: the scene camera's at the screen's aspect, a secondary camera's at its
+   *  texture's (square before `renderToTexture`). */
+  get horizontalFov(): number {
+    if (this._sceneId >= 0) return _creator.getCameraFov(this._sceneId, 1)
+    const t = this._texture
+    const aspect = t ? t.width / t.height : 1
+    return Math.atan(Math.tan(this._fov * Math.PI / 360) * aspect) * 360 / Math.PI
+  }
 
-  /** Near clip distance (default 0.01) — nothing closer than this draws. */
+  /** Near clip distance (default 0.01) — nothing closer than this draws. Live, as `fov`. */
   get near(): number { return this._near }
   set near(distance: number) { this._near = distance; this._projSet = true; this._applyProjection() }
 
   /** Far clip distance / view range (default 1000) — geometry past it is culled. Shadows keep
-   *  their own (shorter) range, so a long view distance doesn't cost shadow sharpness. */
+   *  their own (shorter) range, so a long view distance doesn't cost shadow sharpness. Live, as `fov`. */
   get far(): number { return this._far }
   set far(distance: number) { this._far = distance; this._projSet = true; this._applyProjection() }
 
@@ -141,11 +297,22 @@ export class Camera extends Node {
     return this
   }
 
-  /** Hosts that predate the call keep the fixed defaults (older wasm / native builds). */
+  /** Hosts that predate the call keep the fixed defaults (older wasm / native builds); a secondary camera's view keeps
+   *  the projection it started with (warned once). */
   private _applyProjection(): void {
-    if (this._sceneId < 0 || typeof _creator.setCameraProjection !== "function") return
+    if (this._sceneId < 0) {
+      if (!this._view) return   // remembered: the view starts with it
+      if (_creator.setRenderViewProjection) _creator.setRenderViewProjection(this._view.id, this._fov, this._near, this._far)
+      else if (!Camera._warnedViewProjection) {
+        Camera._warnedViewProjection = true
+        console.warn("[camera] this host has no setRenderViewProjection — a secondary camera keeps the projection its view started with")
+      }
+      return
+    }
+    if (typeof _creator.setCameraProjection !== "function") return
     _creator.setCameraProjection(this._sceneId, this._fov, this._near, this._far)
   }
+  private static _warnedViewProjection = false
   private _following: Node | null = null
   /** The node the camera currently follows (`follow()`), or null. */
   get following(): Node | null { return this._following }
@@ -155,7 +322,9 @@ export class Camera extends Node {
    * view direction), so movement aspects / animation on that node are camera moves — dolly shots,
    * a cutscene path, a `CameraPlace` in a scene file. A node carrying a `CameraPlace` also hands
    * over its projection (fov / near / far). `follow(null)` releases the camera where it is.
-   * One camera per scene: following a new node stops following the previous one.
+   * Following a new node stops following the previous one, and a node leads one camera at a time.
+   * Either kind: the pose is written as the camera's own transform, so a following secondary
+   * camera is a scene root, not a child.
    */
   follow(target: Node | { node: Node, applyTo(camera: Camera): void } | null): this {
     const node = target === null ? null : target instanceof Node ? target : target.node
@@ -175,22 +344,26 @@ export class Camera extends Node {
 
   /** The scene view's [width, height] in logical units — the units of the scene's touches
    *  (`clientX` / `clientY`) and of `getRay`, on every host; × `device.pixelRatio` for device px.
-   *  [0, 0] before the scene has a viewport. */
+   *  [0, 0] before the scene has a viewport. The screen's, whichever camera reads it. */
   get displaySize(): [number, number] {
     const s = _creator.getDisplaySize()
     return [ s[0], s[1] ]
   }
 
-  /** World-space ray direction through a point of the scene view (logical units, as a touch's). */
+  /** World-space ray direction through a point of the scene view (logical units, as a touch's). The scene camera's
+   *  (a secondary camera throws). */
   getViewDirection(screenX: number, screenY: number): Vec3 {
-    if (this._sceneId < 0) throw new Error("Camera is not attached to a scene")
+    this._sceneOnly("getViewDirection")
     const v = new Float32Array(3)
     _creator.getCameraViewDirection(this._sceneId, screenX, screenY, v)
     return new Vec3(v[0], v[1], v[2])
   }
 
-  /** A pick ray from the camera through a point of the scene view (logical units, as a touch's). */
+  /** A pick ray from the camera through a point of the scene view (logical units, as a touch's). The scene camera's
+   *  (a secondary camera throws). */
   getRay(screenX: number, screenY: number): Ray {
+    this._sceneOnly("getRay")
     return new Ray(this.worldPosition, this.getViewDirection(screenX, screenY))
   }
 }
+