lecodes-sdk 2.4.7 → 2.4.8

package/src/gl/RenderTexture.ts

@@ -0,0 +1,93 @@
+// A texture a render view draws into (creator-gl renderview.cpp; creator.h createRenderTexture / createRenderView /
+// setRenderViewOptions / setRenderViewProjection / readRenderTexturePixels). Only the texture: the view drawing into it
+// belongs to what made it — a secondary Camera (`camera.renderToTexture`, a 2D picture) or a ReflectionProbe (a cube) —
+// which holds the view's owned handle, its schedule and its projection. The helpers below are those two makers' shared
+// half: the host's texture, and the view started once their node is in a scene (Node.ts awaitScene).
+
+import { Texture } from "./Texture"
+
+/** @internal `_creator.createRenderTexture` flags (creator.h CREATOR_RENDER_TEXTURE_*). */
+export const RT_FLAG_CUBEMAP = 1
+/** @internal */
+export const RT_FLAG_HDR = 2
+/** @internal */
+export const RT_FLAG_PREFILTER = 4
+/** @internal `_creator.createRenderView` flags bit: no shadow maps in this view (creator.h CREATOR_RENDER_VIEW_SHADOWS_OFF). */
+const VIEW_FLAG_SHADOWS_OFF = 1
+/** @internal The longest side the host takes (creator.h createRenderTexture). */
+export const RT_MAX_SIDE = 4096
+
+/**
+ * A texture a render view draws into — made by `camera.renderToTexture({ width, height })` (a 2D picture: the
+ * tone-mapped image as the screen would show it) or by a `ReflectionProbe` (`probe.texture`: a cube of linear HDR light).
+ * It IS a `Texture`: a 2D one goes wherever an image does (`material.map` — a monitor, a rear-view mirror), a cube
+ * wherever a cubemap does (`scene.environment` takes the probe itself).
+ *
+ * ROW ORDER: a 2D render texture's first texel row is the BOTTOM of the camera's picture (OpenGL's order, on every
+ * backend) — an image's first row is its top. A mesh whose v runs UP its face (`Mesh.plane`) shows it upright as is; one
+ * laid out like a glTF (v down) samples it with v flipped. A cube face is laid out as every GPU's cube lookup reads it.
+ *
+ * LIFETIME: the texture lives while something holds it — the camera or probe that made it (each keeps its texture), a
+ * material showing it — and keeps its last picture when its view stops (`enabled = false`, the camera's next
+ * `renderToTexture`, the camera gone).
+ */
+export class RenderTexture extends Texture {
+  /** A cube (a `ReflectionProbe`'s) rather than a 2D picture (a `Camera`'s). A cube's `width` and `height` are both its
+   *  edge. */
+  readonly cubemap: boolean
+
+  /** @internal Made by `Camera.renderToTexture` and `ReflectionProbe` (through `makeRenderTexture`): the size, the
+   *  kind and the texture's owned handle. */
+  constructor(width: number, height: number, cubemap: boolean, texture: Handle) {
+    super(width, height, texture)
+    this.cubemap = cubemap
+  }
+
+  /**
+   * RGBA8 bytes (`width × height × 4`) of a rectangle of the texture as the NEXT frame drawn leaves it — a GPU
+   * readback, for checks and tools, not a per-frame path. Rows come in the texture's own order: the first is texel row
+   * `y`, which for a 2D texture counts from the picture's BOTTOM. `face` 0..5 = +X −X +Y −Y +Z −Z of a cube (0 for a 2D
+   * picture). A camera's (LDR) texture gives its stored sRGB bytes, a probe's (HDR) its linear light clamped to 0..1 —
+   * a prefiltered probe its sharpest level. Rejects on a host without the call, or when the host refuses the read (the
+   * rectangle outside the texture, the engine gone first).
+   */
+  readPixels(x: number, y: number, width: number, height: number, face = 0): Promise<Uint8Array> {
+    if (!_creator.readRenderTexturePixels) return Promise.reject(new Error("RenderTexture.readPixels: this host has no readRenderTexturePixels"))
+    return new Promise<Uint8Array>((resolve, reject) => {
+      _creator.readRenderTexturePixels!(this._h.id, face, x, y, width, height, (pixels) => {
+        if (pixels) resolve(pixels)
+        else reject(new Error(`RenderTexture.readPixels: the host refused (${x}, ${y}) ${width}×${height} of face ${face}`))
+      })
+    })
+  }
+}
+
+/** @internal Throw for `who` on a host without render textures (createRenderTexture + createRenderView). */
+export const requireRenderTextures = (who: string): void => {
+  if (!_creator.createRenderTexture || !_creator.createRenderView) {
+    throw new Error(`${who}: this host has no render textures (createRenderTexture) — the web hosts do not yet`)
+  }
+}
+
+/** @internal The host's render texture (`flags` RT_FLAG_*; a cube's `height` is its `width`), or a throw naming `who`. */
+export const makeRenderTexture = (who: string, width: number, height: number, flags: number, samples = 0): RenderTexture => {
+  requireRenderTextures(who)
+  const cube = (flags & RT_FLAG_CUBEMAP) !== 0
+  const texture = _creator.createRenderTexture!(width, cube ? 0 : height, flags, samples)
+  if (!texture || texture.id === 0xFFFFFFFF) {
+    throw new Error(`${who}: the host refused a ${cube ? `cube of ${width}` : `${width}×${height}`} render texture (sides 1..${RT_MAX_SIDE})`)
+  }
+  return new RenderTexture(width, cube ? width : height, cube, texture)
+}
+
+/** @internal Start a render view of scene `sceneId` into `texture` from entity `poseId` (createRenderView), or warn for
+ *  `who` and give null — the host refuses an overlay scene. */
+export const startRenderView = (
+  who: string, sceneId: number, texture: RenderTexture, poseId: number,
+  layers: number, fov: number, near: number, far: number, shadows: boolean,
+): Handle | null => {
+  const view = _creator.createRenderView!(sceneId, texture._h.id, poseId, layers & 0xff, fov, near, far, shadows ? 0 : VIEW_FLAG_SHADOWS_OFF)
+  if (view && view.id !== 0) return view
+  console.warn(`[${who}] the host made no render view in scene ${sceneId} (an overlay scene has none) — its texture stays empty`)
+  return null
+}

package/src/gl/Scene.ts

@@ -18,8 +18,9 @@ import { Camera } from "./Camera"
 import { SceneAudio } from "./audio/SceneAudio"
 import { Material } from "./Material"
 import { PostProcessing, type PostProcessingOptions } from "./postProcessing"
+import { ReflectionProbe } from "./ReflectionProbe"
 import { Texture } from "./Texture"
-import { Node, nodes } from "./Node"
+import { Node, bindPendingViews, nodes, sceneIdOf } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 
@@ -176,6 +177,12 @@ export class Scene implements Presentable {
   /** @internal what `environmentIntensity` currently asks for — the accessor's backing field, so it
    *  answers on hosts whose engine has no live setter too. */
   _environmentIntensity = 20000
+  /** @internal The probe the constructor named for `setDefaultIbl` (-1 = none: the project-wide
+   *  `ibl.ktx`) — re-sent when `environment` goes back to null. */
+  _iblId = -1
+  /** @internal What `environment` lights the scene from (null = the scene's own probe). Holding it
+   *  keeps the probe — its cube and the view drawing into it — alive while it lights. */
+  _environment: ReflectionProbe | null = null
   readonly camera: Camera
   /** The listener + global 3D audio knobs (docs/audio-plan.md). */
   readonly audio: SceneAudio = new SceneAudio()
@@ -226,6 +233,7 @@ export class Scene implements Presentable {
       // "no probe named", which leaves the host on the project-wide `ibl.ktx` (the old behaviour).
       const src = typeof options.ibl === "string" ? options.ibl : undefined
       const iblId = src === undefined ? -1 : src.startsWith("id:") ? Number(src.slice(3)) : _creatorFetch.local(src)
+      this._iblId = iblId
       _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000, iblId)
     }
     this._environmentIntensity = options.ibl === false ? 0 : (options.environmentIntensity ?? 20000)
@@ -341,6 +349,44 @@ export class Scene implements Presentable {
     }
   }
   private static _warnedEnvIntensity = false
+
+  /**
+   * Light the scene from a live REFLECTION PROBE (ReflectionProbe.ts) — a cube drawn around the probe's position, the
+   * probe riding the car / standing in the room: chrome and glass show what is actually around them, moving objects
+   * included. `null` gives the light back to the scene's own probe (`SceneOptions.ibl`, at `environmentIntensity`;
+   * re-installing it reloads the probe — a switch, not a per-frame call). A probe in no scene yet starts its view in this
+   * one; one already in another scene draws only while that scene is on show.
+   *
+   * Prefiltered (the default), the probe gives the reflections at every roughness — a car body, painted metal blur it as
+   * they should — and the diffuse ambient too (then `environmentIntensity` no longer changes it); it costs a GPU
+   * filtering per completed cube (`ReflectionProbeOptions.prefilter`). `prefilter: false` gives one sharp level:
+   * mirror-like surfaces (roughness near 0) are right, rougher ones read the sharp cube too, and only the reflections
+   * change — the diffuse ambient keeps the scene's own probe's shape at `environmentIntensity`.
+   *
+   * A probe that draws while it lights reads what it writes — fine on OpenGL; a Vulkan backend may want two probes in
+   * turn (a prefiltered probe never does: it lights from the filtered copy). Leave the probe's own carrier out of its view
+   * (`layers`), or the cube is the inside of the car. Warns once on a host without the call.
+   */
+  get environment(): ReflectionProbe | null { return this._environment }
+  set environment(probe: ReflectionProbe | null) {
+    if (probe !== null && !(probe instanceof ReflectionProbe)) {
+      throw new Error("scene.environment: a ReflectionProbe (new ReflectionProbe({ size: 128 })) or null")
+    }
+    if (probe === this._environment) return
+    this._environment = probe
+    if (probe && sceneIdOf(probe) < 0) probe._bindView(this._id)   // in no scene yet: its view starts in this one
+    if (!_creator.setEnvironmentTexture) {
+      if (!Scene._warnedEnvTexture) {
+        Scene._warnedEnvTexture = true
+        console.warn("[scene] this host has no setEnvironmentTexture — environment stays the scene's own probe")
+      }
+      return
+    }
+    if (probe) _creator.setEnvironmentTexture(this._id, probe.texture._h.id)
+    else _creator.setDefaultIbl(this._id, this._environmentIntensity, this._iblId)   // installing a probe frees the cube's light
+  }
+  private static _warnedEnvTexture = false
+
   /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
   setStencil(enabled: boolean): void {
     if (_creator.setSceneStencil) _creator.setSceneStencil(this._id, enabled)
@@ -348,12 +394,18 @@ export class Scene implements Presentable {
   }
 
   add(...list: Node[]): this {
-    for (const n of list) { _creator.addEntityToScene(this._id, n.id); nodes.pin(n) }   // the scene owns it now
+    for (const n of list) {
+      _creator.addEntityToScene(this._id, n.id)
+      nodes.pin(n)          // the scene owns it now
+      n._inScene = this._id // what a render view under it starts in (Node.ts sceneIdOf)
+    }
+    bindPendingViews()
     return this
   }
   remove(...list: Node[]): this {
     for (const n of list) {
       _creator.removeEntityFromScene(this._id, n.id)
+      if (n._inScene === this._id) n._inScene = -1
       if (!_creator.entityIsOwned(n.id)) nodes.unpin(n.id)   // loose again: its handle owns it
     }
     return this

package/src/inject.ts

@@ -251,7 +251,11 @@ export type { ScatterPlacement, ScatterOptions } from "./gl/Scatter"
 export type { InstanceTransform } from "./gl/InstancedMesh"
 export { Texture } from "./gl/Texture"
 export type { TextureLoadOptions } from "./gl/Texture"
+export { RenderTexture } from "./gl/RenderTexture"
 export { Camera } from "./gl/Camera"
+export type { CameraOptions, RenderToTextureOptions } from "./gl/Camera"
+export { ReflectionProbe } from "./gl/ReflectionProbe"
+export type { ReflectionProbeOptions } from "./gl/ReflectionProbe"
 export { Ray } from "./gl/Ray"
 export { Plane } from "./gl/Plane"
 export { Noise } from "./gl/Noise"

package/src/ui/tree.ts

@@ -93,6 +93,7 @@ export const OWNED_KIND_ENTITY_2D = 5
 export const OWNED_KIND_MEDIA = 6
 export const OWNED_KIND_TWEEN = 7
 export const OWNED_KIND_CANVAS = 8
+export const OWNED_KIND_GL_RENDER_VIEW = 9
 
 // PanDirection (creator-pkg.h) — the low byte of a track answer.
 import { DEAD_HANDLE } from "../core/pins"

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.4.7"
+export const SDK_VERSION = "2.4.8"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {