@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.11

package/five/application/five.d.ts

@@ -46,6 +46,8 @@ declare class Five extends Subscribe<EventTypes> {
      * Model 模型游走模式
      * Floorplan 模型查看模式
      * Topview 户型图模式
+     * VRPanorama VR眼镜模式
+     * XRPanorama XR 全景模式（WebXR，需 forceWebGL）
      * ```
      */
     static Mode: {
@@ -54,6 +56,8 @@ declare class Five extends Subscribe<EventTypes> {
         readonly Floorplan: "Floorplan";
         readonly Topview: "Topview";
         readonly Mapview: "Mapview";
+        readonly VRPanorama: "VRPanorama";
+        readonly XRPanorama: "XRPanorama";
     };
     /**
      * 自动播放状态是否暂停
@@ -159,6 +163,7 @@ declare class Five extends Subscribe<EventTypes> {
     private helperGroup;
     private modeChangeDuration;
     private enableWheel;
+    private _enableHDR;
     private controller?;
     private destroyed;
     private stateSynced;
@@ -212,7 +217,7 @@ declare class Five extends Subscribe<EventTypes> {
      */
     get helperVisible(): boolean;
     set helperVisible(visible: boolean);
-    updateConfiguration(args: Pick<FiveInitArgs, "panorama" | "model" | "floorplan" | "topview" | "mapview" | "imageOptions" | "textureOptions">, refresh?: boolean): void;
+    updateConfiguration(args: Pick<FiveInitArgs, "panorama" | "model" | "floorplan" | "topview" | "mapview" | "vrPanorama" | "xrPanorama" | "imageOptions" | "textureOptions">, refresh?: boolean): void;
     /**
      * 将显示区域加载到页面 DOM 中
      * @description
@@ -494,5 +499,14 @@ declare class Five extends Subscribe<EventTypes> {
     /** 开启 AdaptiveLuminance */
     get enableAdaptiveLuminance(): boolean;
     set enableAdaptiveLuminance(enable: boolean);
+    /**
+     * 是否开启了 HDR（只读）。
+     * 由构造时的 `enableHDR` 初始化参数决定，并受 `canWebGPU`/`forceWebGL` 影响
+     * （forceWebGL 下 XR 的 projection layer 固定 RGBA8，HDR 没有落地路径，两者互斥），
+     * 实际生效值可能与传入的初始化参数不同。开启后主渲染管线的 outputType 为
+     * `THREE.HalfFloatType`，否则为默认的 `THREE.UnsignedByteType`。
+     * 运行时不可切换（涉及渲染目标重建），因此只提供只读 getter，不提供 setter。
+     */
+    get enableHDR(): boolean;
 }
 export { Five, FiveInitArgs };

package/five/application/fiveInitArgs.d.ts

@@ -52,6 +52,17 @@ interface FiveInitArgs {
      * @default `false`
      */
     antialias?: boolean;
+    /**
+     * 是否开启 HDR 支持
+     * @description
+     * 开启后渲染管线会使用 `THREE.HalfFloatType` 作为输出类型，
+     * 以支持更高的动态范围，避免高光过曝等问题。
+     * 会带来一定的性能与显存开销。
+     *
+     * 最终是否生效还取决于设备/浏览器能力：仅当同时满足
+     * “显示器支持高动态范围（`(dynamic-range: high)`）”与“设备支持 WebGPU”时才会真正开启。
+     * @default `false`
+     */
     enableHDR?: boolean;
     /**
      * 屏幕渲染区域
@@ -121,6 +132,10 @@ interface FiveInitArgs {
     topview?: ControllerCustomInitTypes["Topview"];
     /** 地图模式下的特定参数 */
     mapview?: ControllerCustomInitTypes["Mapview"];
+    /** VR眼镜模式下的特定参数 */
+    vrPanorama?: ControllerCustomInitTypes["VRPanorama"];
+    /** XR 全景模式（WebXR）下的特定参数 */
+    xrPanorama?: ControllerCustomInitTypes["XRPanorama"];
     /**
      * 模式间切换时的过度动画时间
      * @description
@@ -155,7 +170,23 @@ interface FiveInitArgs {
      */
     powerPreference?: 'high-performance' | 'low-power' | 'default';
     /**
-     * 是否使用webgl2渲染执行环境, 默认值 false
+     * 强制使用 WebGL2 回落后端
+     * @description
+     * `three` 的 WebGPU 后端目前不支持 WebXR（`THREE.XRManager` 会直接抛错），
+     * 因此需要进入 XR（VR 眼镜）时必须传入 `forceWebGL: true`。
+     *
+     * 该开关只在 renderer 构造期生效，**运行时无法切换后端**。
+     * 业务侧的设备检测必须发生在 `new Five()` 之前。
+     *
+     * 代价：
+     * - 点云走 NodeMaterial 路径而非 compute 光栅化
+     * - 3DGS 只能走 CPU 排序（`RASTER_CPU_SORT`）
+     * - `enableHDR` 不再生效（XR projection layer 固定 RGBA8）
+     * - 如果设置了 `renderer` 参数则不生效，请对传入的 renderer 自行设置
+     */
+    forceWebGL?: boolean;
+    /**
+     * @deprecated 在 five-webgpu 中无效（未接线）。需要 WebGL2 后端请使用 `forceWebGL`。
      */
     webgl2?: boolean;
     /**

package/five/application/mode.d.ts

@@ -5,7 +5,8 @@
  * - **Floorplan**: 模型查看模式
  * - **Topview**: 户型图模式
  * - **Mapview**: 地图模式
- * - **VRPanorama**: VR眼镜模式
+ * - **VRPanorama**: VR眼镜模式（手机 Cardboard 分屏）
+ * - **XRPanorama**: VR 硬件（WebXR）模式，需 `forceWebGL`
  */
 type Mode = 
 /** 模型查看模式 */
@@ -16,6 +17,12 @@ type Mode =
 "Mapview" | 
 /** 全景图游走模式 */
 "Panorama" | 
+/** VR盒子模式 */
+"VRPanorama" | 
+/**
+ * XR模式
+ */
+"XRPanorama" | 
 /** 模型游走模式 */
 "Model";
 declare function isThirdPersonMode(mode: Mode): boolean;

package/five/cardboard/helper.d.ts

@@ -0,0 +1,2 @@
+declare function createHelper(): HTMLDivElement;
+export { createHelper };

package/five/cardboard/index.d.ts

@@ -0,0 +1,13 @@
+import * as THREE from "three/webgpu";
+import { Sensor } from "./sensor";
+declare class Cardboard {
+    renderer: THREE.WebGPURenderer;
+    sensor: Sensor;
+    scale: number;
+    private cameraL;
+    private cameraR;
+    constructor(renderer: THREE.WebGPURenderer);
+    render(scene: THREE.Scene, camera: THREE.Camera): void;
+    dispose(): void;
+}
+export { Cardboard };

package/five/cardboard/sensor.d.ts

@@ -0,0 +1,158 @@
+import * as THREE from "three/webgpu";
+declare class SensorSample {
+    sample: THREE.Vector3;
+    timestampS: number;
+    constructor(sample?: THREE.Vector3, timestampS?: number);
+    set(sample: THREE.Vector3, timestampS: number): void;
+    copy(sensorSample: SensorSample): void;
+}
+/**
+ * An implementation of a simple complementary filter, which fuses gyroscope and
+ * accelerometer data from the 'devicemotion' event.
+ *
+ * Accelerometer data is very noisy, but stable over the long term.
+ * Gyroscope data is smooth, but tends to drift over the long term.
+ *
+ * This fusion is relatively simple:
+ * 1. Get orientation estimates from accelerometer by applying a low-pass filter
+ *    on that data.
+ * 2. Get orientation estimates from gyroscope by integrating over time.
+ * 3. Combine the two estimates, weighing (1) in the long term, but (2) for the
+ *    short term.
+ */
+declare class ComplementaryFilter {
+    kFilter: number;
+    isDebug: boolean;
+    currentAccelMeasurement: SensorSample;
+    currentGyroMeasurement: SensorSample;
+    previousGyroMeasurement: SensorSample;
+    filterQ: THREE.Quaternion;
+    previousFilterQ: THREE.Quaternion;
+    accelQ: THREE.Quaternion;
+    isOrientationInitialized: boolean;
+    estimatedGravity: THREE.Vector3;
+    measuredGravity: THREE.Vector3;
+    gyroIntegralQ: THREE.Quaternion;
+    constructor(kFilter: number, isDebug: boolean);
+    addAccelMeasurement(vector: THREE.Vector3, timestampS: number): void;
+    addGyroMeasurement(vector: THREE.Vector3, timestampS: number): void;
+    getOrientation(): THREE.Quaternion;
+    private run_;
+    private accelToQuaternion_;
+    private gyroToQuaternionDelta_;
+}
+/**
+ * Given an orientation and the gyroscope data, predicts the future orientation
+ * of the head. This makes rendering appear faster.
+ *
+ * Also see: http://msl.cs.uiuc.edu/~lavalle/papers/LavYerKatAnt14.pdf
+ *
+ * @param predictionTimeS - time from head movement to the appearance of
+ * the corresponding image.
+ */
+declare class PosePredictor {
+    predictionTimeS: number;
+    isDebug: boolean;
+    previousQ: THREE.Quaternion;
+    previousTimestampS: number | null;
+    deltaQ: THREE.Quaternion;
+    outQ: THREE.Quaternion;
+    constructor(predictionTimeS: number, isDebug: boolean);
+    getPrediction(currentQ: THREE.Quaternion, gyro: THREE.Vector3, timestampS: number): THREE.Quaternion;
+}
+declare class Pose {
+    angularAcceleration: Float32Array | null;
+    angularVelocity: Float32Array | null;
+    linearAcceleration: Float32Array | null;
+    linearVelocity: Float32Array | null;
+    orientation: Float32Array | null;
+    position: Float32Array | null;
+    constructor();
+}
+declare class FrameData {
+    leftProjectionMatrix: Float32Array;
+    leftViewMatrix: Float32Array;
+    pose: Pose;
+    rightProjectionMatrix: Float32Array;
+    rightViewMatrix: Float32Array;
+    timestamp: number;
+    constructor();
+}
+declare class FieldOfView {
+    leftDegrees: number;
+    rightDegrees: number;
+    upDegrees: number;
+    downDegrees: number;
+    constructor();
+}
+/**
+ * The pose sensor, implemented using DeviceMotion APIs.
+ */
+declare class Sensor {
+    viewer: {
+        id?: string;
+        label?: string;
+        fov: number;
+        interLensDistance: number;
+        baselineLensDistance: number;
+        screenLensDistance: number;
+        distortionCoefficients: [number, number];
+        inverseCoefficients: number[];
+    };
+    device: {
+        widthMeters: number;
+        heightMeters: number;
+        bevelMeters: number;
+    };
+    depthNear: number;
+    depthFar: number;
+    yawOnly: boolean;
+    accelerometer: THREE.Vector3;
+    gyroscope: THREE.Vector3;
+    filter: ComplementaryFilter;
+    posePredictor: PosePredictor;
+    isFirefoxAndroid: boolean;
+    isIOS: boolean;
+    isDeviceMotionInRadians: boolean;
+    isWithoutDeviceMotion: boolean;
+    filterToWorldQ: THREE.Quaternion;
+    inverseWorldToScreenQ: THREE.Quaternion;
+    worldToScreenQ: THREE.Quaternion;
+    originalPoseAdjustQ: THREE.Quaternion;
+    resetQ: THREE.Quaternion;
+    private previousTimestampS;
+    private orientationOut_;
+    private _deviceOrientationQ?;
+    private deviceOrientationFixQ?;
+    private deviceOrientationFilterToWorldQ?;
+    constructor(kFilter: number, predictionTime: number, yawOnly: boolean, isDebug: boolean);
+    getPosition(): any;
+    getOrientation(): Float32Array<ArrayBufferLike>;
+    getPose(): Pose;
+    resetPose(): void;
+    getFrameData(frameData: FrameData): FrameData;
+    start(): () => void;
+    getEyeOffset(): {
+        left: number[];
+        right: number[];
+    };
+    getEyeProjectionMatrix(): {
+        left: number[];
+        right: number[];
+    };
+    getEyeFieldOfView(): {
+        left: FieldOfView;
+        right: FieldOfView;
+    };
+    private onDeviceOrientation_;
+    private onDeviceMotion_;
+    private updateDeviceMotion_;
+    private onOrientationChange_;
+    /**
+     * This is only needed if we are in an cross origin iframe on iOS to work around
+     * this issue: https://bugs.webkit.org/show_bug.cgi?id=152299.
+     */
+    private onMessage_;
+    private setScreenTransform_;
+}
+export { Sensor, Pose, FrameData, FieldOfView };

package/five/controllers/base.d.ts

@@ -30,6 +30,8 @@ interface BaseControllerInitArgs {
     extraElements: HTMLElement[];
     imageOptions: ImageOptions;
     enableWheel: boolean;
+    /** 是否开启 HDR 支持，详见 {@link FiveInitArgs.enableHDR} */
+    enableHDR: boolean;
     videoTexture: THREE.VideoTexture;
     initial: {
         /** 初始化状态 */
@@ -65,6 +67,7 @@ declare class BaseController extends Subscribe<ControllerEventTypes> implements
     videoTexture: THREE.VideoTexture;
     extraElements: HTMLElement[];
     enableWheel: boolean;
+    enableHDR: boolean;
     initial: {
         state: Partial<State>;
         currentState: State;

package/five/controllers/events.d.ts

@@ -1,4 +1,4 @@
-import { GestureEvent, BaseEvent, StateEvent, IntersectEvent, PanoEvent, PanoTextureEvent, XRSessionEvent, XRGestureEvent, XRControllerEvent } from "../utils/event";
+import { GestureEvent, BaseEvent, StateEvent, IntersectEvent, PanoEvent, PanoPrepareEvent, PanoTextureEvent, XRSessionEvent, XRGestureEvent, XRControllerEvent } from "../utils/event";
 type ControllerEventTypes = {
     /** 手势 滑动屏幕 */
     "gesture.pan"(event: GestureEvent): void;
@@ -16,8 +16,8 @@ type ControllerEventTypes = {
     "gesture.mousemove"(event: GestureEvent): void;
     /** 手势 惯性 */
     "gesture.momentum"(event: GestureEvent): void;
-    /** 手势开始 */
-    "gesture.create"(event: GestureEvent): void;
+    /** 手势被触发 */
+    "gesture.fire"(event: GestureEvent): void;
     /** 模态切换动画 开始 */
     "initAnimation.start"(event: StateEvent): void;
     /** 模态切换动画 结束 */
@@ -29,6 +29,8 @@ type ControllerEventTypes = {
     "pano.select"(event: PanoEvent): void;
     /** 请求点位 */
     "pano.request"(event: PanoEvent): void;
+    /** 准备点位 */
+    "pano.prepare"(event: PanoPrepareEvent): void;
     /** 运动去点位 */
     "pano.moveTo"(event: PanoEvent): void;
     /** 运动点位过程 */

package/five/controllers/panorama.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from "three/webgpu";
 import { NetworkResponse, NetWorkMeta } from "../utils/ajax";
-import { ModelScene, PBMPanoPicture } from "../model";
+import { ModelScene, PBMPanoPicture, PBMPanoGainmap } from "../model";
 import { Works, WorkObserver } from "../work";
 import { Pano, PanoId } from "../utils/pano";
 import { TextureLoader } from "../texture/loader";
@@ -84,7 +84,7 @@ declare class PanoramaController extends PanoramaLikeController implements Requi
     protected pendingTextureTask?: {
         panoId: PanoId;
         hash: string;
-        onLoad(colorResponse: NetworkResponse<THREE.Texture, NetWorkMeta[]>, hdrConfig?: any): void;
+        onLoad(colorResponse: NetworkResponse<THREE.CubeTexture, NetWorkMeta[]>, gainmap?: PBMPanoGainmap): void;
         onError(error: Error): void;
     };
     protected panoVideo: PanoVideo;

package/five/controllers/vrPanorama.d.ts

@@ -0,0 +1,56 @@
+import { CameraPose } from "../core/camera";
+import { Cardboard } from "../cardboard";
+import { State } from "../types/state";
+import { Pose } from "../types/pose";
+import { BaseControllerInitArgs } from "./base";
+import { PanoramaController, PanoramaControllerCustomInitArgs, PanoramaControllerInitArgs } from "./panorama";
+import { PanoCircleMeshInterface } from "../types/panoCircleMeshInterface";
+interface VRPanoramaControllerCustomInitArgs extends Omit<PanoramaControllerCustomInitArgs, "maxLatitude" | "minLatitude"> {
+}
+declare const defaultVRPanoramaControllerCustomInitArgs: Required<VRPanoramaControllerCustomInitArgs>;
+type VRPanoramaControllerInitArgs = BaseControllerInitArgs & VRPanoramaControllerCustomInitArgs;
+declare class VRPanoramaController extends PanoramaController implements Required<VRPanoramaControllerInitArgs> {
+    protected cardboard: Cardboard;
+    protected helperElement?: HTMLElement;
+    protected activePanoMesh?: PanoCircleMeshInterface;
+    protected activeTime?: number;
+    static parseArgs(args: VRPanoramaControllerInitArgs): Required<PanoramaControllerInitArgs>;
+    static initAnimationEndState(args: VRPanoramaControllerInitArgs): State;
+    constructor(args: VRPanoramaControllerInitArgs);
+    updateConfiguration(args: VRPanoramaControllerCustomInitArgs): boolean;
+    /** 析构函数 */
+    destroy(): void;
+    /** 是否准备好，即不在用户操作中，并且不再动画中 */
+    isReady(): boolean;
+    /** 生命周期： 更新屏幕渲染尺寸 */
+    updateRenderSize(): void;
+    /** 转动摄像头 */
+    updateCamera(pose: Partial<Pose>, duration: number, userAction: boolean): Promise<void>;
+    /** 通过帧动画转动摄像头 */
+    updateCameraWithKeyframes(keyframes: {
+        progress: number;
+        value: Pose;
+        key?: string;
+    }[], duration: number, userAction: boolean): Promise<void>;
+    /** 时间迭代 */
+    updateTime(time: number, deltaTime: number, ...args: any[]): void;
+    /** 生命周期 渲染 */
+    render(): boolean;
+    /**
+     * 同步修改相机参数
+     * @param cameraPose
+     */
+    protected setCamera(cameraPose?: Partial<CameraPose>): void;
+    /** 删除提示层 */
+    protected destroyHelper(): void;
+    /** 设置提示层大小 */
+    protected updateHelperElementSize(): void;
+    /** 计算看向方向的射线碰撞 */
+    protected intersect(time: number): PanoCircleMeshInterface | undefined;
+    protected onPanGesture(): void;
+    protected onTapGesture(): void;
+    protected onPinchGesture(): void;
+    protected onMouseMove(): void;
+    protected onMouseOut(): void;
+}
+export { VRPanoramaController, VRPanoramaControllerInitArgs, VRPanoramaControllerCustomInitArgs, defaultVRPanoramaControllerCustomInitArgs, };