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
+26 -9
View File
@@ -1,8 +1,8 @@
# Jellyfin Web VR180 — 项目交接文档
> 给新对话用。读完这份就能接手,不需要重新调查环境。
> 最后更新:已部署版本 `2e32e6`(`NS.version = hud-6`;ADDENDUM 6 字幕深度/大小解耦
> + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8 画面拖动搬迁)
> 最后更新:已部署版本 `5217a3`(`NS.version = hud-7`;ADDENDUM 6 字幕深度/大小解耦
> + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8/8b 画面搬迁(实时拖动))
> 已在 Quest 浏览器里实机验证模块加载 + 锁定数学(`subLockAngle/subAngleDeg`,`errors: []`);
> **VR 会话内的观感还没看过**。
@@ -285,7 +285,7 @@ WebXR 规范:需要 *transient activation*。前面不能有 `await`,否则
| 引导线(十字双光束) | ✅ 任何时候都显示 |
| 面板唤出门限 | ✅ 只有指示线指向/靠近面板时才唤出;唤出那一下不算点击;500ms 内忽略 |
| 锁按钮(面板不启动) | ✅ 面板媒体行的第五个按钮:上锁后切到「只显示锁」的最小面板,并同样自动隐藏;每次进 VR 重置为未锁 |
| 画面搬迁(180°窗口) | ✅ 面板进度条上方的拖动条:按住拖动,画面绕眼点左右上下转;连点 3 次复位;每次进 VR 回正前方 |
| 画面搬迁(180°窗口) | ✅ 面板进度条上方的拖动条:按住 0.5s 后拖动 = 搬画面;点一下 = 复位;每次进 VR 回正前方 |
| 按压反馈 | ✅ 圆环放大 1.9× + 蓝填充 + 变白,300ms |
| 字幕抓拖 | ✅ 注视选中 + 手移动拖(与视线解耦,避免转头就飘) |
| 字幕深度/大小解耦 | ✅ 默认「锁定视角尺寸」:拉近/拉远只改深度,视角大小与画面位置不变 |
@@ -412,8 +412,8 @@ subMode / subCanvasSize / subCrop / subTex / subOpacity / subPlacement
subLockAngle / subAngleDeg / subTextDeg / subYOverZ ← ADDENDUM 6
ctlSubsOn / ctlSubDist / ctlSubAngle / ctlSubLock ← 控制条实际画出的值
ctlLock / ctlMode / ctlHold / pressAt / lastActivate ← ADDENDUM 7/7b 锁、面板保持与唤出判定
videoYaw / videoPitch / videoAngleLive / videoRotMode ← ADDENDUM 8 画面搬迁
videoRebuilds / videoReset / viewDrag / viewTaps
videoYaw / videoPitch / videoRotMode / videoTransformWritable ← ADDENDUM 8/8b 画面搬迁
videoSpace / videoRebuilds / videoReset / viewDrag / frameErr
ctlHidden / ctlVisible / ctlBeamOn / ctlDraws / ctlErr
panelPose / grab / grabValue / saved
errors[] 最近错误
@@ -470,7 +470,24 @@ errors[] 最近错误
拖动用**射线自身的方向差**而不是面板上的坐标:面板坐标挪几度就出界了,射线旋转无行程限制,
而且"光标下的那个点始终在光标下",才像"抓住画面拖"。
**唯一的未知**:`XREquirectLayer.transform` 规范上可写,但运行时可能忽略。所以每会话探测一次
(写一个已知旋转再读回):`live` = 每帧写 transform(零成本);`rebuild` = 只能重建媒体层,
那就只在**创建/松手/复位**时重建,拖动过程中画面在松手后追上。见 `stats.videoRotMode` /
`videoRebuilds`。**这条必须真机验证,离线测不出来。**
### 6.15 拖动为什么一开始"松手才动",以及复位为什么崩(ADDENDUM 8b)
两个都是我的 bug,记在下面免得再犯:
1. **探测用四元数分量比较 → 假阴性。** `q` 和 `-q` 是同一个旋转,运行时还可能返回归一化后的
值,所以"写进去再读回来比 y/w"会得出错误的"只读"结论。于是拖动走到重建分支,而那个分支
被限成"只在松手时执行" → 松手才动。**现在比 `position`**(精确、无符号歧义)。
2. **复位崩溃 = 先建后毁。** 同一 `<video>` 上同时存在两个 `XRMediaBinding` 等距柱状图层,
外加微秒级连着重建两次(松手一次 + 复位一次)→ 浏览器直接挂。现在重建一律:
在 `setTimeout`(**不在 XR 帧回调里**)执行、**先毁后建**、限流 120ms、最多排一个。
`transform`/`space` 两条路根本不重建,所以正常情况走不到这条。
3. 顺手补的两个健壮性漏洞:`getOffsetReferenceSpace()` 抛错会逃进帧循环——那里抛异常等于
**永久冻住会话**(rAF 只在回调末尾续订);现在包了 try/catch 并降级到 rebuild。整个每帧
函数体也都包了 try/catch。
**机制自动二选一**:`stats.videoRotMode` = `transform`(每帧写 transform)/ `space`
(`layer.space = refSpace.getOffsetReferenceSpace(q)`)/ `rebuild`(手动兼容档)。
两者**互斥**:创建图层时只有 rebuild 档会把 transform 烘进去,否则会叠加两次旋转。
**手势**(按你的要求):`点一下复位 · 按住 0.5s 再拖动`。拖动基准取"按住满 0.5s 那一刻"的射线,
不是按下那一刻——否则那半秒会把手抖放大成甩动。1° 死区防抖。