@nakednous/host 0.0.6 → 0.0.8

package/README.md

@@ -79,7 +79,7 @@ dependency first and an options object last, and registers with the context so
 | `host.handle(opts)` | `Handle` — a draggable core constraint (`SPHERE` · `PLANE` · `AXIS` · `DIAL` · `VIEW`, or a contract object); `update()`, `value(out, opts)`, snap, hover, cancel, `from` |
 | `host.router(handles, opts)` | `PointerRouter` — one shared pick over overlapping handles, nearest proxy wins; shared hover |
 | `host.cameraHelm(cam, opts)` · `host.poseHelm(opts)` | a core `PoseHelm` on the players: body-fly a camera state, or integrate into a pose in `WORLD` · `EYE` · `SELF` · a mat4 and `bind()` a target |
-| `host.poseTrack(opts)` · `host.cameraTrack(cam, opts)` | core tracks ticked while they play; `{ handles }` builds `TrackHandles`, one handle per keyframe |
+| `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 |
 | `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'` |

package/dist/index.js

@@ -1,4 +1,4 @@
-import { WEBGL, cameraView, cameraProj, mat4Mul, mat4Invert, PLANE, createConstraint, WORLD, AXIS, DIAL, POINT, mapDirection, pixelRatio, rayHitSphere, unproject, SPHERE, dirFromAzEl, DIRECTION, mapLocation, MATRIX, PoseHelm, cameraToPose, EYE, SELF, qToMat4, cameraEye, cameraFromPose, CameraTrack, PoseTrack, qFromAxisAngle, mat4ToTransform, meshBounds, meshFlatten, meshNormals, meshGroups, SCREEN, cameraCopy, createCamera, coastAlive, coastStep, cameraOrbit, cameraPan, cameraDolly } from '@nakednous/tree';
+import { WEBGL, cameraView, cameraProj, mat4Mul, mat4Invert, PLANE, createConstraint, WORLD, AXIS, DIAL, POINT, mapDirection, pixelRatio, rayHitSphere, unproject, SPHERE, dirFromAzEl, DIRECTION, mapLocation, MATRIX, PoseHelm, cameraToPose, EYE, SELF, qToMat4, cameraEye, cameraFromPose, CameraTrack, PoseTrack, qFromAxisAngle, NDC, mat4ToTransform, meshBounds, meshFlatten, meshNormals, meshGroups, SCREEN, cameraCopy, createCamera, coastAlive, coastStep, cameraOrbit, cameraPan, cameraDolly } from '@nakednous/tree';
 
 /**
  * @file The view bag — the matrices every pick, solve, label and orbit reads.
@@ -1300,11 +1300,69 @@ function poseHelm(host, opts) {
  * either decorates the track with TrackHandles: one VIEW handle per
  * draggable keyframe field (pos / eye / center), an optional rot DIAL per
  * keyframe about a declared axis, all on one router.
+ *
+ * add(depth) — the transport panel's + button, which passes its depth slider
+ * (ui's contract) — authors a keyframe where the camera is looking: on a pose
+ * track the pose lands at the centre of the installed camera's frustum at
+ * that depth, aimed along the camera's own eye frame; on a camera track the
+ * camera state is captured, the depth having nothing to place. A panel whose
+ * depth row is hidden passes no depth, which reads the panel's default, 0.5.
+ * The frame is the host's view bag — the matrices the last setCamera
+ * installed — so the placement is the same on every bridge and needs no
+ * renderer here. remove() is the panel's −: no argument retracts the last
+ * keyframe, one per call, an index staying the core track's own remove.
  */
 
 
+// ── Placement — the + button's depth ───────────────────────────────────────
+//
+// The transport panel hands add() a depth in [0, 1] and expects a keyframe in
+// front of the camera. Writer-free placement: unproject the frustum's centre
+// through the view bag's P · V inverse and aim the pose along the bag's eye
+// frame (E = V⁻¹, its columns right / up / back). The depth is NDC-linear, as
+// the p5 transport's was — 0 the near plane's centre, 1 the far plane's — so
+// every bridge's own ndcZMin maps it without the caller knowing the API.
+
+const _at  = [0, 0, 0];   // the unprojected frustum centre
+const _dir = [0, 0, 0];   // the camera's forward
+const _up  = [0, 0, 0];   // the camera's up
+
+/**
+ * Append a pose at the centre of the installed camera's frustum, `depth` of
+ * the way from the near plane to the far one.
+ *
+ * @param {object} host
+ * @param {function} add    The track's core add, already bound.
+ * @param {number} [depth]  NDC-linear depth in [0, 1]; clamped, absent or NaN
+ *                          reads the panel's own default, 0.5.
+ * @returns {boolean} false when no camera is installed (a stale view bag).
+ */
+function _addInFront(host, add, depth) {
+  const view = host.view;
+  if (!view || view.stale) return false;
+  const d    = Number.isFinite(depth) ? (depth < 0 ? 0 : depth > 1 ? 1 : depth) : 0.5;
+  const ndcZ = view.ndcZMin + d * (1 - view.ndcZMin);
+  mapLocation(_at, 0, 0, ndcZ, NDC, WORLD, view, view.vp, view.ndcZMin);
+  const e = view.mat4Eye;                        // columns: right · up · back · eye
+  _dir[0] = -e[8];  _dir[1] = -e[9];  _dir[2] = -e[10];
+  _up[0]  =  e[4];  _up[1]  =  e[5];  _up[2]  =  e[6];
+  add({ pos: [_at[0], _at[1], _at[2]], rot: { dir: _dir, up: _up } }, { deduplicate: false });
+  return true;
+}
+
 // ── Players ────────────────────────────────────────────────────────────────
 
+// remove(): the panel's −, retracting the last authored keyframe — one per
+// click, either kind of track. An index stays the core track's own remove, so
+// a caller editing by index is unaffected; an empty track removes nothing.
+function _wireRemove(track) {
+  const coreRemove = track.remove.bind(track);
+  track.remove = function (index) {
+    return coreRemove(index == null ? track.keyframes.length - 1 : index);
+  };
+  return track;
+}
+
 function _wirePoseTrack(host, track) {
   let player = null;
   track._onActivate = () => {
@@ -1324,8 +1382,22 @@ function poseTrack(host, opts) {
   const o = opts || {};
   const track = new PoseTrack();
   _wirePoseTrack(host, track);
+
+  // add(depth): the transport's + (see the module header). A spec, or an array
+  // of specs, is the core track's own; no argument — the panel with its depth
+  // row hidden — places at the panel's default depth, 0.5.
+  const coreAdd = track.add.bind(track);
+  let warned = false;
+  track.add = function (spec, addOpts) {
+    if (spec != null && typeof spec !== 'number') return coreAdd(spec, addOpts);
+    if (!_addInFront(host, coreAdd, spec) && !warned) {
+      warned = true;
+      console.warn('[host] poseTrack: add(depth) places a pose against the installed camera, and the view bag is stale — no keyframe added. Call the bridge\'s setCamera first.');
+    }
+  };
+
   if (o.handles) track.handles = new TrackHandles(host, track, o.handles, false);
-  return track;
+  return _wireRemove(track);
 }
 
 /**
@@ -1344,7 +1416,9 @@ function cameraTrack(host, cam, opts) {
 
   const coreAdd = track.add.bind(track);
   track.add = function (spec, addOpts) {
-    if (spec == null) {
+    // No spec, or the transport panel's depth: a camera keyframe *is* the
+    // camera, so there is nothing a placement depth could move — capture.
+    if (spec == null || typeof spec === 'number') {
       if (!state) return;
       spec = state;
     } else if (Array.isArray(spec)) {
@@ -1373,7 +1447,7 @@ function cameraTrack(host, cam, opts) {
   track._onDeactivate = () => { host.players.remove(player); apply(); };
 
   if (o.handles) track.handles = new TrackHandles(host, track, o.handles, true);
-  return track;
+  return _wireRemove(track);
 }
 
 // ── TrackHandles ───────────────────────────────────────────────────────────