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

package/five/gaussian-splatting/pipelines/gpuSortPipeline.d.ts

@@ -0,0 +1,98 @@
+import * as THREE from 'three/webgpu';
+import { GSplatPipeline, type PipelineFrameParams, type PipelineIndexSource } from './gsplatPipeline';
+/**
+ * GPU 排序管线（Pipeline_Mode = `RASTER_GPU_SORT`）
+ *
+ * 组合 `SortAdapter` + `RadixSortModule`：一次 `requestSort` 在**同一帧内**完成
+ * Distance_Range 计算 → keygen → radix sort → Order_Texture 写入（Requirement 12.1 / 12.2），
+ * 结果经 Order_Texture 供材质顶点阶段 `textureLoad` 取点。
+ *
+ * 与 CPU 管线的关键差异：
+ * - 排序是**同步生效**的（本帧 submit、本帧绘制读取），因此没有 generation 配对、没有
+ *   Reorder_CPU、没有 `splatIndex` 上传（Requirement 12.4）；
+ * - 因为同帧生效，也就**不需要主动请求额外的 Render_Frame**（Requirement 12.3）——
+ *   `CpuSortPipeline` 那个 `onNeedsRender` 回调在这里没有对应物；
+ * - Data_Texture 必须在排序前就位，这由 Render_Mesh 把 `assembler.assemble()` 提前到排序之前
+ *   保证（Requirement 12.5）。
+ *
+ * 不可用性（`unusable`）汇聚三个来源，经 `checkLimits` 统一走「解析为 `RASTER_CPU_SORT` →
+ * 下一帧 `syncPipelineMode` 切换」这条降级路径（Requirement 15.4 / 16.1 / 16.3），
+ * 本类内部不写单独的降级分支。
+ */
+export declare class GpuSortPipeline extends GSplatPipeline {
+    /** 原生设备。取不到（非 WebGPU 后端）时管线直接进入失败态。 */
+    private readonly device;
+    /** 3DGS ↔ 通用排序模块的对接层。构造失败或 device lost 后为 null。 */
+    private sortAdapter;
+    /** compute pipeline（keygen / radix sort / prefix sum）创建失败（Requirement 16.1）。 */
+    private _pipelineCreateFailed;
+    /** `GPUDevice` 触发 lost 事件（Requirement 16.3）。 */
+    private _deviceLost;
+    /** `dispose()` 之后忽略迟到的 `device.lost` 回调，避免在已释放对象上写状态。 */
+    private _disposed;
+    /** 是否已产出过至少一次有效排序结果（Order_Texture 已写入）。 */
+    private _hasSorted;
+    /** 最近一次成功排序时的 Total_Points（= Order_Texture 当前承载的点数）。 */
+    private _sortedPoints;
+    /** 本帧 Total_Points，由 `frameUpdate` 记录。初值 0 使首个 `frameUpdate` 之前不绘制。 */
+    private _frameTotalPoints;
+    /** 首次排序前充当 `indexSource` 的占位纹理，按需懒建。 */
+    private placeholderTexture;
+    constructor(renderer: THREE.WebGPURenderer);
+    /** 自行在 GPU 上排序：Render_Mesh 因此跳过 Reorder_CPU、Layout_Generation 与 `splatIndex` 写入。 */
+    get usesGpuSort(): boolean;
+    /**
+     * 管线是否已不可用。为真时 `checkLimits` 返回「GPU 管线已失效」，
+     * 下一帧的 `syncPipelineMode` 把模式解析为 `RASTER_CPU_SORT` 并完成切换。
+     *
+     * 三个来源：
+     * - `_pipelineCreateFailed`：compute pipeline 创建失败（Requirement 16.1）
+     * - `_deviceLost`：`GPUDevice` 丢失（Requirement 16.3）
+     * - `sortAdapter.unusable`：keygen dispatch 规模超设备单维上限。keygen shader 只用 `gid.x`
+     *   编址，无法像排序模块那样退化为 2D dispatch，其承载上限（约 1677 万点）低于
+     *   `checkLimits` 按 2D dispatch 允许的规模，所以这一项必须由本 getter 补上——
+     *   `checkLimits` 自己检不出来。
+     */
+    get unusable(): boolean;
+    /**
+     * 本帧可绘制实例数。
+     *
+     * 资源就绪且已有排序结果时为 Total_Points（Requirement 6.5），否则 0。取
+     * `min(本帧点数, 最近一次排序的点数)` 是一层保护：若布局在排序后变大而本帧尚未重排，
+     * 多出来的实例在 Order_Texture 里没有对应条目，不绘制它们比绘制越界读到的 0 更正确。
+     *
+     * 返回 0 的情形：管线不可用（Requirement 16.1 / 16.3）、尚无有效排序结果
+     * （Requirement 8.10，含刚切换到本管线的那几帧）、Total_Points 为 0（Requirement 16.5）。
+     */
+    get instanceCount(): number;
+    /**
+     * 绘制索引来源：Order_Texture（Requirement 10.6）。
+     *
+     * Order_Texture 在点数变化时会被 `SortAdapter` 重建（换掉纹理对象），所以 Render_Mesh 需每帧
+     * 取用并按引用同步给材质，不能只在首帧绑定一次。
+     */
+    get indexSource(): PipelineIndexSource;
+    /**
+     * 请求排序：自建 encoder 录入整条排序链路，一次 submit，同帧生效。
+     *
+     * **不做节流判断**——是否调用由外层 Sort_Throttle 决定（Requirement 7.1）。
+     * 也不请求额外的 Render_Frame：结果对本帧绘制即刻可见，five 的按需渲染语义不变
+     * （Requirement 12.3）。
+     *
+     * 用**自建 encoder** 而不是渲染器的当前 encoder：three 的渲染 encoder 生命周期不对外开放，
+     * 且排序必须整体排在本帧绘制命令之前。独立提交靠队列顺序保证这一点。
+     */
+    requestSort(ctx: PipelineFrameParams): void;
+    /**
+     * 每帧记录本帧点数，供 `instanceCount` 判定。
+     *
+     * GPU 路径没有 CPU 路径那样的「把异步结果修正到当前布局」工作（Order_Texture 在
+     * `requestSort` 里已就地写好），所以这里只有一次赋值。
+     */
+    frameUpdate(ctx: PipelineFrameParams): void;
+    /** 释放全部 GPU 资源：`SortAdapter`（含 Key_Buffer、uniform、Order_Texture、排序模块）与占位纹理。 */
+    dispose(): void;
+    /** 释放 `SortAdapter` 并清零排序状态，使 `instanceCount` 立即回到 0。 */
+    private releaseAdapter;
+    private ensurePlaceholderTexture;
+}

package/five/gaussian-splatting/pipelines/gsplatPipeline.d.ts

@@ -0,0 +1,104 @@
+import type * as THREE from 'three/webgpu';
+import type { Camera } from '../../core/camera';
+import type { PBMGaussianSplattingObject } from '../../model/objects/pbmGaussianSplattingObject';
+import type { SplatAssembler } from '../splatAssembler';
+import type { TransformStore } from '../transformStore';
+/**
+ * 绘制索引来源：管线告诉 Render_Mesh「第 i 个实例要绘制的全局点索引 P 从哪里取」。
+ * - `attribute`   ：CPU 排序路径，P 来自 `splatIndex` 实例属性
+ * - `orderTexture`：GPU 排序路径，P 来自 R32UI 的 Order_Texture
+ *
+ * 新增管线实现时在此联合类型上扩展分支，Render_Mesh 按 `kind` 绑定，不做 `instanceof` 判断。
+ */
+export type PipelineIndexSource = {
+    kind: 'attribute';
+    attribute: THREE.InstancedBufferAttribute;
+} | {
+    kind: 'orderTexture';
+    texture: THREE.Texture;
+};
+/**
+ * 每帧调用参数（params bag）。
+ *
+ * Render_Mesh 持有**唯一一个**实例，每帧填字段后传给管线，以避免每个 Render_Frame 产生新分配
+ * （Requirement 10.7）。因此实现方**不得保留该对象或其字段的引用**：字段内容在下一帧会被覆写，
+ * 需要跨帧使用的数据必须在调用内自行取值或拷贝。
+ */
+export interface PipelineFrameParams {
+    /** 本帧相机（five Camera，含 `matrixWorld` 与投影矩阵）。 */
+    camera: Camera;
+    /** 当前布局中的 3DGS 对象，顺序与 assembler / transformStore 一致。 */
+    objects: readonly PBMGaussianSplattingObject[];
+    /** 大数据纹理组装器，本帧已完成 assemble。 */
+    assembler: SplatAssembler;
+    /** 变换存储（GPU 纹理 + 排序用数组）。 */
+    transformStore: TransformStore;
+    /** 当前布局总点数（`assembler.totalPoints`）。 */
+    totalPoints: number;
+}
+/**
+ * 3DGS 渲染管线抽象基类。
+ *
+ * Render_Mesh 唯一依赖的契约（Requirement 10.1 / 10.2）：排序、绘制索引来源、绘制实例数、
+ * 材质取点方式、资源释放。按 Pipeline_Mode 在实现间整体切换，Render_Mesh 不引用 Sort_Worker、
+ * Radix_Sort_Module、Sort_Adapter 或任何 WebGPU 资源。
+ *
+ * 采用**抽象基类而非纯接口**（Requirement 10.3）：公共状态（`renderer` / `inputsDirty`）与
+ * 能力 getter 上提到基类，`markInputsDirty` / `requestSort` / `frameUpdate` / `dispose` 一律给
+ * 无副作用默认实现，使 Render_Mesh 可无条件调用而不必按实现类型分支。
+ *
+ * 后续阶段新增管线（如 `COMPUTE_GPU_SORT` 软光栅化）只需继承本类并在 Pipeline_Mode 解析里加一个
+ * 分支，Render_Mesh 的消费代码与切换机制不用改（Requirement 10.9）。
+ */
+export declare abstract class GSplatPipeline {
+    /** three 渲染器。取原生 `GPUDevice` / `GPUTexture` 的入口，由各实现按需使用。 */
+    protected readonly renderer: THREE.WebGPURenderer;
+    /**
+     * 排序输入是否为脏（对象集合变化、某对象 transform 变化、管线刚切换）。
+     * 由 `markInputsDirty()` 置位，实现在完成排序后自行清除。初值为 true，使首帧必定排序。
+     */
+    protected inputsDirty: boolean;
+    constructor(renderer: THREE.WebGPURenderer);
+    /**
+     * 是否自行在 GPU 上完成排序。
+     * 为 true 时 Render_Mesh 跳过 Reorder_CPU、Layout_Generation 与 `splatIndex` 写入。
+     */
+    get usesGpuSort(): boolean;
+    /**
+     * 材质是否应启用 Order_Texture 取点。
+     * 由 `usesGpuSort` 派生，实现类通常无需单独覆盖。
+     */
+    get requiresOrderTexture(): boolean;
+    /**
+     * 本帧可绘制实例数。资源未就绪、排序失败或尚无有效排序结果时返回 0
+     * （Render_Mesh 据此降级为空绘制而不中断渲染循环）。
+     */
+    abstract get instanceCount(): number;
+    /** 绘制索引来源。Render_Mesh 按 `kind` 绑定 Order_Texture 或 `splatIndex` 实例属性。 */
+    abstract get indexSource(): PipelineIndexSource;
+    /**
+     * 通知管线排序输入已变化（布局或 transform 变化、管线刚切换）。
+     * 基类仅记录脏标记；实现可覆盖以追加动作（如令 worker 重传输入），覆盖时需调用 `super`。
+     */
+    markInputsDirty(): void;
+    /**
+     * 请求排序。**不做节流判断**——是否调用由外层 Sort_Throttle 决定（Requirement 7.1）。
+     *
+     * 基类为无副作用空实现，使将来某个无需每帧排序的管线（例如全静态场景的预排序管线）可直接继承。
+     *
+     * @param _ctx 每帧参数，跨帧复用，不得保留引用。
+     */
+    requestSort(_ctx: PipelineFrameParams): void;
+    /**
+     * 每帧无条件调用（排序之后、绘制之前），供实现同步材质参数、上传实例属性等。
+     * 基类为无副作用空实现。
+     *
+     * @param _ctx 每帧参数，跨帧复用，不得保留引用。
+     */
+    frameUpdate(_ctx: PipelineFrameParams): void;
+    /**
+     * 释放管线持有的全部资源（Worker、GPU buffer、纹理等，Requirement 10.8）。
+     * 基类为无副作用空实现。
+     */
+    dispose(): void;
+}

package/five/gaussian-splatting/pipelines/pipelineMode.d.ts

@@ -0,0 +1,42 @@
+import type * as THREE from 'three/webgpu';
+/** 由设备能力自动解析。永不作为 Current_Pipeline_Mode 出现。 */
+export declare const GSPLAT_PIPELINE_AUTO = 0;
+/** TSL 硬件光栅化 + wasm worker 排序（现状，WebGL2 路径）。 */
+export declare const GSPLAT_PIPELINE_RASTER_CPU_SORT = 1;
+/** TSL 硬件光栅化 + GPU compute radix sort。 */
+export declare const GSPLAT_PIPELINE_RASTER_GPU_SORT = 2;
+/**
+ * GPU 管线的可用性探针。
+ *
+ * 只声明 `checkLimits` 真正需要的那一个成员，避免 `pipelineMode.ts` 反向依赖
+ * `GSplatPipeline` / `GpuSortPipeline` 的具体类型（`GpuSortPipeline` 的
+ * `unusable` getter 结构上满足这个约定）。
+ */
+export interface GSplatPipelineUsability {
+    readonly unusable?: boolean;
+}
+/**
+ * 按当前点数检查设备 limits 是否支撑 GPU 排序管线。
+ *
+ * @param device 已就绪的 `GPUDevice`
+ * @param totalPoints 当前场景的 Total_Points
+ * @param activePipeline 当前生效的管线（可选）。其 `unusable` 为真时（compute pipeline
+ *   创建失败或 device lost）一并视为不可用，使运行期失败复用同一条降级路径。
+ * @returns 不可用时返回可读的原因字符串，可用时返回 `null`
+ */
+export declare function checkLimits(device: GPUDevice, totalPoints: number, activePipeline?: GSplatPipelineUsability | null): string | null;
+/**
+ * 把 Requested_Pipeline_Mode 解析为 Current_Pipeline_Mode。
+ *
+ * - `AUTO`：后端为 WebGPU、`GPUDevice` 就绪且 limits 通过时选 `RASTER_GPU_SORT`，否则 `RASTER_CPU_SORT`
+ * - 显式 `RASTER_GPU_SORT`：前提不满足时静默降级为 `RASTER_CPU_SORT`（不抛错）
+ * - 解析过程抛异常：`console.warn` 并返回 `RASTER_CPU_SORT`
+ *
+ * 返回值永不为 `GSPLAT_PIPELINE_AUTO`。
+ *
+ * @param requested Requested_Pipeline_Mode
+ * @param renderer 当前渲染器
+ * @param totalPoints 当前场景的 Total_Points，用于按实际规模检查 limits
+ * @param activePipeline 当前生效的管线，透传给 `checkLimits` 以纳入其 `unusable` 状态
+ */
+export declare function resolvePipelineMode(requested: number, renderer: THREE.WebGPURenderer, totalPoints: number, activePipeline?: GSplatPipelineUsability | null): number;

package/five/gaussian-splatting/pipelines/sortThrottle.d.ts

@@ -0,0 +1,45 @@
+import * as THREE from 'three/webgpu';
+/**
+ * 排序节流器
+ *
+ * 只负责回答「本 Render_Frame 是否需要调用管线的排序」这一个问题：
+ * 不持有任何 GPU 资源，不引用排序模块，对 `GSplatPipeline` 的内部逻辑无侵入。
+ *
+ * 阈值语义与字段名沿用改造前 `PBMGaussianSplattingRenderMesh.shouldSort`，
+ * 使 `RASTER_CPU_SORT` 与 `RASTER_GPU_SORT` 两条管线的节流行为完全一致。
+ */
+export declare class SortThrottle {
+    /** 平移增量阈值（世界单位）：超过才重排。 */
+    sortCameraDistance: number;
+    /** 姿态相似度阈值（|quat 点积|）：低于才重排（0.99 ≈ 约 16° 内不重排）。 */
+    sortCameraCoorient: number;
+    /** 最小重排间隔（ms）：即使相机已明显变化也不超过此频率，0 = 不限。 */
+    sortMinIntervalMs: number;
+    /** 上次排序时的相机世界矩阵快照（尚未排序过时为 null）。 */
+    private prevMatrix;
+    /** 上次排序的时间戳（ms）。 */
+    private lastTime;
+    /** 是否已产生过至少一次排序结果。 */
+    private hasSorted;
+    /**
+     * 判定本帧是否需要排序。
+     *
+     * 判定顺序（与改造前实现一致，`inputsDirty` 优先于时间门）：
+     *   1. 尚未排序过，或排序输入已脏（对象集合 / transform 变化）→ 必须排序。
+     *      数据变了不重排会用旧布局的索引访问新布局的数据。
+     *   2. 距上次排序不足 `sortMinIntervalMs` → 不排序。
+     *   3. 无相机快照（理论上被步骤 1 覆盖，仅作兜底）→ 排序。
+     *   4. 相机位移超过 `sortCameraDistance`，或姿态相似度低于 `sortCameraCoorient` → 排序。
+     *
+     * @param camera 当前帧相机
+     * @param inputsDirty 对象集合或某对象 transform 是否发生变化
+     */
+    shouldSort(camera: THREE.Camera, inputsDirty: boolean): boolean;
+    /** 记录本次排序：快照相机矩阵与时间戳。排序被实际发起后调用。 */
+    markSorted(camera: THREE.Camera): void;
+    /**
+     * 重置节流状态，使下一帧必定重排。
+     * 管线切换时调用（切换后的新管线尚无任何排序结果）。
+     */
+    reset(): void;
+}

package/five/index.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="./declare" />
 
-import "./three-version-check";
 import "./certificates/hardware";
 export * from './model';
 export * from "./work";
@@ -18,10 +17,12 @@ export { imageURL as defaultImageURLTransform, type ImageURLOptions, type ImageU
 export { imageSupport } from "./utils/imageSupport";
 export { Motion, type MotionKeyframe, type MotionValue, type MotionConfig, type MotionInitalValue, type MotionCircle, } from "./utils/motion";
 export { isPanoId, panoEqual, panoParse, panoStringify, type PanoId, type Pano, } from "./utils/pano";
+export { type GainmapCfgData, } from "./utils/gainmap-data";
+export { type Clock, } from "./utils/clock";
 export { coordinatesToVector, vectorToCoordinates, headingToLongitude, longitudeToHeading, } from './utils/vectorCoordinates';
 export { draco, type Draco } from './utils/draco';
 export { makeBoundingVolume, isBoundingVolume, createDebugBoundingMesh, type BoundingVolume, type CullingVolume, type VolumePlaneIntersect, type BoundingVolumeJson, type BoxBoundingVolume, type BoxBoundingVolumeJson, type RegionBoundingVolume, type RegionBoundingVolumeJson, type SphereBoundingVolume, type SphereBoundingVolumeJson } from './utils/volume';
-export { type BaseEvent, type GestureEvent, type IntersectEvent, type ModeChangeEvent, type ModelTileEvent, type ModelEvent, type ModelSceneEvent, type NetworkResourceEvent, type ObjectEvent, type PanoEvent, type PanoTextureEvent, type RenderEvent, type StateEvent, type WorksEvent, type XRGestureEvent, type XRSessionEvent, type XRControllerEvent } from './utils/event';
+export { type BaseEvent, type GestureEvent, type IntersectEvent, type ModeChangeEvent, type ModelTileEvent, type ModelEvent, type ModelSceneEvent, type NetworkResourceEvent, type ObjectEvent, type PanoEvent, type PanoPrepareEvent, type PanoTextureEvent, type RenderEvent, type StateEvent, type WorksEvent, type XRGestureEvent, type XRMachineType, type XRSessionEvent, type XRControllerEvent } from './utils/event';
 export { type EasingFunction, } from './utils/easing';
 export { BoundingMesh, } from './meshes/boundingMesh';
 export { PanoCircleMesh, type PanoCircleMeshOptions, } from "./meshes/panoCircleMesh";
@@ -42,6 +43,7 @@ export { type IntersectMeshInterface } from "./types/intersectMeshInterface";
 export { type Intersection } from "./model/intersection";
 export { Five } from "./application/five";
 export { type Mode } from "./application/mode";
+export { GSPLAT_PIPELINE_AUTO, GSPLAT_PIPELINE_RASTER_CPU_SORT, GSPLAT_PIPELINE_RASTER_GPU_SORT, } from "./gaussian-splatting/pipelines/pipelineMode";
 export { PROXY_CONTROLLER_EVENT_NAMES, type EventTypes, type ControllerEventTypes, type EventCallback, } from "./application/events";
 export { type LegacyEventType, type GestureTypes, type WebXRControllerKey, type WebXRControllerType, type WebXRControllerParams, type WebXRAxesParams } from './application/events-legacy';
 export { type FiveInitArgs } from "./application/fiveInitArgs";
@@ -54,5 +56,9 @@ export { type FloorplanControllerCustomInitArgs } from "./controllers/floorplan"
 export { type ModelControllerCustomInitArgs } from "./controllers/model";
 export { type PanoramaControllerCustomInitArgs } from "./controllers/panorama";
 export { type TopviewControllerCustomInitArgs } from "./controllers/topview";
+export { type VRPanoramaControllerCustomInitArgs } from "./controllers/vrPanorama";
 export { type PanoramaLikeControllerCustomInitArgs } from "./controllers/panoramaLike";
 export { type MapviewControllerCustomInitArgs } from "./controllers/mapview";
+export { type XRPanoramaControllerCustomInitArgs } from "./controllers/xrPanorama";
+export { XRButton } from "./webxr/xrButton";
+export { type DeviceProfile, type DeviceProfileOverride } from "./webxr/deviceProfile";