lecodes-cli 0.18.1 → 0.19.0

package/runtime/sdk/runtime/device.ts

@@ -7,12 +7,17 @@ import { appEventsOn, appEventsOff } from "./appEvents"
 
 type ResizeCallback = (width: number, height: number) => void
 
+type HdrChangeCallback = (headroom: number) => void
+
 type DeviceEventMap = {
   resize: ResizeCallback
   /** Connectivity came back (best-effort, navigator.onLine semantics). */
   online: () => void
   /** Connectivity was lost. */
   offline: () => void
+  /** The headroom the 3D engine renders to moved (`device.hdr.headroom`): the display ramped up to
+   *  its peak after launch, brightness changed, the window went to another screen. */
+  hdrchange: HdrChangeCallback
 }
 
 const resizeListeners: ResizeCallback[] = []
@@ -22,6 +27,25 @@ const onResize = (width: number, height: number): void => {
   for (const cb of resizeListeners.slice()) cb(width, height)
 }
 
+// --- device.hdr state ---
+// The 3D bridge is a free global that a 2D-only bundle never defines — reach it defensively. Hosts
+// without the methods are SDR by definition; the look setters are remembered so the getters read
+// back what the app asked for.
+const gl = (): typeof _creator | undefined => (typeof _creator !== "undefined" ? _creator : undefined)
+let hdrStrengthLocal = 0.35
+let hdrPaperWhiteLocal = 1
+// `hdrchange` is a poll: the engine quantises the headroom to half-stops, so a change is rare and
+// a 4 Hz timer (only while someone listens) is cheaper than a per-frame bridge call.
+const hdrListeners: HdrChangeCallback[] = []
+let hdrPollTimer: ReturnType<typeof setInterval> | undefined
+let hdrLastHeadroom = 1
+const pollHdr = (): void => {
+  const h = device.hdr.headroom
+  if (h === hdrLastHeadroom) return
+  hdrLastHeadroom = h
+  for (const cb of hdrListeners.slice()) cb(h)
+}
+
 /** Semantic haptic styles for `device.vibrate`. Impact styles (`light`/`medium`/`heavy`/`soft`/
  *  `rigid`) are a physical "tap" of varying weight; notification styles (`success`/`warning`/`error`)
  *  cue an outcome; `selection` is a light tick for a value change. Chosen to map 1:1 onto iOS
@@ -66,7 +90,10 @@ const orientedAttitude = (s: ArrayLike<number>): Quat => {
 }
 
 export const device = {
-  get platform(): "web" | "android" | "ios" | string {
+  /** Which INPUT MODEL the app is running under — the thing to branch on when a build needs
+   *  mouse-look instead of on-screen sticks. It is not the OS name: a Mac reports `"desktop"`,
+   *  like Windows and Linux do (the OS/version detail is host-side, not here). */
+  get platform(): "web" | "android" | "ios" | "desktop" | string {
     return _creatorUtils.platform
   },
   get language(): string {
@@ -162,6 +189,63 @@ export const device = {
       return new Vec3(g.x, -g.y, g.z)
     },
   },
+  /** The display's extended dynamic range — HDR. On a screen with headroom above SDR white (Apple's
+   *  XDR panels; the macOS host today) the 3D surface is float and the engine renders past 1.0:
+   *  1.0 is the white of the UI and of a diffuse white surface, and the sun, emissives and speculars
+   *  climb up to `headroom` times that. Everywhere else it is SDR: `available` false, `headroom` 1,
+   *  the look setters remembered but invisible.
+   *
+   *  Branch content on `available`, not on `headroom` — the live value ramps up from 1 over the
+   *  first seconds after launch and follows the brightness keys. Particle `emissive` is the thing
+   *  to raise: it is in post-exposure units (1 = white on screen) and everything above that clips on
+   *  SDR, so an HDR display is the only place a fireball peaking at 8 reads as one. */
+  hdr: {
+    /** Whether the surface can show anything above SDR white at all (`maxHeadroom > 1`). */
+    get available(): boolean {
+      return device.hdr.maxHeadroom > 1
+    },
+    /** The peak the display can reach, as a multiple of SDR white (a 1600-nit XDR panel reports up
+     *  to 16). Constant for the surface; 1 on SDR. */
+    get maxHeadroom(): number {
+      const v = gl()?.getDisplayMaxHeadroom?.() ?? 1
+      return v > 1 ? v : 1
+    },
+    /** The headroom the engine renders to right now — the screen's current peak as a multiple of SDR
+     *  white, quantised to half-stops. Moves with brightness and the screen under the window
+     *  (`hdrchange` event); never below 1. */
+    get headroom(): number {
+      const v = gl()?.getDisplayHeadroom?.() ?? 1
+      return v > 1 ? v : 1
+    },
+    /** How much of the picture reaches for the headroom, 0..1 (default 0.35). 0 touches only what
+     *  SDR clipped — faithful to the SDR grade, but a mostly-mid-tone frame then looks flat next to
+     *  the one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit exterior
+     *  takes 1, a dim interior wants less. A host may pin it (`LECODES_HDR_STRENGTH`). */
+    get strength(): number {
+      return gl()?.getHdrStrength?.() ?? hdrStrengthLocal
+    },
+    set strength(v: number) {
+      const s = Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0.35
+      hdrStrengthLocal = s
+      gl()?.setHdrStrength?.(s)
+    },
+    /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
+     *  console game's calibration screen, where paper white sits at ~200 nits against SDR's ~100.
+     *  It scales the WHOLE picture: at 1 a white wall is as bright as the UI's white, at 2 it is
+     *  twice that, and highlights still climb above it (the engine keeps `headroom / paperWhite` for
+     *  them, clamped at the peak). `strength` decides how much of the picture reaches for the
+     *  peak; this decides where the picture starts. 1.5–2 is the console norm; a game that wants to
+     *  read as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. A host may
+     *  pin it (`LECODES_HDR_PAPER_WHITE`). */
+    get paperWhite(): number {
+      return gl()?.getHdrPaperWhite?.() ?? hdrPaperWhiteLocal
+    },
+    set paperWhite(v: number) {
+      const p = Number.isFinite(v) ? Math.min(8, Math.max(1, v)) : 1
+      hdrPaperWhiteLocal = p
+      gl()?.setHdrPaperWhite?.(p)
+    },
+  },
   /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
    *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /
    *  `"offline"`. */
@@ -173,6 +257,14 @@ export const device = {
       appEventsOn(channel, callback as () => void)
       return
     }
+    if (channel === "hdrchange") {
+      hdrListeners.push(callback as HdrChangeCallback)
+      if (hdrPollTimer === undefined) {
+        hdrLastHeadroom = device.hdr.headroom
+        hdrPollTimer = setInterval(pollHdr, 250)
+      }
+      return
+    }
     if (channel !== "resize") return
     resizeListeners.push(callback as ResizeCallback)
     if (!resizeRegistered) {
@@ -185,6 +277,15 @@ export const device = {
       appEventsOff(channel, callback as () => void)
       return
     }
+    if (channel === "hdrchange") {
+      const i = hdrListeners.indexOf(callback as HdrChangeCallback)
+      if (i >= 0) hdrListeners.splice(i, 1)
+      if (hdrListeners.length === 0 && hdrPollTimer !== undefined) {
+        clearInterval(hdrPollTimer)
+        hdrPollTimer = undefined
+      }
+      return
+    }
     if (channel !== "resize") return
     const i = resizeListeners.indexOf(callback as ResizeCallback)
     if (i >= 0) resizeListeners.splice(i, 1)