@realsee/five-webgpu 1.0.0-alpha.5 → 1.0.0-alpha.7

package/five/controllers/xrPanorama.d.ts

@@ -0,0 +1,506 @@
+import * as THREE from "three/webgpu";
+import { State } from "../types/state";
+import { Pose } from "../types/pose";
+import { CameraPose } from "../core/camera";
+import { XRGestureEvent } from "../utils/event";
+import { XRManager } from "../webxr/xrManager";
+import { DeviceProfileOverride } from "../webxr/deviceProfile";
+import { XRControllerModelFactory } from "../webxr/XRControllerModelFactory";
+import { ButtonStateMachine, ButtonEvent } from "../webxr/buttonStateMachine";
+import { PanoCircleMeshInterface } from "../types/panoCircleMeshInterface";
+import { BaseControllerInitArgs } from "./base";
+import { PanoramaController, PanoramaControllerCustomInitArgs, PanoramaControllerInitArgs } from "./panorama";
+/**
+ * XRPanorama（WebXR / VR 硬件）控制器的自定义初始化参数。
+ *
+ * 与 {@link PanoramaControllerCustomInitArgs} 的关系与 `VRPanoramaController`
+ * 完全同构：XR 下相机朝向由头显决定，纬度不受限，因此 `Omit` 掉
+ * `maxLatitude` / `minLatitude`（{@link parseArgs} 中会强制为 `±π/2`）。
+ *
+ * 在此基础上新增 XR 专属的可选字段（参考空间 / foveation / 手柄显示 / 设备映射 / 诊断）。
+ */
+interface XRPanoramaControllerCustomInitArgs extends Omit<PanoramaControllerCustomInitArgs, "maxLatitude" | "minLatitude"> {
+    /** 参考空间类型，默认 `'local-floor'` */
+    referenceSpaceType?: XRReferenceSpaceType;
+    /** 注视点渲染（foveation）强度 `[0, 1]`，默认 `1`（边缘最省） */
+    foveation?: number;
+    /** 是否显示手柄模型，默认 `true` */
+    showControllerModel?: boolean;
+    /** 是否显示 pointer ray（指向射线），默认 `true` */
+    showPointerRay?: boolean;
+    /** 按字段覆盖设备的按键 / 轴映射与手柄模型选择（Device_Profile），默认不覆盖 */
+    deviceProfile?: DeviceProfileOverride;
+}
+/**
+ * XRPanorama 控制器的自定义参数默认值。
+ *
+ * 从 {@link defaultPanoramaControllerCustomInitArgs} 中 `omit` 掉
+ * `maxLatitude` / `minLatitude`（这两项在 XR 下无意义），再补上 XR 专属字段。
+ */
+declare const defaultXRPanoramaControllerCustomInitArgs: Required<XRPanoramaControllerCustomInitArgs>;
+type XRPanoramaControllerInitArgs = BaseControllerInitArgs & XRPanoramaControllerCustomInitArgs;
+/**
+ * XRPanorama 模式控制器。
+ *
+ * 通过 WebXR 在 VR 头显中呈现全景。继承 {@link PanoramaController}，
+ * 复用其全景资源管理、点位移动动画、瓦片细化与视频全景逻辑；
+ * 相机 / 渲染 / 输入段将在后续任务（8.2–8.9）中接管重写。
+ *
+ * @remarks
+ * 前置条件：renderer 的后端必须为 WebGL2（非 WebGPU），即 `new Five()` 时
+ * 传入 `forceWebGL: true`。`three` 的 WebGPU 后端目前不支持 WebXR。
+ */
+declare class XRPanoramaController extends PanoramaController {
+    /**
+     * 自研 WebXR 会话管理（唯一持有 `XRSession` / XR layer 的地方）。
+     *
+     * @remarks
+     * 负责进入 / 退出、眼相机、手柄位姿追踪与逐眼渲染；控制器只经它取 session、
+     * 输入源射线与 Eye_Camera，不再依赖 three 渲染器自带的 XR 管理器。
+     */
+    protected xrManager: XRManager;
+    /** 是否显示手柄模型（构造参数 `showControllerModel`，默认 `true`）。 */
+    protected showControllerModel: boolean;
+    /** 是否显示 pointer ray（构造参数 `showPointerRay`，默认 `true`）。 */
+    protected showPointerRay: boolean;
+    /**
+     * 左右手 pointer ray 的 `Raycaster`（**复用实例**，不每帧 new）。
+     *
+     * @description
+     * 每帧由 {@link XRManager.fillRaycaster} 按输入源的 target ray 填充（对应需求 8.6）。
+     * 按 `inputSource.handedness` 分左右手（`'none'` 归右手），供拾取
+     * （任务 8.9 的 `intersect`）消费。
+     *
+     * 复用时统一设置拾取参数（与 `VRPanoramaController.intersect` 中 raycaster 的参数对齐）：
+     * `params.Points.threshold = 0.1`、`firstHitOnly = true`、`floorIndex = -1`。
+     */
+    protected controllerRaycasters: {
+        left: THREE.Raycaster;
+        right: THREE.Raycaster;
+    };
+    /**
+     * 注视 / 手势射线（**复用实例**）。
+     *
+     * @description
+     * 当设备提供 hand tracking 或 `targetRayMode === 'transient-pointer'`（如 Apple Vision Pro）
+     * 时，用它作为拾取源（对应需求 8.8）。首次需要时在 {@link updateGazeRay} 中惰性创建，
+     * 不需要时保持 `null`。拾取参数与 {@link controllerRaycasters} 一致。
+     */
+    protected gazeRaycaster: THREE.Raycaster | null;
+    /**
+     * 本帧 {@link controllerRaycasters} 的哪一只手被真正填充过。
+     *
+     * @description
+     * `controllerRaycasters` 是复用实例，某只手本帧没有输入源时它里面残留的是**上一帧**
+     * 的 origin / direction。拾取与走点必须只用本帧填过的射线，否则会按一条陈旧射线选点。
+     * 由 {@link updateControllerHelper} 每帧重置并写入，{@link pickPickingRaycaster} 据此判断。
+     */
+    protected controllerRayFilled: {
+        left: boolean;
+        right: boolean;
+    };
+    /**
+     * 手柄模型工厂（承载 glTF 手柄模型，`gltfLoader` 桥接到 five 的 fetcher）。
+     * @description 惰性创建：第一次需要建手柄模型时才 new（见 {@link getControllerModelFactory}）。
+     */
+    protected controllerModelFactory: XRControllerModelFactory | null;
+    /**
+     * 按键状态机（纯逻辑）：把每帧采样到的 `pressed` 转成 `buttonDown / press / buttonUp / tap` 事件，
+     * 状态以 `(XRInputSource, 按键名)` 为键。
+     */
+    protected buttonStateMachine: ButtonStateMachine;
+    /** 按 Device_Profile 生成的左右手按键映射（profile 在会话内不变，构造期算一次）。 */
+    private buttonMaps;
+    /** 以 `XRInputSource` 为键的手柄模型 / pointer ray 引用，用于移除时清理。 */
+    private inputVisuals;
+    /** `showControllerModel` / `showPointerRay` 变化后置位，下一帧在 {@link updateTime} 中重建 / 移除。 */
+    private inputsDirty;
+    /** 同一帧最多走点一次的标志（tap 走点与驻留走点共用），每帧 {@link updateTime} 开头清零。 */
+    private walkedThisFrame;
+    /** 最近一次 {@link updateTime} 的帧时间，供输入源移除 / 会话结束时补发 buttonUp 用。 */
+    private lastFrameTime;
+    /** 本帧需要走点的 trigger tap 来源（未被 preventDefault），先右后左处理。 */
+    private walkSources;
+    /**
+     * 驻留走点状态：当前被射线持续指向的点位 `panoMesh`。
+     *
+     * @description
+     * 与 `VRPanoramaController` 的同名字段同义：{@link intersect} 每帧记录射线命中的点位，
+     * 若连续多帧命中同一个点位且时长超过 {@link ACTIVE_TO_CURRENT_DELAY}，则自动走点。
+     * `XRPanoramaController` 与 `VRPanoramaController` 平级（都 `extends PanoramaController`），
+     * 继承不到 VR 的这两个字段，故在本类里新增。
+     */
+    protected activePanoMesh?: PanoCircleMeshInterface;
+    /**
+     * 驻留走点状态：{@link activePanoMesh} 开始被指向的时间戳。
+     * 与 {@link activePanoMesh} 配合判定驻留时长。
+     */
+    protected activeTime?: number;
+    /**
+     * 注视 / 手势射线的复用实例（惰性创建，不每帧 new）。
+     * @description {@link updateGazeRay} 与 `select` 回调共用；是否「生效」由 {@link gazeRaycaster} 是否非空表达。
+     */
+    private gazeRayPool;
+    /**
+     * 强制 latitude 不受限（`±π/2`），再交给父类解析。
+     *
+     * 与 `VRPanoramaController.parseArgs` 同构：XR 下相机朝向由头显决定，
+     * 不应被 `maxLatitude` / `minLatitude` 约束。
+     */
+    static parseArgs(args: XRPanoramaControllerInitArgs): Required<PanoramaControllerInitArgs>;
+    /** 返回 `mode: 'XRPanorama'` 的初始化动画终态 */
+    static initAnimationEndState(args: XRPanoramaControllerInitArgs): State;
+    constructor(args: XRPanoramaControllerInitArgs);
+    /**
+     * 更新配置：强制 latitude 不受限后交给父类。
+     *
+     * 与 `VRPanoramaController.updateConfiguration` 同构。
+     */
+    updateConfiguration(args: XRPanoramaControllerCustomInitArgs): boolean;
+    /**
+     * 时间迭代（XR 版）。
+     *
+     * @description
+     * 全景业务段（动画推进 / panoMeshes / 瓦片细化 / 全景视频）直接复用父类
+     * {@link PanoramaController.updateTime}。父类在 `locationMotion` 运行时算出站点位置
+     * `cameraPose.offset`，并**只通过** `setCamera` 应用到相机；本类覆写的 {@link setCamera}
+     * 只取其中的位置（朝向 / fov / distance 一律忽略），因此站点位置必须先经父类
+     * `updateTime` 更新，眼相机才能用到**本帧**的站点。相机朝向则由本方法从头显单向同步。
+     *
+     * 每帧顺序：
+     * 1. 父类全景业务（经 {@link setCamera} 更新 `camera.position`）；
+     * 2. `xrManager.beginFrame`：以本帧站点位置算 Head_Pose、更新 Eye_Camera 与手柄位姿；
+     * 3. `hasPose` 时把 five 相机朝向同步为头部朝向（位置保持站点，不写 `zoom`）；
+     * 4. 手柄采样 / 注视射线；
+     * 5. 射线拾取与驻留走点。
+     *
+     * @param time - 当前帧时间戳
+     * @param deltaTime - 距上一帧的时间增量
+     * @param args - rAF 透传的实参，`args[1]` 为 `XRFrame`（`args[0]` 是 rAF 自己的时间戳）
+     */
+    updateTime(time: number, deltaTime: number, ...args: any[]): void;
+    /**
+     * 相机反向同步：XR → five（每帧在 {@link updateTime} 中、`hasPose` 时调用）。
+     *
+     * 只写朝向，**不改 `camera.position`**（站点位置只由全景业务段 A 的 `locationMotion`
+     * 经 {@link setCamera} 驱动，头部平移不改变站点），也不碰只读的 `zoom`：
+     * 直接 compose 本地矩阵再反算 pose。
+     *
+     * @param headOrientation - 本帧头部朝向（`FrameInfo.headOrientation`）
+     */
+    protected syncCameraFromXR(headOrientation: THREE.Quaternion): void;
+    /**
+     * 生命周期：渲染（XR 版）。
+     *
+     * @description
+     * 返回 `true` 表示「本帧已自行处理」，`Five.render()` 据此跳过 `FiveRenderer`
+     * （`five.ts` 约 1842-1851 行），XR 下没有后处理合成。已进入但本帧 `hasPose` 为假时
+     * `renderEyes` 返回 `false` 并跳过绘制，这里仍返回 `true`，避免 `FiveRenderer`
+     * 白白渲染一帧到头显不可见的画布。
+     *
+     * 清屏、视口、scissor、渲染目标与状态恢复都由 `xrManager.renderEyes` 内部处理。
+     *
+     * @returns 已进入返回 `true`（旁路 `FiveRenderer`）；未进入返回 `false`（退回普通渲染路径）
+     */
+    render(): boolean;
+    /**
+     * 转动摄像头（任务 8.6，姿态旁路）。
+     *
+     * XR 下相机朝向由头显决定，不接受外部姿态驱动，直接 resolve 空 Promise。
+     * 与 `VRPanoramaController.updateCamera` 同构。
+     *
+     * @param pose - 目标姿态（忽略）
+     * @param duration - 动画时长（忽略）
+     * @param userAction - 是否用户操作（忽略）
+     */
+    updateCamera(pose: Partial<Pose>, duration: number, userAction: boolean): Promise<void>;
+    /**
+     * 通过帧动画转动摄像头（任务 8.6，姿态旁路）。
+     *
+     * XR 下相机朝向由头显决定，不接受外部关键帧驱动，直接 resolve 空 Promise。
+     * 与 `VRPanoramaController.updateCameraWithKeyframes` 同构。
+     *
+     * @param keyframes - 关键帧列表（忽略）
+     * @param duration - 动画时长（忽略）
+     * @param userAction - 是否用户操作（忽略）
+     */
+    updateCameraWithKeyframes(keyframes: {
+        progress: number;
+        value: Pose;
+        key?: string;
+    }[], duration: number, userAction: boolean): Promise<void>;
+    /**
+     * 同步修改相机参数（任务 8.6，姿态旁路）。
+     *
+     * **只应用站点位置，忽略朝向 / fov / distance。**
+     * 父类 `PanoramaController.updateTime` 在 `locationMotion` 运行时算出站点位置
+     * `cameraPose.offset`，并且只通过 `setCamera` 应用到相机；若这里是空实现，
+     * 切换全景图时 `camera.position` 永远不更新，眼相机停在旧站点，而全景球贴图已切到新点位，
+     * 渲染就会错位。因此这里把 `offset` 写入 `camera.position`。
+     *
+     * 其余字段一律忽略：
+     * - `longitude` / `latitude`：朝向由头显决定，由 {@link syncCameraFromXR} 单向反写，
+     *   写入会与头显朝向打架；
+     * - `fov`：视场角由头显的各眼投影矩阵决定；
+     * - `distance`：XR 下相机不后退（后退会使眼相机偏离站点、与头部真实位置不符），故忽略。
+     *
+     * 写入位置后，用现有四元数 / 缩放 compose 本地矩阵并 `computePose`，
+     * 让 `camera.pose` 与 `camera.position` 保持一致（`camera.zoom` 只读，不写）。
+     *
+     * @param cameraPose - 相机姿态（仅使用 `offset`）
+     */
+    protected setCamera(cameraPose?: Partial<CameraPose>): void;
+    /**
+     * 生命周期：更新屏幕渲染尺寸（任务 8.6，姿态旁路）。
+     *
+     * XR presenting 期间 `setSize` / `setPixelRatio` 是 no-op（尺寸由 three 的
+     * XRManager 管，见风险 R5），这里只标记需要重渲染。
+     * 与 `VRPanoramaController.updateRenderSize` 同构。
+     */
+    updateRenderSize(): void;
+    /**
+     * 是否准备好（任务 8.6，姿态旁路）。
+     *
+     * XR 期间始终视为用户操作中，返回 `false`。
+     * 与 `VRPanoramaController.isReady` 同构。
+     */
+    isReady(): boolean;
+    /**
+     * 新建一个用于拾取的 `Raycaster`，并设置与 `VRPanoramaController.intersect` 一致的参数。
+     *
+     * @description
+     * `params.Points.threshold = 0.1`、`firstHitOnly = true`、`floorIndex = -1`。
+     * 这些参数在构造期设一次，之后每帧只 {@link XRManager.fillRaycaster}
+     * 复用填充 origin / direction，不会被覆盖。
+     */
+    protected createPickingRaycaster(): THREE.Raycaster;
+    /**
+     * 每帧填充手柄射线，采样按键并派发 `xr.controller.update` 与按键手势（`updateTime` 的第 ③ 步）。
+     *
+     * @description
+     * 1. 重置本帧 {@link controllerRayFilled} 与 {@link walkSources}；`inputSources` 为空时直接返回。
+     * 2. 遍历输入源，按对象区分左右手（`handedness` 为 `'none'` 归右手），用
+     *    {@link XRManager.fillRaycaster} 填充复用的 {@link controllerRaycasters}；只有它返回 `true`
+     *    （本帧 pose 有效）才把该手标记为已填充。
+     * 3. 按 Device_Profile 读 axes / buttons；对每个已映射的按键调用
+     *    {@link ButtonStateMachine.sample}，按返回事件的顺序派发 `xr.gesture.*`。
+     * 4. 派发一次 `xr.controller.update`。
+     * 5. 处理 trigger tap 走点（先右后左，同一帧最多一次，见 {@link walkByTap}）。
+     *
+     * @param inputSources - 当前 session 的输入源
+     * @param time - 当前帧时间戳
+     * @param deltaTime - 距上一帧的时间增量
+     */
+    protected updateControllerHelper(inputSources: ArrayLike<XRInputSource>, time: number, deltaTime: number): void;
+    /**
+     * 按 Device_Profile 生成某只手的按键映射。
+     *
+     * @description
+     * trigger → `LeftTrigger` / `RightTrigger`；primary → `X` / `A`；secondary → `Y` / `B`；
+     * pinch → `LeftPinch` / `RightPinch`。下标为 `null`（该设备不映射）的项直接略过，
+     * 等价于「始终松开」。
+     */
+    private createButtonMap;
+    /**
+     * 派发状态机产出的一个按键事件为 `xr.gesture.*`。
+     *
+     * @description
+     * `isFirst` / `isFinal` 沿用原语义：`buttonDown` 为首次、`buttonUp` 为末次、`tap` 两者皆是、
+     * `press` 两者皆非。`LeftTrigger` / `RightTrigger` 的 `tap` 且未被业务 `preventDefault` 时，
+     * 记录到 {@link walkSources}，由 {@link walkByTap} 在本帧采样结束后统一走点。
+     */
+    protected dispatchButtonEvent(buttonEvent: ButtonEvent): void;
+    /**
+     * trigger tap 走点：顺序为先 `RightTrigger` 后 `LeftTrigger`，同一帧最多走点一次。
+     *
+     * @description
+     * 只有该输入源本帧射线已被填充（{@link XRManager.fillRaycaster} 返回 `true`）才走点；
+     * 走点后清零驻留状态。press 与其它按键不走点。
+     */
+    protected walkByTap(): void;
+    private tryWalk;
+    /**
+     * 会话结束前重置按键状态：仍按下中的键只补发 `buttonUp`（不派发 tap / press），并清空状态。
+     * 由 `XRManager` 的 `onSessionEnding` 回调调用。
+     */
+    protected resetButtonStates(): void;
+    /**
+     * 按 Device_Profile 的 `axes.x` / `axes.y` 从 `gamepad.axes` 读摇杆方向，
+     * 写入传入的 axes 对象。下标为 `null` / 越界 / gamepad 为空时按 0 处理（保持默认 0）。
+     *
+     * @param gamepad - 输入源的 gamepad（可能为 `null`）
+     * @param out - 待写入的 axes 对象
+     */
+    protected readAxes(gamepad: Gamepad | null | undefined, out: {
+        up: number;
+        down: number;
+        left: number;
+        right: number;
+    }): void;
+    /** 惰性创建手柄模型工厂（`gltfLoader` 桥接到 five 的 fetcher）。 */
+    private getControllerModelFactory;
+    /**
+     * 让某个输入源上的手柄模型 / pointer ray 与当前开关、设备能力保持一致（按需创建或移除）。
+     *
+     * @description
+     * - 模型：仅 `tracked-pointer` 且 gamepad / gripSpace 均非空、`showControllerModel` 为真、
+     *   `profile.model !== 'none'` 时存在，挂在 tracker 条目的 `grip` 下。
+     * - pointer ray：仅 `tracked-pointer` 且 `showPointerRay` 为真时存在，挂在 `targetRay` 下。
+     * - 该输入源已不在 tracker 里时直接忽略。
+     */
+    protected syncInputVisual(source: XRInputSource): void;
+    /**
+     * 按本帧拾取结果更新 pointer ray 的长度（需求 7.6）。
+     *
+     * @description
+     * - 被用于拾取的那只手（`raycaster` 与该输入源对应手的复用 `Raycaster` 是同一个实例）：
+     *   命中时长度取「射线起点到命中点的距离」与 {@link POINTER_RAY_LENGTH} 的较小值，
+     *   使射线远端落在命中点上，与焦点环 `intersectMesh` 的中心重合；
+     * - 其余输入源，以及本帧没有命中 / 没有拾取射线（`raycaster` 或 `point` 为 `null`）：恢复为 {@link POINTER_RAY_LENGTH}。
+     *
+     * 射线节点挂在 target ray 下，XR 到世界的变换是纯平移（无旋转无缩放），
+     * 所以局部 -Z 方向的长度等于世界距离。
+     *
+     * @param raycaster - 本帧用于拾取的射线，没有时传 `null`
+     * @param point - 命中点（世界坐标），未命中时传 `null`
+     */
+    protected updatePointerRayLength(raycaster: THREE.Raycaster | null, point: THREE.Vector3 | null): void;
+    /** 输入源被移除：摘掉其模型 / ray 并释放 ray 的几何 / 材质，删除 Map 条目。 */
+    protected removeInputVisual(source: XRInputSource): void;
+    /** 清理全部输入源的模型 / ray（会话结束、析构时调用）。 */
+    protected clearInputVisuals(): void;
+    private disposeRay;
+    /**
+     * 构造并派发一个 {@link XRGestureEvent}（{@link dispatchButtonEvent} 的内部辅助）。
+     *
+     * @param type - 事件名（`xr.gesture.*`）
+     * @param button - 触发的按键名
+     * @param isFirst - 是否为手势序列的首次
+     * @param isFinal - 是否为手势序列的末次
+     * @returns 派发出去的事件对象，调用方可据其 `defaultPrevented` 决定是否执行默认行为
+     */
+    protected emitGesture(type: 'xr.gesture.tap' | 'xr.gesture.press' | 'xr.gesture.buttonUp' | 'xr.gesture.buttonDown', button: XRGestureEvent['buttons'], isFirst: boolean, isFinal: boolean): XRGestureEvent;
+    /**
+     * 注视 / 手势射线：当设备提供 hand tracking，或输入源 `targetRayMode` 为
+     * `gaze` / `transient-pointer`（如 Apple Vision Pro）时，用它作为拾取源。
+     *
+     * @description
+     * 判定走能力检测，不看 `machineType`（UA 只用来挑模型）。命中输入源后用
+     * {@link XRManager.fillRaycaster} 填充复用的射线并赋给 {@link gazeRaycaster}；
+     * 没有命中的输入源，或本帧该输入源 pose 无效时置回 `null`，让拾取回落到手柄射线
+     * （不保留陈旧射线）。
+     */
+    protected updateGazeRay(): void;
+    /**
+     * session `select` 回调（捏合 / 注视选点）。
+     *
+     * 只有 `targetRayMode` 为 `gaze` 或 `transient-pointer` 的输入源走点（这类设备没有扳机）；
+     * 射线取该输入源本帧已填充的 target ray，未填充则不选点。
+     *
+     * @param source - 触发 `select` 的输入源
+     */
+    protected onXRSelect(source: XRInputSource): void;
+    /**
+     * 选取本帧用于拾取的射线源（任务 8.9）。
+     *
+     * ## 优先级
+     *
+     * 1. **注视 / 手势射线**（{@link gazeRaycaster}）：非 `null` 时优先。
+     *    `gazeRaycaster` 仅在 {@link updateGazeRay} 判定「设备提供 hand tracking 或
+     *    `targetRayMode === 'transient-pointer'`」时才被填充（如 Apple Vision Pro 的
+     *    捏合注视交互），否则保持 `null`。因此它非空即代表「本设备这一帧应走注视拾取」，
+     *    对应需求 8.8「设备提供 hand tracking 或 transient-pointer 时用注视 / 手势射线作为拾取源」。
+     * 2. **手柄射线**：无注视射线时回落到手柄。右手为主手（参照原始 five 的习惯），
+     *    故**优先右手** {@link controllerRaycasters.right}，其次左手。但要确认该手本帧确有
+     *    输入源 —— {@link controllerRaycasters} 是复用实例，若某手本帧未连接，其内容是上一帧的
+     *    陈旧值，不能据此拾取。所以这里按 `session.inputSources` 的 `handedness` 判定哪只手在场。
+     * 3. 两手都不在场且无注视射线：返回 `null`（本帧无可用拾取源）。
+     *
+     * @returns 本帧应使用的 `Raycaster`，无可用射线源时为 `null`。
+     */
+    protected pickPickingRaycaster(): THREE.Raycaster | null;
+    /**
+     * 计算射线碰撞并刷新点位选中态 / 驻留走点（任务 8.9）。
+     *
+     * ## 与 `VRPanoramaController.intersect` 的关系
+     *
+     * 结构与点位判定、驻留走点逻辑完全照搬 `VRPanoramaController.intersect`
+     * （见 `controllers/vrPanorama.ts`），差异只有一处 —— **射线源**：
+     *
+     * - `VRPanorama` 的射线源是**注视方向**（相机朝向）：
+     *   `new THREE.Raycaster(this.camera.position, this.camera.getDirection(...))`。
+     * - `XRPanorama` 的射线源换成 {@link pickPickingRaycaster} 选出的**手柄射线（优先）
+     *   或注视 / 手势射线**。这些 `Raycaster` 已由 {@link updateControllerHelper} /
+     *   {@link updateGazeRay} 在本帧填充好 origin / direction 与拾取参数
+     *   （`params.Points` / `firstHitOnly` / `floorIndex`，见 {@link createPickingRaycaster}），
+     *   这里**直接复用，不新建 `Raycaster`、不重设 params**（对应需求 8.6）。
+     *
+     * 其余（locationMotion 守卫、驻留走点、对 `accessibleNodes` 的 panoMesh 求交、取最近、
+     * 焦点环 {@link intersectMesh} 的位置 / 朝向、`intersect.update` 派发、模型求交兜底）
+     * 与 VR 版逐行同构。
+     *
+     * ## 无射线源时的降级
+     *
+     * {@link pickPickingRaycaster} 返回 `null`（本帧两手都不在场且无注视射线）时，
+     * 隐藏焦点环、清空驻留状态并返回 `undefined`，不做求交（对应需求 8.9 的「射线不可用时
+     * 不拾取」语义）。
+     *
+     * @param time - 当前帧时间戳
+     * @returns 本帧被指向的点位 `panoMesh`，无则 `undefined`。
+     */
+    protected intersect(time: number): PanoCircleMeshInterface | undefined;
+    /**
+     * 用一条射线选点并触发走点（扣扳机 / 捏合选点）。
+     *
+     * ## 为什么要单独实现
+     *
+     * five-webgpu 的 2D 走点逻辑内联在 `PanoramaController.onTapGesture(event)` 里，
+     * 入参是 `GestureEvent`（要 `event.center.raycaster` / `event.state` / `event.userAction`，
+     * 还要往回写 `event.state` 再派发 `gesture.tap`）。XR 没有 `GestureEvent`，
+     * 射线来自手柄 / 捏合，硬套会得到一个半真半假的事件对象。
+     *
+     * 原始 five 的 XR 控制器同样是单独实现了一个 `checkSelectedPano(raycaster)`
+     * （`xrPanorama.ts:984`），本方法照它移植，只把 API 换成 five-webgpu 的。
+     * 相比重构父类那 200 行 `onTapGesture`，这样对 2D 路径零风险。
+     *
+     * ## 选点策略（与原始 five 同构）
+     *
+     * 1. 先把「可到达点位」过滤出来：排除当前点位、排除超过 `maxAccessibleDistance` 的、
+     *    排除既不可加载也未激活的。
+     * 2. 射线与**模型**求交，拿到地面落点；在可到达点位里找离落点最近的，距离小于
+     *    `panoTapTriggerRadius` 则选中它（＝「指着地板上的点位圈走过去」）。
+     * 3. 没命中则退化为「沿射线方向找前方点位」（{@link getForwardObserverOrNot}）。
+     *    这里传 `xrManager.eyeCameras[0]` 而不是 five 的 `camera`：该方法要把点位投影到屏幕空间
+     *    比较距离，必须用**头显实际的投影矩阵**（单眼 Eye_Camera 的 view 投影），
+     *    用 five 那个 2D 相机（fov 90 / 画布宽高比）
+     *    会和头显里看到的范围不符。
+     * 4. 已在本次位移动画目标里的点位不重复选（避免连点抖动）。
+     * 5. 没选中：不在动画中时播一下 {@link cameraBounce} 回弹反馈。
+     *
+     * ## 为什么不直接调 `moveToPano`
+     *
+     * 走点要走 five 的既有事件链：派发 `pano.select` → `pano.request`，由
+     * `five.ts` 的 `controller.on("pano.request")` 统一调 `five.moveToPano`
+     * （见 `five.ts:2801-2806`）。这样业务侧 `preventDefault` 拦截、以及 five 层面的
+     * state 同步都和 2D 路径一致。直接调 `moveToPano` 会绕过这条链。
+     *
+     * @param raycaster - 选点射线（手柄射线或注视 / 捏合射线）
+     */
+    protected checkSelectedPano(raycaster: THREE.Raycaster): void;
+    /**
+     * 析构。
+     *
+     * @description
+     * 先 `super.destroy()` 回收全景业务侧资源，再清理 XR 资源（与 `VRPanoramaController` 同构）。
+     * `xrManager.dispose()` 幂等：已进入时同步归还（移除会话监听、释放 XR layer 与帧源）并尝试
+     * `session.end()`；归还过程中会回调 `onSessionEnding` / `onSessionEnd`。随后把手柄根节点
+     * `inputs.root` 从场景移除（其下的手柄节点已在归还时被 `inputs.clear()` 清掉）。
+     */
+    destroy(): void;
+    protected onPanGesture(): void;
+    protected onTapGesture(): void;
+    protected onPinchGesture(): void;
+    protected onMouseMove(): void;
+    protected onMouseOut(): void;
+}
+export { XRPanoramaController, XRPanoramaControllerCustomInitArgs, XRPanoramaControllerInitArgs, defaultXRPanoramaControllerCustomInitArgs, };

package/five/core/internalWebGPURenderer.d.ts

@@ -9,12 +9,18 @@ declare class InternalWebGPURenderer extends THREE.WebGPURenderer {
      * 上层可通过该回调感知并尝试恢复（重新配置 canvas、触发重渲染）。
      */
     onDeviceLostCallback?: (info: unknown) => void;
-    constructor({ antialias, logarithmicDepthBuffer, outputType, }: {
+    readonly forceWebGL: boolean;
+    constructor({ antialias, logarithmicDepthBuffer, outputType, forceWebGL, }: {
         antialias?: boolean;
         logarithmicDepthBuffer?: boolean;
         outputType?: OutputTextureDataType | undefined;
+        forceWebGL?: boolean;
     });
     get isInitialized(): boolean;
+    /**
+     * XR（WebXR）是否可用。
+     */
+    get isXRCapable(): boolean;
     /**
      * 强制让 WebGPU backend 重新配置 canvas 上下文。
      *

package/five/core/panoVideo.d.ts

@@ -8,8 +8,11 @@ interface PanoVideoProps {
 }
 declare class PanoVideo {
     private material;
-    object: THREE.Mesh<THREE.BufferGeometry, THREE.ShaderMaterial>;
+    object: THREE.Mesh<THREE.BufferGeometry, THREE.NodeMaterial>;
     private alphaMotion;
+    private u;
+    /** 是否已设置视频材质（等价于原来的 USE_PANO_VIDEO 宏状态） */
+    private active;
     constructor();
     setMaterial(value: PanoVideoProps | null): void;
     updateTime(time: number): void;

package/five/core/tiling.d.ts

@@ -1,6 +1,7 @@
 import * as THREE from "three/webgpu";
 import { WorkObserver } from "../work";
 import { ImageOptions } from "../types/imageOptions";
+import type { PBMPanoGainmap } from "../model";
 export interface TilingFrameState {
     time: number;
     resolution: THREE.Vector2;
@@ -9,25 +10,24 @@ export interface TilingFrameState {
     cameraMatrix: THREE.Matrix4;
     cameraProjectionMatrix: THREE.Matrix4;
     panoMap: THREE.CubeTexture | null;
-    gainMap?: THREE.CubeTexture;
+    /**
+     * 该 pano 的 gainmap（cube 贴图 + 配置），无 HDR 时不存在
+     * @description 复用 `PBMPanoGainmap` 类型（type-only import，不产生运行时依赖）
+     */
+    panoGainmap?: PBMPanoGainmap;
     panoMatrix: THREE.Matrix4;
     panoZoom: number;
     minLevel: number;
     level: number;
-    /** HDR：是否启用，以及该 pano 的 gainmap 配置 + 显示增益 */
+    /** HDR：是否启用，以及显示增益 */
     useHDR?: boolean;
     maxDisplayBoost?: number;
-    hdrConfig?: {
-        gamma?: number;
-        minContentBoost?: number;
-        maxContentBoost?: number;
-        hdrCapacityMin?: number;
-        hdrCapacityMax?: number;
-    };
 }
 export declare class Tiling {
     private disposed;
     fiveId: string;
+    /** 是否开启 HDR 支持，详见 {@link FiveInitArgs.enableHDR} */
+    enableHDR: boolean;
     level: number;
     pedding: number;
     maxRequest: number;
@@ -52,15 +52,29 @@ export declare class Tiling {
     private forceRenderWhenNextUpdate;
     constructor(options: {
         fiveId: string;
+        /**
+         * 是否开启 HDR 支持，详见 {@link FiveInitArgs.enableHDR}
+         * @description
+         * 决定 `renderTarget` 的纹理类型：开启时使用 `THREE.HalfFloatType` 以承载 HDR 数据，
+         * 关闭时使用默认的 `THREE.UnsignedByteType`，避免不必要的显存与性能开销。
+         * @default `false`
+         */
+        enableHDR?: boolean;
     });
     dispose(): void;
     /** 从池取用一个 TileMaterial，池空则新建 */
     private acquireTileMaterial;
     /** 归还 TileMaterial 到池：清空纹理引用并重置状态；超出上限或已销毁则直接 dispose */
     private releaseTileMaterial;
-    /** 从纹理池取一个同尺寸 THREE.Texture，池空则新建。复用可保留其 GPUTexture，后续 setImage+needsUpdate 会原地重传（同 video texture 机制）。 */
+    /**
+     * 从纹理池取一个同尺寸、同色彩空间的 THREE.Texture，池空则新建。
+     * 复用可保留其 GPUTexture，后续 setImage+needsUpdate 会原地重传（同 video texture 机制）。
+     * @description 必须带上 colorSpace 分桶：GPU 纹理格式在首次创建时按 colorSpace 决定
+     * （sRGB 会创建 rgba8unorm-srgb 做硬件解码），之后只重传像素、不会重建格式。
+     * 色图（sRGB）与 gainmap（NoColorSpace）若共用同一张池化纹理，格式会被串用而渲染错误。
+     */
     private acquireTileTexture;
-    /** 归还瓦片纹理到池（按尺寸分桶）；超出上限或已销毁或尺寸未知则直接 dispose。 */
+    /** 归还瓦片纹理到池（按尺寸 + 色彩空间分桶）；超出上限或已销毁或尺寸未知则直接 dispose。 */
     private releaseTileTexture;
     /**
      * 把 loadTexture 产出的“一次性纹理”的图像搬进池化纹理并复用其 GPUTexture。

package/five/core/webglAsyncReadFix.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 修复 WebXR 沉浸式会话期间 WebGL 后端异步回读（readRenderTargetPixelsAsync 等）永不 resolve 的问题。
+ *
+ * 根因：
+ * three r183 `src/renderers/webgl-fallback/utils/WebGLUtils.js`（约 273-310 行）的
+ * `_clientWaitAsync()` 在 `gl.clientWaitSync` 返回 `TIMEOUT_EXPIRED` 时，
+ * 使用 `window.requestAnimationFrame(test)` 继续轮询。
+ * 沉浸式 XR 会话期间 `window.requestAnimationFrame` 不会触发（帧由 `XRSession.requestAnimationFrame` 驱动），
+ * 导致该 Promise 永不 resolve；
+ * `WebGLTextureUtils.copyTextureToBuffer` → `readRenderTargetPixelsAsync` 随之挂死，
+ * 进而 `PanoramaController.moveToPano` 里 `await getRgbaDataFromCubeTexture(...)` 永不返回，点位无法真正移动。
+ *
+ * 修复：实例级替换 `backend.utils._clientWaitAsync`，逻辑与 three 原版逐行一致，
+ * 唯一区别是轮询用 `setTimeout(test, 0)` 代替 `requestAnimationFrame`——setTimeout 在 XR 会话中仍然工作。
+ *
+ * 非 XR 设备、WebGPU 后端下均为空操作。
+ */
+/**
+ * 仅当设备被识别为 XR 头显（Pico / Oculus / Vision Pro）、后端为 WebGL 且存在
+ * `utils._clientWaitAsync` 时，安装实例级补丁；其余情况什么都不做。
+ * @param backend `renderer.backend`，需在 `init()` 完成之后传入
+ * @returns 是否实际安装了补丁
+ */
+declare function installWebGLAsyncReadFix(backend: unknown): boolean;
+export { installWebGLAsyncReadFix };