lecodes-sdk 2.4.6 → 2.4.8

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.6",
+  "version": "2.4.8",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -14,9 +14,11 @@ export type PickBone = { name: string, weight: f32 }
  *  `bones` = its JOINTS_0 / WEIGHTS_0 pairs with weight > 0 (empty = unweighted). */
 export type PickVertex = { index: u32, bind: [f32, f32, f32], world: [f32, f32, f32], bones: PickBone[] }
 /** The closest triangle under a screen point (`pickTriangle`). `node` = the mesh node's own entity (0
- *  when the host has none), `lightmapGroup` / `uv1` only when the node / primitive carry them. */
+ *  when the host has none), `lightmapOrdinal` = the primitive's index over the file's meshes (the bake's record
+ *  `<key>@<ordinal>`), `uv1` (the lightmap uv the GPU reads: the bake's packed one when loaded) only when the primitive
+ *  carries one. */
 export type TrianglePick = {
-  entity: u32, node: u32, nodeName: string, lightmapGroup?: i32,
+  entity: u32, node: u32, nodeName: string, lightmapOrdinal: u32,
   mesh: string, primitive: u32, material: string,
   triangle: u32, backface: boolean, distance: f32,
   point: [f32, f32, f32], bary: [f32, f32, f32], uv1?: [f32, f32],
@@ -182,6 +184,10 @@ declare global {
      *  not the roughness-prefiltered `_ibl.ktx` beside it. Optional: hosts that predate it keep the
      *  flat skybox. */
     setSkyboxTexture?(sceneId: u32, fetchId: bytes): void
+    /** Optional. Light the scene from a CUBEMAP texture (a render texture's cube, creator.h setEnvironmentTexture): the
+     *  IBL reflects it, its irradiance and intensity stay; no roughness prefiltering, so only mirror-like reflections are
+     *  right. The engine holds the texture while it lights; setDefaultIbl replaces it. */
+    setEnvironmentTexture?(sceneId: u32, textureId: u32): void
     /** Temporal anti-aliasing (Filament's TAA) for the scene and its overlays: on, MSAA and FXAA are off for the
      *  view; `feedback` = the history's share (0.12 default, higher = less ghosting, less smoothing), `sharpness` =
      *  the post-TAA sharpen (0–1), `upscale` = the fraction the 3D is rendered at and TAA-upscaled from (0.5–1,
@@ -323,6 +329,30 @@ declare global {
      *  re-uploads a sub-rectangle with the creation channel count. Optional (Texture.fromPixels throws). @args data width height channels srgb @count pixelBytes=data @owned GlTexture */
     createTexturePixels?(width: u32, height: u32, channels: u32, data: Uint8Array, srgb: boolean): Handle
     updateTexturePixels?(textureId: u32, x: u32, y: u32, width: u32, height: u32, data: Uint8Array): void
+    /** Optional. A RENDER TEXTURE, what a render view draws into (creator.h createRenderTexture): `flags` bit 1 = CUBEMAP
+     *  (`width` = the edge, `height` ignored), bit 2 = HDR (R11F_G11F_B10F linear light, for lighting); neither = an LDR
+     *  display texture (SRGB8_A8, the tone-mapped picture); bit 4 = PREFILTER, with both others only (flags 7, a
+     *  power-of-two edge of 16 at least): a probe filtered for roughness — the id is the 5-level filtered cube, its views
+     *  draw a raw one behind it, filtered on the GPU at the frame after each completed cube with `samples` samples
+     *  (0 = 256; read for PREFILTER only). Otherwise an ordinary texture id (setUniformTexture, setSceneBackground); its
+     *  texel rows run as OpenGL renders, on every backend (a 2D texture's first row = the picture's bottom). 0xFFFFFFFF
+     *  on failure. @owned GlTexture */
+    createRenderTexture?(width: u32, height: u32, flags: u32, samples: u32): Handle
+    /** Optional. A RENDER VIEW of the scene into a render texture, from node `cameraEntityId` (its world pose, read every
+     *  frame; a cube takes its position only): `layerMask` = the layers it sees (setLayer), `fov` vertical degrees (a cube
+     *  is 90), `flags` bit 1 = no shadows. Drawn each frame its scene is presented, before the scene's own view; freeing the
+     *  texture takes its views with it. 0 on failure. @owned GlRenderView */
+    createRenderView?(sceneId: u32, textureId: u32, cameraEntityId: u32, layerMask: u8, fov: f32, near: f32, far: f32, flags: u32): Handle
+    /** Optional. `everyNth` 1 = every frame, N = one render per N frames drawn, counted afresh from this call (the next
+     *  frame renders); `facesPerFrame` 1..6 for a cube (round-robin). */
+    setRenderViewOptions?(renderViewId: u32, enabled: boolean, everyNth: u32, facesPerFrame: u32): void
+    /** Optional. The view's projection, live (createRenderView's fov / near / far were the initial values): a 2D view's
+     *  vertical fov in degrees and clip planes; a cube ignores `fov` (90) and takes the planes. Unknown id = no-op. */
+    setRenderViewProjection?(renderViewId: u32, fov: f32, near: f32, far: f32): void
+    /** Optional. RGBA8 bytes of a rectangle of a render texture as the next frame leaves it — rows in the texture's order
+     *  (the first is texel row `y`), `face` 0..5 = +X -X +Y -Y +Z -Z of a cube (0 for 2D), an HDR one clamped to 0..1
+     *  (linear); null when refused. A GPU readback, for checks and tools. @custom */
+    readRenderTexturePixels?(textureId: u32, face: u32, x: u32, y: u32, width: u32, height: u32, onDone: (pixels: Uint8Array | null) => void): void
 
     /** A material INSTANCE of these .filamat bytes (an app's own shader, fetched); the material itself is deduplicated by content in the engine. @c createMaterialInstanceFromBytes @owned GlMaterial @throw createMaterial: no .filamat bytes behind this fetch id */
     createMaterial(systemId: bytes): Handle
@@ -353,6 +383,12 @@ declare global {
 
     setVisible(entityId: u32, visible: boolean): void
     isVisible(entityId: u32): boolean
+    /** Optional. Visibility layers: the entity's explicit layer bits (u8), inherited by its subtree down to a
+     *  descendant with its own; 0 clears them (inherit again). Nothing set = 0x01. A view draws a renderable
+     *  when their layers share a bit (the scene's own view sees all). A host without it has no layers. @c setEntityLayer */
+    setLayer?(entityId: u32, mask: u8): void
+    /** Optional. The entity's effective layer bits: its own, else the nearest ancestor's, else 0x01. @c getEntityLayer */
+    getLayer?(entityId: u32): u8
 
     /** @custom */
     createGlb(systemId: bytes, onComplete: (root: Handle | null) => void, onReject: () => void): void
@@ -671,23 +707,31 @@ declare global {
     // JoltPhysics. motionType: 0 static / 1 kinematic / 2 dynamic.
     /** @c creatorHasPhysics */
     physicsHasSupport(): boolean
-    /** Lightmap bake (engines/bake) — a dev-time tool compiled into the desktop host only; `lightmapBake` exists
+    /** Lightmap bake (engines/bake) — a dev-time tool compiled into the bake tool lecodes-bake only; `lightmapBake` exists
      *  only where `lightmapHasSupport()` is true. Describes the given static instances (GLB roots / Mesh entities;
      *  `keysJoined` = one key per id, '
 '-joined), the scene's brightest sun, its point lights (spherical emitters of
-     *  `lightRadius` metres) and its IBL to the bake, which traces them on the NVIDIA card — direct light plus
+     *  `lightRadius` metres) and its IBL to the bake, which traces them on the GPU (`tracer`: 0 auto = OptiX where an NVIDIA driver
+     *  with OptiX opens, else Vulkan ray query on any card with hardware ray tracing; 1 OptiX, 2 Vulkan by name) — direct light plus
      *  `bounceRays` Lambertian paths of `bounces` vertices per texel (0 / 0 = direct only) with `patchSamples` next-event
      *  samples over the bright patches of a first direct pass — and writes
      *  `<outDir>/<stem>.bake` + `<stem>-light[_n].ktx2` (irradiance in lux / lightScale, BC6H) + `<stem>-aux[_n].ktx2`
      *  (sun / sky visibility + light direction); `split` adds `<stem>-direct[_n]` / `-indirect[_n]` page sets for the
-     *  SDK's two views; `denoise` runs OptiX's AI denoiser over 0 nothing, 1 the indirect part, 2 + the sky and the lamps, 3 + the sun; `filter` = the texel's reconstruction filter radius in texels (1 = ±1 texel tent, 0.5 = within the texel, 0 = the centre alone);
+     *  SDK's two views; `denoise` runs the AI denoiser (`denoiser`: 0 auto = OptiX's on an NVIDIA card, else Intel Open Image Denoise; 1 OptiX, 2 OIDN by name —
+     *  independent of the tracer) over 0 nothing, 1 the indirect part, 2 + the sky and the lamps, 3 + the sun; `filter` = the texel's reconstruction filter radius in texels (1 = ±1 texel tent, 0.5 = within the texel, 0 = the centre alone);
      *  `probeSpacing` > 0 places REFLECTION PROBES on a grid of that many metres and writes `<stem>-probes.ktx2` (a BC6H atlas of octahedral
      *  maps: one column of roughness-level tiles per probe, captured with `probeSize`² cube faces and `probeRays` paths per texel; the scene's
      *  IBL cubemap is what an escaping ray sees; `probeIndoor` keeps only the probes under a roof (an open share of the sphere of at most 15 %) — the
      *  outdoors reflects the sky through the texel's baked sky visibility instead; `volumeSpacing` (metres, 0 = none) bakes THE LIGHT GRID for movers — `<name>.lgrid`, named in the .bake's `volume`: per cell
      *  in free space an ambient cube without the direct sun, links between neighbours a ray connects (what `setAmbientCube`
-     *  is fed from); `minSize` (metres, 0 = off) leaves every instance smaller than that along every axis out of the atlas — an occluder
-     *  only, `"small": true` + its `light` (an ambient cube baked where it stands) in the .bake, applied by lightmapObjectApply; `probeLayout` 0 = ROOMS (indoor points slide to their
+     *  is fed from); `minSize` (metres, 0 = off) leaves every record (a mesh of an instance) smaller than that along every axis out of the atlas — an occluder
+     *  only, `"small": true` + its `light` (an ambient cube baked where it stands) in the .bake, applied by lightmapObjectApply; `thinTexels` (0 = off) does the same to every
+     *  record none of whose lightmap charts is wider than that many texels across its short side — a railing's tubes, a cable, a pipe run: a strip of 1-3 texels around a tube
+     *  cannot hold the light's change around it and its uv seam shows as a step; `objectSlab` (metres, 0 = one cube an object) gives a long one of
+     *  those round(length / objectSlab) cubes along the longest axis of its bounds (16 at most), blended per pixel along it; BY HAND, the same way out of
+     *  the atlas: every record whose key (`<node key>@<ordinal>`) `cubeKeys` matches — an ECMAScript regular expression, searched, case-sensitive ("" = off; one
+     *  that does not compile fails the bake: "error: bad --cube pattern") — and every record of the entities in `cubeIds` (of `entityIds`: a node's
+     *  `lightmap: 'cube'`), whatever their size or charts; `probeLayout` 0 = ROOMS (indoor points slide to their
      *  room's middle and merge: one probe per room), 1 = GRID; `probeBox` = 6 floats, min xyz + max xyz, keeps the grid inside that box — null = the
      *  receivers' bounds) and the grid into the .bake; `debugDir` (optional) gets the float layers per page. Synchronous; progress on stdout as
      *  "[lightmap] …" lines, "[lightmap] done" on success. @c creatorHasLightmapBake */
@@ -697,7 +741,7 @@ declare global {
                   sunRays: u32, skyRays: u32, lightRays: u32, lightRadius: f32, sunAngleDeg: f32, bias: f32, seed: u32,
                   bounceRays: u32, bounces: u32, patchSamples: u32, split: boolean, denoise: u32, filter: f32,
                   probeSpacing: f32, probeSize: u32, probeRays: u32, probeIndoor: boolean, probeLayout: u32, probeBox: Float32Array | null, minSize: f32, volumeSpacing: f32, emissiveNits: f32, detailTexels: u32, debugDir?: string,
-                  transmit?: string): boolean
+                  transmit?: string, tracer?: u32, denoiser?: u32, thinTexels?: f32, objectSlab?: f32, cubeKeys?: string, cubeIds?: Uint32Array): boolean
     /** Lightmap consumption: the next createGlb takes lightmap.filamat (the material behind that instance id) for its
      *  OPAQUE materials and the masked twin for its MASK materials instead of the ubershader, and keeps TEXCOORD_1;
      *  BLEND (glass) materials always keep the ubershader. 0xFFFFFFFF clears. The same call arms the foliage tier. @custom */
@@ -724,17 +768,22 @@ declare global {
      *  Returns the probe count; an invalid texture id clears. */
     lightmapProbesSet?(atlasTextureId: u32, oct: u32, levels: u32, perRow: u32, count: u32,
                        lox: f32, loy: f32, loz: f32, sx: f32, sy: f32, sz: f32): u32
-    /** Bind the light page + the aux page + this instance's rect (uv1 * [sx, sy] + [ox, oy]) on every lightmap-material
-     *  instance of the entity (a GLB instance's renderables, or a Mesh entity's own) and move those renderables to light
-     *  channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). Returns how many
+    /** Bind the light page + the aux page + a RECORD's rect (uv1 * [sx, sy] + [ox, oy]) and move the renderables it went on
+     *  to light channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). The bake's
+     *  unit is the mesh: a GLB instance is one record per primitive (`<key>@<ordinal>` in the .bake); `ordinal` >= 0 binds
+     *  that primitive (its index over the file's meshes) of every node that draws it, on a material instance of its own;
+     *  -1 (the default) = every lightmap-material primitive of the entity (a Mesh entity, a terrain). Returns how many
      *  material instances took it (0 = not loaded lightmapped). */
-    lightmapApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, sx: f32, sy: f32, ox: f32, oy: f32, group?: i32): u32
+    lightmapApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, sx: f32, sy: f32, ox: f32, oy: f32, ordinal?: i32): u32
     /** A SMALL STATIC the atlas left out (the bake's `minSize`: `small` + `light` in the .bake): no rect — the light
-     *  baked where it stands goes into its material parameters. `data` = 27 floats: the ambient cube — per side of its
-     *  bounds (+x -x +y -y +z -z) the irradiance rgb in lux and the sky visibility — then probe a, probe b, a's weight
-     *  (65535 = no probe, 65534 = the sky). The textures = any page of the level (the probes' records sit under every
-     *  aux page). Returns the material instances that took it (0 = not loaded lightmapped). @count count=data */
-    lightmapObjectApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, data: Float32Array, group?: i32): u32
+     *  baked where it stands goes into its material parameters. `data` = 7 + 24 n floats: axis (0 x, 1 y, 2 z), from, to
+     *  (its bounds along the axis), n (slabs, 1..16); then n AMBIENT CUBES, slab by slab from `from` — per side of the slab's
+     *  box (+x -x +y -y +z -z) the irradiance rgb in lux and the sky visibility; then probe a, probe b, a's weight (65535 =
+     *  no probe, 65534 = the sky). Any other count is refused. The shader blends the two slabs around a pixel along the
+     *  axis. The textures = any page of the level (the probes' records sit under every aux page). `ordinal` as
+     *  `lightmapApply` (a small record of a GLB is one primitive). Returns the material instances that took it (0 = not
+     *  loaded lightmapped). @count count=data */
+    lightmapObjectApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, data: Float32Array, ordinal?: i32): u32
     /** BAKED AMBIENT LIGHT for a mover, or anything on a standard or custom LIT shader: every renderable of the GLB
      *  instance (or the Mesh entity) takes its diffuse indirect light from `data`'s ambient cube instead of the scene's
      *  IBL, and the IBL's reflections through the sky visibility. `data` = 25 or 26 floats: six sides (+x -x +y -y +z -z) of
@@ -751,6 +800,12 @@ declare global {
      *  `lightVolumeSample(x, y, z)` = that cube at a point (26 floats, null = no grid or no valid cell near), for tools;
      *  `lightVolumeClear()` drops the grid and every mover's cube. */
     lightVolumeLoad?(fetchId: bytes): boolean
+    /** THE PACKED LIGHTMAP UV1 (`<name>-uv1.bin`, the .bake's `uv1`): the bake packs every file's lightmap charts into a
+     *  square of their own and its rects map THAT uv1. `lightmapUv1Load(fetchId)` hands the engine the fetched sidecar
+     *  (false = not one); every GLB a rect is applied to then takes its file's packed uv1 into TEXCOORD_1, once per asset
+     *  (assets bound before the call are applied again). `lightmapUv1Clear()` drops it: the models get their own uv1 back. */
+    lightmapUv1Load?(fetchId: bytes): boolean
+    lightmapUv1Clear?(): void
     lightVolumeTrack?(entityId: u32, on: boolean, fixed?: boolean): void
     lightVolumeClear?(): void
     /** @out 26 @out 26 */

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