hud-7: live picture pan; fix the reset crash; tap-to-reset / hold-to-drag

Reported after hud-6:
  触发复位后直接崩溃了;我拖动后,我希望画面立刻就有反应,而不是我松手之后才改变。
  按住0.5s后拖动才是拖动,否则算复位

1. Why the picture only moved on release — a bad probe
The transform-write probe compared quaternion COMPONENTS. q and -q are the same
rotation and a runtime may hand back a renormalised quaternion, so a perfectly
capable runtime could be judged "read-only". When it was, the drag took the
rebuild branch, and that branch was throttled to "on release only" — hence the
picture sitting still until the finger came up. The probe now compares the
POSITION (exact, no sign ambiguity).

2. Two mechanisms, auto-selected and mutually exclusive
   'transform' -> layer.transform = q              (one write per change)
   'space'     -> layer.space = refSpace.getOffsetReferenceSpace(q)
                     (the recentering path every WebXR app uses; a layer pose is
                      recomputed from its space each frame)
   'rebuild'   -> recreate the media layer (manual escape hatch, "兼容" in the 2D panel)
createVideoLayer() only bakes the transform in for 'rebuild' — otherwise the
probe's own write would apply the aim twice. layer.transform is never written on
the 'space' path and vice versa. stats.videoRotMode / videoTransformWritable
report what was chosen.

3. The crash — create-before-destroy
The reset created the replacement layer BEFORE destroying the old one: two
XRMediaBinding equirect layers bound to one <video> element at once, then a
second rebuild microseconds later (release rebuilt, then reset rebuilt again),
took the browser down. A rebuild now runs in a setTimeout OUTSIDE the XR frame
callback, destroys FIRST, is throttled to 120 ms, and never queues more than one.
The transform/space paths never rebuild at all.

Two robustness holes found while testing:
  * videoSpaceFor() let a throwing getOffsetReferenceSpace() escape into the frame
    loop, where an exception kills the loop for good (rAF is only re-armed at the
    end of the callback) — a frozen session. Caught now, demoting to 'rebuild'.
  * the whole per-frame body is wrapped in try/catch for the same reason.

4. The gesture the owner asked for
   press the drag strip
     released before 500 ms, no movement -> RESET to dead ahead
     held past 500 ms, then moved        -> PAN
     held past 500 ms, never moved       -> RESET
The pan reference is captured when the hold threshold passes, not at the press,
so the hold itself cannot fling the picture; a ~1 deg dead zone absorbs jitter.
The strip now reads 点一下复位 · 按住 0.5s 再拖动 (the triple-tap hint is gone).

Verified offline against the real sources by three suites (build.py --check too):
  test-gesture  the state machine above, stubbed ray/clock: quick tap resets;
                hold-without-move resets; movement inside the hold window is
                ignored; after arming a +10/+5 deg ray move gives exactly
                +10/+5 deg; a pan does not reset; dead zone respected; pitch guard
  test-mech     position probe true/false for writable/ignored; transform
                strategy writes with no rebuild; space strategy assigns the offset
                space and leaves the transform alone; unchanged angle reuses the
                cached space; rebuild queues at most one and runs
                removeLayer -> createVideoLayer -> addLayer; throwing or absent
                getOffsetReferenceSpace is reported and falls back permanently
  test-ad8      quaternion aim/wrap/guard maths, panel bands on the 1440x520
                canvas, the strip's drawn readout, hold()
Deployed as mvp-5217a3 (hud-7); confirmed live on the Quest, errors empty.
This commit is contained in:
2026-10-11 21:47:55 +08:00
parent 263e270747
commit 7f751b7eee
7 changed files with 672 additions and 161 deletions
+127
View File
@@ -814,6 +814,10 @@ running.
## Runtime risk and how it is handled
> **SUPERSEDED by ADDENDUM 8b** — the probe below compared quaternion components,
> which is sign-sensitive and produced a false "read-only" verdict; and the gesture is
> now tap = reset / hold 0.5 s = drag. See the addendum at the end of this file.
`XRCompositionLayer.transform` / `XREquirectLayer.transform` are settable in the spec,
but a runtime may ignore the write. Since the whole interaction depends on it, the
module probes once per session:
@@ -849,3 +853,126 @@ probeVideoAngleMutable(layer) // write a known rotation, read it back
(`lastPressSrc` / `lastPressFrame`) captured in `pointerDown`.
- Stats: `videoYaw`, `videoPitch`, `videoAngleLive`, `videoRotMode`, `videoRebuilds`,
`videoReset`, `viewDrag`, `viewTaps`.
---
# ADDENDUM 8b — live picture pan: two mechanisms, the crash, and the real gesture
Owner feedback on ADDENDUM 8:
> 触发复位后直接崩溃了;另外,我拖动后,我希望画面立刻就有反应,而不是我松手之后才改变。
> 按住0.5s后拖动才是拖动,否则算复位
## 1. Why the picture only moved on release
ADDENDUM 8 decided whether it could write `layer.transform` with this probe:
```js
layer.transform = new XRRigidTransform(origin, q);
var o = layer.transform.orientation;
live = Math.abs(o.y - q.y) < 1e-4 && Math.abs(o.w - q.w) < 1e-4;
```
Comparing **quaternion components** is sign-sensitive — `q` and `−q` are the same
rotation — and a runtime is free to hand back a renormalised quaternion. So the probe
could report "read-only" for a runtime that was perfectly capable of the write. When it
did, the drag path took the rebuild branch, and because that branch was throttled to
"on release only", the picture sat still until the finger came up. That is exactly what
was observed.
The probe now compares the **position**, which is exact and has no sign ambiguity:
```js
layer.transform = new XRRigidTransform({x:0.123, y:-0.456, z:0.789}, identity);
writable = layer.transform.position matches that marker;
```
## 2. Two mechanisms, chosen automatically
```js
videoRotStrategy() -> 'transform' // preferred: one cheap write per change
| 'space' // layer.space = refSpace.getOffsetReferenceSpace(q)
| 'rebuild' // manual escape hatch ("兼容" in the 2D panel)
```
- `transform` — post-creation `layer.transform` writes are honoured.
- `space` — they are not, so the aim lives in an **offset reference space** instead. A
layer's pose is recomputed from its space every frame, and `getOffsetReferenceSpace()`
is the recentering path every WebXR app uses, so this is the more likely of the two to
be fully implemented.
- The two are **mutually exclusive**: `createVideoLayer()` must NOT bake the transform in
while the probe is about to write it, or the aim would be applied twice. Only the
`rebuild` strategy bakes it in at creation.
- `layer.transform` is never written on the `space` path, and vice versa.
Switching is automatic per session; `stats.videoRotMode` reports what was chosen and
`stats.videoTransformWritable` reports the raw probe result. The 2D panel has
「画面旋转: 自动 / 兼容」 to force the rebuild path without a redeploy.
## 3. The crash
The reset path rebuilt the video layer, and it created the replacement **before**
destroying the old one. Two `XRMediaBinding` equirect layers bound to the same `<video>`
element at the same time, plus a second rebuild microseconds later (the release path
also rebuilt, then the reset rebuilt again), took the browser down.
Every rebuild now:
1. runs in a `setTimeout` **outside the XR frame callback** (never inline in a frame),
2. **destroys the old layer first**, then creates the replacement,
3. is throttled to at most one per `REBUILD_MIN_MS` (120 ms),
4. never queues more than one pending rebuild.
The `space`/`transform` strategies rebuild **not at all**, so in the normal case the
crash path is not even reachable.
Two more robustness fixes found while testing this:
- `videoSpaceFor()` used to let a throwing `getOffsetReferenceSpace()` escape. It runs
inside the XR frame loop, where an exception would stop the loop and freeze the
session. It is caught now, and the strategy falls back to `rebuild`.
- The whole per-frame body (`updatePointer` / `pollGamepads` / `updatePanelPose` /
`updateGrabFrame` / `updateViewDrag` / frame hooks) is wrapped in a try/catch. A single
bad frame could previously kill the loop: `requestAnimationFrame` is only re-armed at
the end of the callback, so any throw froze the session permanently.
## 4. The real gesture
```
press the drag strip
├─ release before 500 ms, no movement -> RESET to dead ahead
├─ held past 500 ms, then moved -> PAN (picture follows the hand)
└─ held past 500 ms, never moved -> RESET
```
- The pan reference (`a0`) is captured **at the moment the hold threshold passes**, not
at the press. Otherwise the half second the user spends holding would fling the picture
the instant dragging armed.
- A ~1° dead zone keeps hand jitter from turning a reset tap into a tiny pan.
- The strip now reads `点一下复位 · 按住 0.5s 再拖动` instead of the retired triple-tap hint.
`stats.viewDrag` walks through it: `pressed (hold 500ms to pan)` →
`armed (drag to pan)` → `ended (moved)` / `reset (tap)`.
## 5. Verification
Three offline suites, all against the real sources (`build.py --check` passes too):
`test-ad8` — quaternion + panel geometry: aim for ±yaw/±pitch, unit norm, exact
azimuth/elevation recovery, yaw wrap, pitch guard, "aimed point stays under the cursor";
panel bands on the 1440×520 canvas (strip 0–0.20, inert readout 0.20–0.30, seek
0.30–0.52, media 0.52–0.74, subtitle 0.84–1.0, no dead column); the strip's drawn
readout; `hold()`.
`test-gesture` — the state machine above, driven with a stubbed ray: quick tap resets;
hold-without-movement resets; movement inside the hold window is ignored (no fling);
after arming a +10°/+5° ray move yields exactly +10°/+5°; a real pan does not reset; the
dead zone is respected; pitch cannot pass the guard.
`test-mech` — the mechanism: the position-based probe returns true for a writable
transform and false for an ignored one; the transform strategy writes and schedules no
rebuild; the space strategy assigns an offset space, leaves the transform alone (no
double rotation) and schedules no rebuild; unchanged angles reuse the cached space; the
rebuild strategy queues at most one, and its observed order is
`removeLayer -> createVideoLayer -> addLayer`; a throwing/absent
`getOffsetReferenceSpace()` is reported and permanently falls back to `rebuild`.