@nakednous/host 0.0.8 → 0.0.10

package/README.md

@@ -82,6 +82,7 @@ dependency first and an options object last, and registers with the context so
 | `host.poseTrack(opts)` · `host.cameraTrack(cam, opts)` | core tracks ticked while they play; `{ handles }` builds `TrackHandles`, one handle per keyframe. `add(depth)` — the transport panel's `+` — authors where the camera is looking: a pose track places the pose at the centre of the installed camera's frustum, `depth` `0`…`1` from the near plane to the far one, aimed along that camera (the view bag's matrices; never deduplicated), a camera track captures its camera state, a placement depth being nothing a camera keyframe could use. `remove()` — the transport panel's `−` — retracts the last keyframe, one per call; `remove(i)` is the core track's own |
 | `host.hid(opts)` · `host.gamepad(opts)` | rate streams — `lin[3]` / `ang[3]` in raw device units, `bind(helm)` feeds it each tick; `available`, `connected` |
 | `host.image(url)` · `host.video(opts)` · `host.raster(draw, w, h)` | texture sources — an `ImageBitmap`, a hidden `<video>` from a file or the camera with a `ready` promise, a Canvas2D drawing |
+| `decodeRGBE(bytes, opts)` · `encodeRGBE(r, g, b, out)` | a Radiance `.hdr` file's RGBE bytes decoded to `{ data, width, height }` in linear light — three 8-bit mantissas and a shared exponent, `level · 2^(e − 136)` — and the inverse. A floating-point texture's pixels, which no browser image decoder gives: `loadImage` hands back 8-bit codes clamped at 1.0, so a tone-mapping pass would have nothing left to compress. Rows come back in the file's own order (`rowOrder: 'BOTTOM_UP'` for GL's, which is what `webgl.tree`'s `loadHDR` asks for); `maxPixels` refuses past 16 Mpixel rather than exhaust the tab. Pure, DOM-free, one allocation. Verified against three.js's `HDRLoader` and ImageMagick |
 | `host.mesh(url, opts)` | one mesh — the arrays shape `{ position, indices, normal?, tangent?, texcoord?, color?, joints?, weights? }` with its `bounds` `{ min, max, center, diag }` beside them — from an OBJ file, a one-part glTF 2.0 file (`.glb`, `.gltf`), or any format through `{ parse: (arrayBuffer) => arrays }`; what a bridge's buffer upload takes as it is, and `size / mesh.bounds.diag` fits any file to `size`. A file of several parts rejects, naming `model`. `{ format }` when the URL does not say. **`normals`**: left out, the file's normals are kept and a mesh without any gets smooth ones; `'smooth'` always recomputes them, summed per position, so a faceted file or a texture seam smooths too; `'flat'` always recomputes them on the flattened mesh (every triangle owning its vertices: more vertices, indices counting up); `false` computes nothing. The procedure, its limits and sources are tree's `mesh` module's; glTF viewers compute flat normals for a file without any — here that is `'flat'` |
 | `host.model(url, opts)` | a model with its structure — `{ parts: [{ name, node, skin, mesh, targets, color }], nodes: { names, parents, rest }, skins: [{ name, joints, inverseBind }], clips: [{ name, duration, channels }] }` — what a rig, morph targets or animation need. A part's `mesh` is as `host.mesh` returns it, in the part's own space; `targets` are morph deltas; nodes come parents first with a rest pose, and with `skins` and `clips` feed tree's `clipSample` · `poseBlend` · `poseWorld` · `jointPalette` as they are. Same options; `'flat'` flattens each part's morph targets with its mesh. An OBJ file is one white part under one identity node. host's own parsers: no textures, cameras, sparse accessors or compressed geometry |
 | `host.labels` · `host.hasLabels` | the label layer, created on first access — `set(id, text, x, y, z, opts)` at a world anchor, `setScreen(id, text, sx, sy, opts)` in canvas px, `{ frame: true }` for a label that lives one frame, `tick()`; `hasLabels` probes without creating |
@@ -92,7 +93,8 @@ dependency first and an options object last, and registers with the context so
 The module-level functions behind the methods are exported too (`createView`, `createPointer`,
 `createPlayers`, `createLoop`, `observeCanvas`, `Handle`, `PointerRouter`, `cameraHelm`,
 `poseHelm`, `helmBasis`, `poseTrack`, `cameraTrack`, `TrackHandles`, `createHid`,
-`createGamepad`, `decodeSpaceNavigator`, `loadImage`, `createVideo`, `raster`, `loadMesh`, `loadModel`, `createLabels`,
+`createGamepad`, `decodeSpaceNavigator`, `loadImage`, `createVideo`, `raster`, `loadMesh`, `loadModel`,
+`decodeRGBE`, `encodeRGBE`, `createLabels`,
 `createOrbit`), so an adapter can compose them on its own context.
 
 ---

package/dist/index.js

@@ -186,10 +186,11 @@ function observeCanvas(canvas, onChange) {
  *
  * - pointerdown · pointermove · pointerup · pointercancel on the canvas,
  *   keydown (Esc) on the window.
- * - Coordinates in logical canvas px through the element's bounding
- *   rectangle — (clientX − rect.left) · (width / rect.width), the logical
- *   size read off the view bag's vp — the numbers mapLocation(SCREEN) and vp
- *   expect, so a CSS-scaled canvas maps correctly.
+ * - Coordinates in screen space — the surface's logical pixels, top-left, y
+ *   down — through the element's bounding rectangle: (clientX − rect.left) ·
+ *   (width / rect.width), the logical size read off the view bag's vp. These
+ *   are the numbers mapLocation(SCREEN) and vp expect (a viewport of negative
+ *   height), so a CSS-scaled canvas maps correctly.
  * - Per pointer: an entry { id, x, y, seq, down, up, cancel, owner }, kept
  *   from its press until the frame after its release; `seq` counts moves,
  *   so a consumer remembers the last seq it consumed and reads only new
@@ -787,7 +788,7 @@ class Handle {
   }
 
   // The proxy's world position and its grab radius in world units — a
-  // constant grabPx screen size at the proxy's depth.
+  // constant grabPx canvas size at the proxy's depth.
   _proxyPrep() {
     const c = this._constraint, v = this._view, p = this._proxyPos;
     if (this._from && !this._grabbed) this._resolveFrame();
@@ -810,14 +811,14 @@ class Handle {
     return rayHitSphere(o[0], o[1], o[2], d[0], d[1], d[2], p[0], p[1], p[2], this._proxyRad);
   }
 
-  /** Unproject a canvas pixel into the ray scratch; false on a stale view. */
+  /** Unproject a screen-space pixel into the ray scratch; false on a stale view. */
   _ray(x, y) {
     const v = this._view;
     if (v.stale) return false;
     return unproject(_rayO, _rayD, x, y, v, v.vp, v.ndcZMin) !== null;
   }
 
-  /** Hit-test the proxy at a canvas pixel. */
+  /** Hit-test the proxy at a screen-space pixel. */
   _pickAt(x, y) {
     return this._ray(x, y) && this._proxyT(_rayO, _rayD) < Infinity;
   }
@@ -1207,7 +1208,7 @@ function cameraHelm(host, cam, opts) {
   const helm = new PoseHelm();
   _applyOpts(helm, opts);
   if (opts && opts.from != null) {
-    console.error('[host] cameraHelm: a camera helm is always body-fly and has no `from`. Ignoring it; bind the camera to a poseHelm for screen- or world-relative motion.');
+    console.error('[host] cameraHelm: a camera helm is always body-fly and has no `from`. Ignoring it; bind the camera to a poseHelm for view- or world-relative motion.');
   }
   if (_isCameraState(cam)) helm.home(cameraToPose(_pose, cam));
   const player = {
@@ -1294,8 +1295,14 @@ function poseHelm(host, opts) {
  * poseTrack(host, opts) is a core PoseTrack whose activation hooks add and
  * remove its player. cameraTrack(host, cam, opts) is a core CameraTrack whose
  * player evaluates straight into the camera state `cam` — the state is the
- * keyframe shape, so track.eval(cam) is the write — and once more on
- * deactivate so the camera rests on the path; add() with no argument
+ * keyframe shape, so track.eval(cam) is the write — while the track plays, and
+ * once more on deactivate so the camera rests on the path. That bound is the
+ * point: a stopped track's camera belongs to whoever else drives it — the
+ * reader's orbit, the figure's own camera code — so a consumer that renders
+ * from the state derives it instead, one evaluation per frame after the tick
+ * that advances the transport, which carries a seek, a dragged keyframe and a
+ * capture into the state as well and repeats the player's write harmlessly
+ * while the track plays. add() with no argument
  * captures `cam`, add({ camera }) any camera-state object. { handles } on
  * either decorates the track with TrackHandles: one VIEW handle per
  * draggable keyframe field (pos / eye / center), an optional rot DIAL per
@@ -1401,7 +1408,17 @@ function poseTrack(host, opts) {
 }
 
 /**
- * A core CameraTrack evaluating into the camera state `cam` while it plays.
+ * A core CameraTrack evaluating into the camera state `cam` while it plays, and
+ * once when it stops, so the camera rests on the path.
+ *
+ * The write is bounded by playback on purpose: while a track is stopped the
+ * camera it names belongs to whoever else drives it — the reader's orbit, the
+ * figure's own camera code — and a factory writing every frame would fight
+ * them. A consumer that renders *from* the state therefore derives it: evaluate
+ * the track once per frame, after the tick that advances the transport. A seek,
+ * a dragged keyframe and a capture reach the state that way too, and the
+ * evaluation repeats the player's own write harmlessly while the track plays.
+ *
  * @param {object} host
  * @param {object} cam   A camera state ({ eye, center, up, fov, halfHeight, near, far }).
  * @param {{ handles?:boolean|object }} [opts]
@@ -2491,7 +2508,7 @@ function raster(draw, w, h, opts) {
  * class — a CSS class beside the layer's own 'host-label', frame — a
  * transient label that lives for the frame it was set in: a gizmo re-sets
  * it every draw and tick() removes it once a frame passes without. A label
- * whose screen depth leaves [0, 1] or whose anchor leaves the canvas is
+ * whose window depth leaves [0, 1] or whose anchor leaves the canvas is
  * hidden, not clamped. Elements are reused by id; tick() writes transforms
  * only, text when the string changed.
  */
@@ -2684,7 +2701,7 @@ function createLabels(host, opts) {
  * what is still draining, so do home() and enabled = false. The default is
  * 0.2 s; 0 makes the orbit exact.
  *
- * Screen y runs down; which world direction that is depends on the
+ * Canvas y runs down; which world direction that is depends on the
  * projection installed in the view bag: a y-up projection (GL's, tree's
  * default) maps a downward drag to the eye's −up, a y-flipped one (p5's,
  * mat4Proj[5] < 0) to +up. The orbit reads that sign off the bag each
@@ -2799,7 +2816,7 @@ function createOrbit(host, cam, opts) {
       let moved = false;
       let az = 0, el = 0, px = 0, py = 0, ld = 0;   // this frame's step
       const view = host.view;
-      const ys = view.mat4Proj[5] < 0 ? -1 : 1;   // screen-down is the eye's −up under a y-up projection, +up under p5's flip
+      const ys = view.mat4Proj[5] < 0 ? -1 : 1;   // canvas-down is the eye's −up under a y-up projection, +up under p5's flip
       if (a !== null && b === null) {
         const t = tracked.get(a.id);
         if (t) {
@@ -2851,6 +2868,204 @@ function createOrbit(host, cam, opts) {
   return host.register(orbit);
 }
 
+/**
+ * @file HDR — Radiance (.hdr) RGBE bytes decoded to the pixels a bridge uploads.
+ * @module host/hdr
+ * @license AGPL-3.0-only
+ *
+ * A floating-point texture needs radiance, and no image decoder in the browser
+ * gives it any: `loadImage` hands back an `ImageBitmap` of 8-bit codes, clamped
+ * at 1.0, so a tone-mapping pass would have nothing left to compress. Radiance's
+ * RGBE is the one high-range format a few dozen lines decode.
+ *
+ * ```
+ * const hdr = decodeRGBE(bytes)          // { data, width, height } — radiance
+ * const tex = texture(gl, hdr)          // the bridge's upload, RGBA32F
+ * ```
+
+ *
+ * A pixel is three 8-bit mantissas and a shared exponent — `v · 2^(e − 136)` —
+ * the format of Greg Ward's RADIANCE (Ward, *Real Pixels*, Graphics Gems II,
+ * 1991). The reader follows `rgbe.c`'s structure and three.js's `HDRLoader`
+ * (itself adapted from Bruce Walter's code), with the exact scale above rather
+ * than that implementation's `v · 2^(e − 128) / 255`, and no `+ 0.5` — the
+ * offset `rgbe.c`'s floating read carries, which lifts every pixel by half a
+ * mantissa step (0.04 % of the mean on a Poly Haven HDRI) and which no file
+ * declares. Rows keep the order the file states and are never flipped here: GL's
+ * bottom-up space is the upload's concern (see texture.js).
+ *
+ * `loadHDR` — the fetch and the GL row order — is `webgl.tree`'s, and it
+ * re-exports these two; a reader with no bridge to feed uses them directly. Rows
+ * come back in the file's own order unless `rowOrder: 'BOTTOM_UP'` asks for GL's.
+ * The decoder is trusted by round-tripping through the encoder and by agreeing
+ * with three.js's `HDRLoader` and ImageMagick on real Radiance files.
+ */
+
+
+// Radiance's own threshold: at or below it a float holds no light, so a pixel
+// that low is written as four zero bytes and read back as black.
+const _MIN_RADIANCE = 1e-32;
+// 16 Mpixel of RGBA32F is 256 MB of output: past this the tab is gone before
+// anything on screen says why, so the refusal comes from here.
+const _DEFAULT_MAX_PIXELS = 16 * 1024 * 1024;
+
+const _fv = new DataView(new ArrayBuffer(4));
+
+// The shared exponent as a float32: the bit pattern of 2^(e − 136) — mantissa
+// zero, biased exponent — read straight out of the view, no Math.pow per pixel.
+// 256 entries, made once at load, indexed by the exponent byte a pixel carries.
+const _SCALES = new Float32Array(256);
+for (let e = 0; e < 256; e++) {
+  _fv.setUint32(0, e < 10 ? 0 : (e - 9) << 23, true);   // e < 10 underflows to zero
+  _SCALES[e] = _fv.getFloat32(0, true);
+}
+
+/**
+ * Encode three linear radiance samples and a shared exponent to RGBE bytes.
+ * The inverse of a pixel in `decodeRGBE`: the largest component becomes a byte
+ * level between 128 and 255 — `level = round(v / 2^(e − 136))` with e the
+ * exponent that carries it — so all eight bits are spent and the components
+ * keep their ratio. The level is an integer: 0.0 comes back exactly, and
+ * everything else to within half a level, the 1/512 an 8-bit mantissa costs at
+ * worst.
+ * @param {number} r  Red, ≥ 0.
+ * @param {number} g  Green.
+ * @param {number} b  Blue.
+ * @param {Uint8Array} [out]  Four bytes to write; a new one when absent.
+ * @returns {Uint8Array} out
+ */
+function encodeRGBE(r, g, b, out) {
+  const o = out || new Uint8Array(4);
+  const max = Math.max(r, g, b);
+  if (!(max >= _MIN_RADIANCE)) { o[0] = o[1] = o[2] = o[3] = 0; return o; }
+  // The exponent whose scale carries max as a byte level of 128 to 255 — the
+  // finest step the format has for this magnitude. The float32's own exponent
+  // sets the base, one scale step below the level 255 needs, and the search
+  // steps up until max fits a byte. `_SCALES` is the decoder's own table, so
+  // the two cannot drift apart.
+  _fv.setFloat32(0, max, true);
+  let e = Math.min(255, Math.max(1, ((_fv.getUint32(0, true) >>> 23) & 0xff) - 127 + 128));
+  while (e < 255 && max / _SCALES[e] > 255) e++;
+  o[0] = Math.min(255, Math.round(r / _SCALES[e]));
+  o[1] = Math.min(255, Math.round(g / _SCALES[e]));
+  o[2] = Math.min(255, Math.round(b / _SCALES[e]));
+  o[3] = e;
+  return o;
+}
+
+// The header: a magic line, keyed lines and comments, a blank line, then the
+// resolution string (`-Y 512 +X 1024`). Anything before the resolution is
+// skipped — XMP and other writers put blocks there — so the walk stops at the
+// first line that states a dimension.
+function _headerAt(data) {
+  let pos = 0, height = 0, width = 0, flipRows = false;
+  const n = data.length;
+  while (pos < n) {
+    let end = pos;
+    while (end < n && data[end] !== 10) end++;
+    const line = String.fromCharCode.apply(null, data.subarray(pos, Math.min(end, pos + 400)));
+    pos = end + 1;
+    if (/^#\?/.test(line)) continue;
+    const res = /^\s*([-+])([XY])\s+(\d+)\s+([-+])([XY])\s+(\d+)\s*$/.exec(line);
+    if (res) {
+      const first = res[2].toUpperCase(), second = res[5].toUpperCase();
+      if (first === 'Y' && second === 'X') {
+        height = +res[3]; width = +res[6];
+        flipRows = res[1] === '+';           // +Y: row 0 at the bottom
+      } else if (first === 'X' && second === 'Y') {
+        width = +res[3]; height = +res[6];
+        flipRows = res[1] === '+';           // +X: column 0 on the right
+      } else {
+        throw new Error('[host] hdr: the resolution names ' + first + ' then ' + second + '; -Y h +X w expected.');
+      }
+      return { width, height, flipRows, pos };
+    }
+    if (line === '') continue;                    // a writer may separate the keys from the resolution
+  }
+  throw new Error('[host] hdr: no resolution line — the file is not a Radiance image.');
+}
+
+// One scanline of RGBE bytes into `row`: either the new-style RLE (4 planes,
+// runs of 128 bytes or fewer) or the flat tuples an old writer leaves.
+function _scanline(data, pos, row, w, off, rowBytes) {
+  const end = data.length;
+  if (w >= 8 && w < 32768 && pos + 3 < end && data[pos] === 2 && data[pos + 1] === 2 && (data[pos + 2] & 0x80) === 0) {
+    const scanline = (data[pos + 2] << 8) | data[pos + 3];
+    if (scanline !== w) throw new Error('[host] hdr: scanline width ' + scanline + ', image width ' + w + '.');
+    pos += 4;
+    for (let c = 0; c < 4; c++) {
+      let x = 0;
+      while (x < w) {
+        if (pos >= end) throw new Error('[host] hdr: the file ends inside scanline ' + (off / rowBytes) + '.');
+        const count = data[pos++];
+        if (count > 128) {                       // a run of one byte
+          if (pos >= end) throw new Error('[host] hdr: the file ends inside a run.');
+          const v = data[pos++];
+          for (let i = 0; i < count - 128; i++) row[(x + i) * 4 + c] = v;
+          x += count - 128;
+        } else {                                 // a literal run
+          if (count === 0 || pos + count > end) throw new Error('[host] hdr: bad run length in scanline ' + (off / rowBytes) + '.');
+          for (let i = 0; i < count; i++) row[(x + i) * 4 + c] = data[pos + i];
+          pos += count;
+          x += count;
+        }
+        if (x > w) throw new Error('[host] hdr: a run overruns scanline ' + (off / rowBytes) + '.');
+      }
+    }
+    return pos;
+  }
+  // flat: 4 bytes per pixel, in file order (the scanline is one plane-less array)
+  if (pos + w * 4 > end) throw new Error('[host] hdr: the file ends inside scanline ' + (off / rowBytes) + '.');
+  for (let i = 0; i < w * 4; i++) row[i] = data[pos + i];
+  return pos + w * 4;
+}
+
+/**
+ * Decode Radiance RGBE bytes into the pixel source `texture` takes.
+ * @details Every pixel becomes four float channels — R, G, B and 1 — and the
+ * rows come back in the order the file states, top-down for the `-Y` every
+ * writer emits. `loadHDR` is the one that turns them over for GL; a caller
+ * here that wants the same passes `rowOrder: 'BOTTOM_UP'`. The decoder holds no
+ * state, allocates its output once, and needs no DOM, so it runs under
+ * node:test as well as in the browser.
+ * @param {ArrayBuffer|Uint8Array} bytes  The whole file.
+ * @param {{ rowOrder?:string, maxPixels?:number }} [opts]
+ *        rowOrder: `FILE` (default) or `BOTTOM_UP` — the latter for GL's
+ *        texture space, row 0 at v = 0.
+ *        maxPixels: refuse past this many pixels (default 16 MPixel).
+ * @returns {{ data:Float32Array, width:number, height:number }} Radiance in
+ *          linear light: what `texture` uploads as RGBA32F, and the range a
+ *          tone operator compresses.
+ */
+function decodeRGBE(bytes, opts) {
+  const o = opts || {};
+  const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const head = _headerAt(data);
+  const { width: w, height: h } = head;
+  if (!(w > 0) || !(h > 0)) throw new Error('[host] hdr: the resolution states ' + w + ' × ' + h + '.');
+  const max = o.maxPixels || _DEFAULT_MAX_PIXELS;
+  if (w * h > max) {
+    throw new Error('[host] hdr: ' + w + ' × ' + h + ' is past maxPixels (' + max +
+      '); pass a bigger one, or decode at a lower resolution.');
+  }
+  const flip = o.rowOrder === 'BOTTOM_UP';
+  const out = new Float32Array(w * h * 4);
+  const row = new Uint8Array(w * 4);
+  let pos = head.pos;
+  for (let y = 0; y < h; y++) {
+    pos = _scanline(data, pos, row, w, y * w * 4, w * 4);
+    const at = (flip ? h - 1 - y : y) * w * 4;
+    for (let x = 0; x < w; x++) {
+      const p = x * 4, s = _SCALES[row[p + 3]], d = at + p;
+      out[d] = row[p] * s;
+      out[d + 1] = row[p + 1] * s;
+      out[d + 2] = row[p + 2] * s;
+      out[d + 3] = 1;
+    }
+  }
+  return { data: out, width: w, height: h };
+}
+
 /**
  * @file The host context — one per canvas: pointer, view bag, players, loop, observer.
  * @module host
@@ -3022,5 +3237,5 @@ function createHost(canvas, opts) {
   return host;
 }
 
-export { GAMEPAD_MAP, HID_FILTERS, Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createGamepad, createHid, createHost, createLabels, createLoop, createOrbit, createPlayers, createPointer, createVideo, createView, decodeSpaceNavigator, helmBasis, isConstraint, loadImage, loadMesh, loadModel, measureCanvas, observeCanvas, poseHelm, poseTrack, raster, validConstraint };
+export { GAMEPAD_MAP, HID_FILTERS, Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createGamepad, createHid, createHost, createLabels, createLoop, createOrbit, createPlayers, createPointer, createVideo, createView, decodeRGBE, decodeSpaceNavigator, encodeRGBE, helmBasis, isConstraint, loadImage, loadMesh, loadModel, measureCanvas, observeCanvas, poseHelm, poseTrack, raster, validConstraint };
 //# sourceMappingURL=index.js.map