hud-6: pan the 180° video window about the eye; padlock as a panel button

ADDENDUM 8 — panning the video window (yaw/pitch about the eye)
The 180° window was hard-wired dead ahead, so scenes staged below the horizon
could only be watched by physically lowering the head. The video layer is an
XREquirectLayer with radius 0, i.e. the content sits at infinity: only its
ORIENTATION is visible and translating it does nothing. So panning is purely
layer.transform's rotation, which rotates the content about the eye point — no
parallax, no swim when the head moves, and no decode/upload cost (8K HEVC
DirectPlay untouched). Only the video rotates; the panel (refSpace, fixed pose)
and the subtitles (viewer space, head-locked) stay in front of the user.

    state.videoYaw   (+ = picture moved RIGHT)
    state.videoPitch (+ = picture moved UP)
    q = qy(-yaw) * qx(pitch)   -> aim = (cos p·sin yaw, sin p, -cos p·cos yaw)

Interaction is one affordance in the panel, above the progress bar (the owner's
requested placement): a drag strip. Pinch and drag -> the picture follows the
hand 1:1; three taps within 1.6 s reset it (taps counted on RELEASE, so a drag
cannot be mistaken for one); the live angles are printed on the strip. The drag
is driven by the RAY's own direction delta rather than a cursor position on the
panel: a panel-space cursor leaves the panel after a few degrees, while ray
rotation has no range limit and keeps the content point under the cursor.
Controls.hold() freezes the panel auto-hide for the drag's duration.

Pitch is limited only by a gimbal guard (±(π/2 - 0.02)) per "不限"; yaw wraps to
[-π, π]. Both reset to 0 on every VR session — not persisted.

Runtime risk: XREquirectLayer.transform is settable per spec but a runtime may
ignore the write, so it is probed once per session (write a known rotation, read
it back) -> stats.videoRotMode = 'live' (transform write per frame) or
'rebuild' (recreate the media layer, but only on creation/release/reset, never
per frame). THIS PROBE NEEDS A REAL XR SESSION — it is the one thing not
verifiable offline.

ADDENDUM 7b (previous pass, in this commit's tree) — the padlock
The padlock had been given its own quad layer parked 0.45 m to the right of the
panel. On device it could not be selected while the panel was shown but could
when it was hidden. Aiming is the binding constraint: with hands the only
pointing device is a ray, and the cursor's acceptance window reaches the panel's
own right edge, so the badge was outside every reachable ray; its hit test also
used the panel's layer geometry, which is why the behaviour flipped with panel
visibility. It is now an ordinary panel button (media row, fifth slot) using the
same hitTest/handleSelect path as every other button, and "locked" is a third
panel mode (0.26 × 0.10 m) that draws and hit-tests ONLY the padlock. Locking
swaps the panel in place and lets it auto-hide; the next summon shows the padlock
alone; unlocking restores the full panel and ignores presses for 500 ms.
handleSelect() no longer falls back to pressing the panel centre when no ray hit
exists.

Panel: expanded grew 0.72 × 0.21 m -> 0.72 × 0.26 m (canvas 1440 × 520) for the
drag strip; every row re-proportioned.

Verified offline against the real bundle: quaternion/drag maths (aim direction
for ±yaw/±pitch, unit norm, azimuth/elevation recovery, yaw wrap, pitch clamp,
"aimed point ends up under the cursor"), panel hit bands on the new 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, and hold().
build.py --check passes; deployed as mvp-2e32e6 and confirmed live on the Quest
(hud-6, videoYaw/videoPitch 0, errors empty).
This commit is contained in:
2026-10-11 19:59:25 +08:00
parent 838675baa6
commit 263e270747
7 changed files with 1103 additions and 87 deletions
+124 -1
View File
@@ -7,7 +7,7 @@ VR180 / VR360 沉浸播放,不用再手动切全屏 + 选投影。
## 1. 当前部署状态
已注入到 `192.168.123.199` 上的 Jellyfin 容器 `Jellyfin`(当前版本 `mvp-7616c9`,`NS.version = hud-5`,含 ADDENDUM 6 + 7 + 7b):
已注入到 `192.168.123.199` 上的 Jellyfin 容器 `Jellyfin`(当前版本 `mvp-2e32e6`,`NS.version = hud-6`,含 ADDENDUM 6 + 7 + 7b + 8):
| 项 | 值 |
|---|---|
@@ -811,3 +811,126 @@ Live Quest 3 over CDP after deploy: `__JFVR.version = 'hud-5'`, `stats.ctlMode =
The *feel* — how easily the padlock is aimed with the hand ray, and whether 0.5 s is the
right arm delay — can only be judged in the headset.
---
# ADDENDUM 8 — panning the 180° video window about the eye
## The requirement
> 我希望画面可以不是固定在我的正前方180度,我希望能调整画面内容在整个vr空间中以我眼睛为
> 旋转点进行上下左右的水平移动(为了解决一些场景需要物理低头才能看到的问题,我不想真的
> 低头去看)
The window was hard-wired dead ahead, so anything staged below the horizon cost a
physical head-down.
## Why a pure rotation is the right mechanism
The video layer is an `XREquirectLayer` with `radius` 0, i.e. the content is **at
infinity**. That single fact decides everything:
| Property of radius-0 equirect | Consequence for this feature |
| --- | --- |
| Only the orientation is visible; translation has no effect | Panning = rotating `layer.transform`, nothing else |
| No parallax | The picture does not swim when the head moves |
| It is a sphere "around everywhere" | The rotation is about the **eye point** — literally what was asked |
| No new texture / no re-upload | 8K HEVC DirectPlay, 120 Hz and the ~112 fps budget are untouched |
Only the video layer rotates. The control panel is at a fixed pose in `refSpace`, the
subtitles are head-locked in `viewerSpace`, so **the UI does not move with the
picture**.
Rejected alternatives:
| Alternative | Why not |
| --- | --- |
| `refSpace.getOffsetReferenceSpace()` | Rotates the panel, the hands and every ray too — the UI would leave the user's view |
| Moving the layer's position | An infinite-radius sphere shows no visible change (and would add parallax/swim) |
| Changing `centralHorizontalAngle` | That changes FOV/distortion, not where the window points |
## Controls
`state.videoYaw` (+ = picture right) and `state.videoPitch` (+ = picture up):
```
q = qy(-yaw) * qx(pitch) // pitch in the content frame, then yaw about world Y
aim = (cos p·sin yaw, sin p, -cos p·cos yaw) // the window's aim direction
```
The yaw sign is flipped so the two numbers read the way a user thinks about them, and
every value shown in the panel is a plain "moved this many degrees right/up".
Pitch is limited only by a gimbal guard (±(π/2 − 0.02)) per the owner's "不限,看用户拖动
幅度来定"; yaw wraps to [−π, π]. **Reset to 0/0 on every VR session** — not persisted.
Interaction is a single affordance that lives in the panel, above the progress bar
(the owner's requested placement):
```
⠿ 拖动调整画面 偏航 +12° 俯仰 -8°
连点 3 次复位 0° / 0° = 正前方
```
- Pinch it and drag — the picture follows the hand 1:1.
- Three taps within 1.6 s reset to dead ahead; taps are counted on **release**, so a
drag cannot be mistaken for one.
- The live angles are printed on the right at all times.
The drag uses the **ray's direction**, not a cursor position on the panel:
```
yaw' = wrap(yaw0 + (rayYaw - rayYaw0)), pitch' = clamp(pitch0 + (rayPitch - rayPitch0))
rayYaw = atan2(dx, -dz), rayPitch = asin(dy)
```
A panel-space cursor leaves the panel after a few degrees; ray rotation has no range
limit, and the content point under the cursor stays under the cursor — which is what
"grab the picture" has to feel like. `Controls.hold(true)` freezes the panel auto-hide
for the duration, otherwise the panel would auto-hide mid-drag.
## The one runtime unknown
`XREquirectLayer.transform` is settable per spec but a runtime may ignore the write. It
is probed once per session (write a known rotation, read it back):
```
stats.videoRotMode = 'live' -> a transform write per frame, free
= 'rebuild' -> recreate the media layer, but only on
creation / release / reset (never per frame)
```
`stats.videoRebuilds` counts rebuilds. **This probe needs a real XR session, so it is
the one thing that cannot be checked offline.**
## Offline verification (real bundle, no headset)
Quaternion / drag maths, extracted from `src/90-main.js` and driven directly:
```
yaw=0 pitch=0 -> aim (0, 0, -1) dead ahead
yaw=+20 -> aim x = +0.342 picture moved RIGHT
yaw=-20 -> aim x = -0.342 picture moved LEFT
pitch=+20 -> aim y = +0.342 picture moved UP
pitch=-20 -> aim y = -0.342 picture moved DOWN
yaw=30 pitch=40 -> unit direction, azimuth 30.000° and elevation 40.000° recovered
wrapYaw(±3π/2) -> ∓π/2 wraps into [-π, π]
clampPitch(±9) -> ±(π/2-0.02) gimbal guard holds
drag -> the aimed point ends up under the cursor (yaw and pitch)
```
Panel geometry via `Controls.hitTest` on the 1440×520 canvas:
```
y 0.05 / 0.18 -> view_drag (the whole strip)
y 0.25 -> null (time readout: intentionally inert)
y 0.40 -> seek
y 0.60 -> media row (back10|playpause|fwd10|subs|lock)
y 0.90 -> subtitle row (9 actions)
x sweep 0.04..0.96 at y 0.05 -> no dead column
```
`Controls.draw` renders `拖动调整画面` / `连点 3 次复位` / `偏航 +12° 俯仰 -8°` /
`0° / 0° = 正前方`, and `hold(true|false)` is reflected in `stats.ctlHold`.
Live Quest 3 over CDP after deploy: `__JFVR.version = 'hud-6'`,
`state.videoYaw = state.videoPitch = 0`, `errors: []`.