@displayxr/inline3d 1.43.1 → 1.45.0

package/js/camera/pair-cursor.js

@@ -15,7 +15,11 @@
 //    disparity is past the draw threshold (-0.005 baselines, and >= 0.5 px; cursorShouldDraw), the
 //    OS cursor hidden exactly then;
 //  - the same filter (fast rise, slow sink) and the same arrow (CURSOR_ARROW, tip = hotspot, the
-//    OS arrow's 19 CSS px).
+//    OS arrow's 19 CSS px);
+//  - the same crosstalk softening (Amendment 2 §B.7, cursorSoften): a lifted arrow is blurred by
+//    0.1 × its ghost offset (here: its disparity, the two halves being the two views) and faded
+//    toward 0.5, both zero on the glass. Rasterised into the buffer from the core's 13-tap kernel
+//    (cursorSoftArrowRaster) — inside the woven pixels, never a CSS filter or CSS opacity.
 // What is specific to a pair: it has no 3D views, so it works in tile PIXEL disparity — OUTPUT
 // pixels of one eye of the woven buffer, + = crossed (in front of the glass), the sign the rest of
 // camera/ uses — and converts to the core's eye-baseline units through the panel's pixel pitch:
@@ -25,12 +29,18 @@
 
 import {
   CursorPointer,
+  CursorShapeSelector,
   cursorArrowFootprint,
-  cursorArrowInset,
+  cursorShapePolys,
+  cursorShapeRaster,
+  cursorSoftenPixels,
+  drawCursorShape2D,
   cursorDefaultHeight,
   cursorFilterStep,
   cursorShouldDraw,
+  cursorSoften,
   cursorTarget,
+  resolveCursorSoften,
   CURSOR_ARROW,
   CURSOR_ARROW_CSS_PX,
   CURSOR_DEFAULT_TUNING,
@@ -211,44 +221,114 @@ export function pairCursorTarget(contentPx, pxPerBaseline, tuning = CURSOR_DEFAU
   return -cursorTarget(tuning, true, -contentPx / pxPerBaseline) * pxPerBaseline || 0;
 }
 
-/** The arrow's fill, inset by one output px (at least 1/19 of its height), cached per size. */
-const _fillBySize = new Map();
-function arrowFill(sizePx) {
+/** The shape's outline + fill inset by one output px (at least 1/19 of its height), cached per size. */
+const _polysBySize = new Map();
+function shapePolys(name, sizePx) {
   const d = sizePx > 0 ? Math.max(1 / 19, 1 / sizePx) : 1 / 19;
-  const key = Math.round(d * 1e4);
-  let f = _fillBySize.get(key);
+  const key = `${name}:${Math.round(d * 1e4)}`;
+  let f = _polysBySize.get(key);
   if (!f) {
-    if (_fillBySize.size > 32) _fillBySize.clear();
-    _fillBySize.set(key, (f = cursorArrowInset(d)));
+    if (_polysBySize.size > 64) _polysBySize.clear();
+    _polysBySize.set(key, (f = cursorShapePolys(name, d)));
   }
   return f;
 }
 
 /**
- * Draw the arrow into both halves of a woven buffer: the left eye's copy `disparityPx / 2` right of
- * the pointer, the right eye's as far left (crossed = in front). The shared arrow: its dark outline
- * polygon, then the white fill inset by a px; the tip on the hotspot. Each copy is clipped to its
- * own half, so an arrow at the edge never bleeds into the other eye.
- * @param {number} sizePx  arrow height in output px
+ * Draw the cursor into both halves of a woven buffer: the left eye's copy `disparityPx / 2` right of
+ * the pointer, the right eye's as far left (crossed = in front). The shared sprite (the arrow by
+ * default, or `shape`): its dark outline, then the white fill inset by a px; the hotspot on the
+ * pointer. Each copy is clipped to its own half, so a sprite at the edge never bleeds into the
+ * other eye.
+ * @param {number} sizePx  sprite height (one arrow height) in output px
+ * @param {string} [shape='arrow']  a CURSOR_SHAPES name
  */
-export function drawPairArrow(g, outW, outH, u, v, disparityPx, sizePx) {
+export function drawPairArrow(g, outW, outH, u, v, disparityPx, sizePx, shape = 'arrow') {
   const cy = v * outH;
-  const fill = arrowFill(sizePx);
+  const polys = shapePolys(shape, sizePx);
   for (const eye of [0, 1]) {
     const cx = eye * outW + u * outW + (eye === 0 ? disparityPx / 2 : -disparityPx / 2);
     g.save();
     g.beginPath();
     g.rect(eye * outW, 0, outW, outH);
     g.clip();
-    for (const [poly, style] of [[CURSOR_ARROW, '#000'], [fill, '#fff']]) {
-      g.beginPath();
-      poly.forEach(([x, y], k) => (k ? g.lineTo : g.moveTo).call(g, cx + x * sizePx, cy + y * sizePx));
-      g.closePath();
-      g.fillStyle = style;
-      g.fill();
+    drawCursorShape2D(g, shape, cx, cy, sizePx, polys);
+    g.restore();
+  }
+}
+
+// A scratch 2D canvas for the softened arrow (drawImage blends and honours the clip; putImageData
+// would do neither). Null where no canvas can be made — then the crisp arrow is drawn.
+let _scratch = null;
+function scratchCanvas(w, h) {
+  if (!_scratch || (typeof OffscreenCanvas === 'function' && !(_scratch instanceof OffscreenCanvas))) {
+    try {
+      if (typeof OffscreenCanvas === 'function') _scratch = new OffscreenCanvas(1, 1);
+      else if (globalThis.document && document.createElement) _scratch = document.createElement('canvas');
+    } catch {
+      _scratch = null;
     }
+  }
+  if (!_scratch || typeof _scratch.getContext !== 'function') return null;
+  if (_scratch.width < w) _scratch.width = w;
+  if (_scratch.height < h) _scratch.height = h;
+  return _scratch.getContext('2d');
+}
+
+/**
+ * The SOFTENED arrow into both halves (ADR-046 Amendment 2 §B.7): as drawPairArrow — same
+ * placement, same tip, same clip to each half — but rasterised from the core's 13-tap blur of the
+ * arrow with `radius` (arrow heights) and `alpha` (opacity). Returns false (nothing drawn) when no
+ * scratch canvas is available, so the caller can fall back to the crisp arrow.
+ */
+export function drawPairArrowSoft(g, outW, outH, u, v, disparityPx, sizePx, radius, alpha, shape = 'arrow') {
+  const cy = v * outH;
+  const polys = shapePolys(shape, sizePx);
+  const rasters = [0, 1].map((eye) => {
+    const cx = eye * outW + u * outW + (eye === 0 ? disparityPx / 2 : -disparityPx / 2);
+    return cursorShapeRaster(shape, cx, cy, sizePx, radius, alpha, [1, 1, 1, 1], [0, 0, 0, 1], polys);
+  });
+  const sg = scratchCanvas(Math.max(rasters[0].width, rasters[1].width), Math.max(rasters[0].height, rasters[1].height));
+  if (!sg || typeof sg.putImageData !== 'function' || typeof ImageData !== 'function') return false;
+  for (const eye of [0, 1]) {
+    const r = rasters[eye];
+    sg.putImageData(new ImageData(r.data, r.width, r.height), 0, 0);
+    g.save();
+    g.beginPath();
+    g.rect(eye * outW, 0, outW, outH);
+    g.clip();
+    g.drawImage(sg.canvas, 0, 0, r.width, r.height, r.x0, r.y0, r.width, r.height);
+    g.restore();
+  }
+  return true;
+}
+
+/**
+ * A url() image cursor into both halves: at its CSS size (one sprite unit = `sizePx` output px per
+ * 19 CSS px), its hotspot on the pointer, softened in the PIXELS (cursorSoftenPixels: `radiusPx`
+ * blur, `alpha` opacity) — never a CSS filter or opacity. Returns false when no scratch canvas.
+ */
+export function drawPairImage(g, outW, outH, u, v, disparityPx, sizePx, sprite, radiusPx, alpha) {
+  const k = sizePx / 19; // output px per CSS px
+  const w = Math.max(1, Math.round(sprite.width * k)), h = Math.max(1, Math.round(sprite.height * k));
+  const sg = scratchCanvas(w + 2 * (Math.ceil(radiusPx) + 2), h + 2 * (Math.ceil(radiusPx) + 2));
+  if (!sg || typeof sg.getImageData !== 'function' || typeof ImageData !== 'function') return false;
+  sg.clearRect(0, 0, sg.canvas.width, sg.canvas.height);
+  sg.drawImage(sprite.entry.image, 0, 0, w, h);
+  const soft = cursorSoftenPixels(sg.getImageData(0, 0, w, h).data, w, h, radiusPx, alpha);
+  sg.clearRect(0, 0, sg.canvas.width, sg.canvas.height);
+  sg.putImageData(new ImageData(soft.data, soft.width, soft.height), 0, 0);
+  const cy = v * outH - sprite.hotspot[1] * k - soft.pad;
+  for (const eye of [0, 1]) {
+    const cx = eye * outW + u * outW + (eye === 0 ? disparityPx / 2 : -disparityPx / 2) - sprite.hotspot[0] * k - soft.pad;
+    g.save();
+    g.beginPath();
+    g.rect(eye * outW, 0, outW, outH);
+    g.clip();
+    g.drawImage(sg.canvas, 0, 0, soft.width, soft.height, Math.round(cx), Math.round(cy), soft.width, soft.height);
     g.restore();
   }
+  return true;
 }
 
 /**
@@ -258,8 +338,12 @@ export function drawPairArrow(g, outW, outH, u, v, disparityPx, sizePx) {
  */
 export class PairCursor {
   /** @param {HTMLElement} canvas  the tile — the pointer counts over its box */
-  constructor(canvas, { height, pointerScope = 'window' } = {}) {
+  constructor(canvas, { height, pointerScope = 'window', soften, shape = 'auto', shapeFor = null } = {}) {
     this.pointer = new CursorPointer(canvas, { scope: pointerScope });
+    /** Which sprite (CSS mirror / fixed / shapeFor); `.current` = the one drawn last. */
+    this.shapes = new CursorShapeSelector(this.pointer, { shape, shapeFor });
+    /** Crosstalk softening parameters (resolveCursorSoften). */
+    this.soften = resolveCursorSoften(soften, '@displayxr/inline3d pair cursor');
     // A fraction of the tile height when given; by default the OS arrow's size (CSS px → tile).
     this.height = height > 0 ? height : null;
     this.filter = {};
@@ -271,7 +355,7 @@ export class PairCursor {
     this.metersPerCssPx = null;
     /** The eye separation (metres) the baseline units convert with: displayMetrics' (a default today). */
     this.eyeSeparationM = DISPLAY_METRICS_DEFAULTS.eyeSeparationM;
-    /** The last frame's placement, for diagnostics: `{ contentPx, targetPx, disparityPx, filteredPx, drawn, pxPerBaseline }` (output px, + = in front) or null. */
+    /** The last frame's placement, for diagnostics: `{ contentPx, targetPx, disparityPx, filteredPx, drawn, pxPerBaseline, soften }` (output px, + = in front) or null. */
     this.last = null;
   }
 
@@ -308,9 +392,27 @@ export class PairCursor {
     const d = cursorFilterStep(this.filter, CURSOR_DEFAULT_TUNING, target, nowSec);
     const drawn = cursorShouldDraw(d, pxPerBaseline);
     const disparity = -d * pxPerBaseline; // output px, + = in front
-    if (drawn) drawPairArrow(g, geo.outW, geo.outH, u, v, disparity, hf * geo.outH);
+    let soften = null;
+    let shape = null;
+    if (drawn) {
+      // Softening in PANEL px: one output px of an eye spans (tile CSS width × dpr) / outW of them.
+      // The ghost offset of a pair IS its disparity (the two halves are the two views).
+      const sizePx = hf * geo.outH;
+      const dpr = globalThis.devicePixelRatio > 0 ? globalThis.devicePixelRatio : 1;
+      const k = r && r.width > 0 ? (r.width * dpr) / geo.outW : 1;
+      const spritePx = r && r.height > 0 ? hf * r.height * dpr : sizePx;
+      const s = cursorSoften(d, disparity * k, spritePx, this.soften);
+      const sprite = this.shapes.pick({ u, v, point: null }, nowSec * 1000);
+      shape = this.shapes.current;
+      soften = { blurPx: s.blurPx, alpha: s.alpha, ghostPx: Math.abs(disparity * k), spritePx, radius: spritePx > 0 ? s.blurPx / spritePx : 0, soft: s.blurPx > 0 || s.alpha < 1 };
+      if (sprite.kind === 'image') {
+        drawPairImage(g, geo.outW, geo.outH, u, v, disparity, sizePx, sprite, soften.soft ? soften.radius * sizePx : 0, soften.soft ? s.alpha : 1);
+      } else if (sprite.kind === 'shape' && (!soften.soft || !drawPairArrowSoft(g, geo.outW, geo.outH, u, v, disparity, sizePx, soften.radius, s.alpha, shape))) {
+        drawPairArrow(g, geo.outW, geo.outH, u, v, disparity, sizePx, shape);
+      } // 'none': the page hides its cursor; draw nothing (the OS cursor stays hidden)
+    }
     this.pointer.hideCss(drawn); // the OS arrow IS the cursor on the plane
-    this.last = { contentPx: this._content, targetPx: -target * pxPerBaseline || 0, disparityPx: drawn ? disparity : 0, filteredPx: disparity || 0, drawn, pxPerBaseline };
+    this.last = { contentPx: this._content, targetPx: -target * pxPerBaseline || 0, disparityPx: drawn ? disparity : 0, filteredPx: disparity || 0, drawn, pxPerBaseline, soften, shape };
     return this.last;
   }
 
@@ -345,5 +447,6 @@ export class PairCursor {
 
   dispose() {
     this.pointer.dispose();
+    this.shapes.dispose();
   }
 }

package/js/inline3d-cursor-bvh.js

@@ -0,0 +1,147 @@
+// inline3d-cursor-bvh.js — the depth cursor's pick, BVH-accelerated, for three.js scenes.
+//
+// Loaded ONLY when a page opts into `cursor: 'depth'` (./model imports it dynamically on opt-in;
+// ADR-046 §0: zero cost, no download otherwise). It brings the vendored MeshBVH slice of
+// three-mesh-bvh (js/vendor/three-mesh-bvh.js, MIT), which imports the page's own `three`.
+//
+// Same answer as three's Raycaster.intersectObjects(targets, true)[0] — the nearest hit, the same
+// layer test, the same traversal (an object's raycast returning false stops its subtree) — but each
+// plain Mesh is tested against a bounds tree instead of every triangle. Nothing on the page is
+// touched: no prototype patching, no `geometry.boundsTree`, no index reordering (`indirect: true`);
+// the trees live in a WeakMap keyed by geometry.
+//
+//  - Built lazily, the first time a ray reaches a mesh's bounding sphere, within a small time
+//    budget a frame (one big mesh may exceed it once; it cannot be split). A mesh not built yet is
+//    raycast the plain way meanwhile, so the answer never waits for a build.
+//  - CPU-animated vertices (the position attribute's version moves): the tree is refitted.
+//    A replaced attribute, a changed vertex count or index: rebuilt.
+//  - Skinned, morphing, instanced or batched meshes, a partial drawRange, and anything that is not
+//    a Mesh (points, lines, sprites, a splat's own raycast): three's own raycast, as before —
+//    its answer follows the deformation; a static tree would not.
+
+import { MeshBVH } from './vendor/three-mesh-bvh.js';
+
+/** Build time allowed per ~frame (ms) before further builds wait for the next one. */
+const BUILD_BUDGET_MS = 4;
+const FRAME_MS = 16;
+
+/**
+ * A hit test for ./three's DepthCursor over `targets` (searched recursively): the nearest hit along
+ * a WORLD ray, as a world point, or null.
+ * @param {object} THREE  the page's three.js namespace.
+ * @param {object[]} targets  Object3Ds that count as content.
+ * @returns {((origin: number[], direction: number[]) => number[]|null) & {info: () => object}}
+ */
+export function bvhHitTest(THREE, targets, { now = () => (globalThis.performance ? globalThis.performance.now() : Date.now()) } = {}) {
+  const raycaster = new THREE.Raycaster();
+  raycaster.firstHitOnly = true; // MeshBVH.raycastObject3D: the nearest hit only
+  const o = new THREE.Vector3();
+  const d = new THREE.Vector3();
+  const sphere = new THREE.Sphere();
+  const trees = new WeakMap(); // geometry → { bvh, pos, idx, count, posVersion, idxVersion } | false (cannot)
+  const hits = [];
+  const info = { mode: 'bvh', built: 0, refits: 0, failed: 0, buildMs: 0, plainCasts: 0 };
+  let windowStart = -Infinity;
+  let spent = 0;
+  const best = [0, 0, 0];
+  let bestDist = Infinity;
+
+  function treeFor(mesh) {
+    if (mesh.isSkinnedMesh || mesh.isInstancedMesh || mesh.isBatchedMesh) return null;
+    const g = mesh.geometry;
+    if (!g || !g.attributes) return null;
+    const pos = g.attributes.position;
+    if (!pos) return null;
+    if (g.morphAttributes && g.morphAttributes.position && g.morphAttributes.position.length) return null;
+    const idx = g.index;
+    const full = idx ? idx.count : pos.count;
+    const dr = g.drawRange;
+    if (dr && (dr.start > 0 || (dr.count !== Infinity && dr.count < full))) return null;
+    let t = trees.get(g);
+    if (t === false) return null;
+    if (t) {
+      if (t.pos !== pos || t.idx !== idx || t.count !== pos.count || (idx && idx.version !== t.idxVersion)) {
+        trees.delete(g); // replaced or resized: rebuild below
+        t = undefined;
+      } else {
+        if (pos.version !== t.posVersion) {
+          t.bvh.refit(); // vertices animated on the CPU
+          t.posVersion = pos.version;
+          info.refits++;
+        }
+        return t;
+      }
+    }
+    const t0 = now();
+    if (t0 - windowStart >= FRAME_MS) {
+      windowStart = t0;
+      spent = 0;
+    }
+    if (spent >= BUILD_BUDGET_MS) return null; // plain raycast this time; built on a later frame
+    try {
+      const bvh = new MeshBVH(g, { indirect: true, setBoundingBox: false, verbose: false });
+      t = { bvh, pos, idx, count: pos.count, posVersion: pos.version, idxVersion: idx ? idx.version : 0 };
+      trees.set(g, t);
+      info.built++;
+    } catch (err) {
+      trees.set(g, false); // e.g. a three.js older than the slice supports: plain raycast for good
+      info.failed++;
+      t = null;
+    }
+    const dt = now() - t0;
+    spent += dt;
+    info.buildMs += dt;
+    return t;
+  }
+
+  function castOne(obj) {
+    hits.length = 0;
+    let result;
+    const t = obj.isMesh ? treeFor(obj) : null;
+    if (t) {
+      const g = obj.geometry;
+      if (g.boundingSphere === null) g.computeBoundingSphere(); // as Mesh.raycast does
+      sphere.copy(g.boundingSphere).applyMatrix4(obj.matrixWorld);
+      if (!raycaster.ray.intersectsSphere(sphere)) return undefined;
+      t.bvh.raycastObject3D(obj, raycaster, hits);
+    } else {
+      if (obj.isMesh || obj.isPoints || obj.isLine || obj.isSprite) info.plainCasts++; // drawables only, not groups
+      result = obj.raycast(raycaster, hits);
+    }
+    for (let i = 0; i < hits.length; i++) {
+      const h = hits[i];
+      if (h.distance < bestDist) {
+        bestDist = h.distance;
+        best[0] = h.point.x;
+        best[1] = h.point.y;
+        best[2] = h.point.z;
+      }
+    }
+    return result;
+  }
+
+  // Raycaster.intersectObject's traversal: the layer test, and `false` from raycast stops the subtree.
+  function visit(obj) {
+    let propagate = true;
+    if (obj.layers.test(raycaster.layers)) {
+      if (castOne(obj) === false) propagate = false;
+    }
+    if (propagate) {
+      const c = obj.children;
+      for (let i = 0; i < c.length; i++) visit(c[i]);
+    }
+  }
+
+  const hitTest = (origin, direction) => {
+    o.set(origin[0], origin[1], origin[2]);
+    d.set(direction[0], direction[1], direction[2]).normalize();
+    raycaster.set(o, d);
+    bestDist = Infinity;
+    for (let i = 0; i < targets.length; i++) visit(targets[i]);
+    hits.length = 0;
+    return bestDist < Infinity ? [best[0], best[1], best[2]] : null;
+  };
+  /** Diagnostics: `{ mode: 'bvh', built, refits, failed, buildMs, plainCasts }` (cumulative). */
+  hitTest.info = () => ({ ...info });
+  return hitTest;
+}