@realsee/five-webgpu 1.0.0-alpha.4 → 1.0.0-alpha.6

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

@@ -0,0 +1,159 @@
+import * as THREE from 'three/webgpu';
+import { GSplatPipeline, type PipelineFrameParams, type PipelineIndexSource } from './gsplatPipeline';
+/**
+ * CPU 排序管线（Pipeline_Mode = `RASTER_CPU_SORT`）
+ *
+ * 对现有「Sort_Worker + WASM `_sort` + Reorder_CPU」链路的**封装搬移**：算法、数据流、
+ * generation 配对与 `splatIndex` 写入逻辑与改造前逐项一致（Requirement 9.1 / 9.2），
+ * 只是从 `PBMGaussianSplattingRenderMesh` 移入本类，使 Render_Mesh 只依赖
+ * `GSplatPipeline` 契约而不直接引用 Sort_Worker。
+ *
+ * 数据流：
+ *   1. `requestSort`：`assembler.extractSortInputs()`（世界坐标 + transformIndex）与
+ *      `transformStore.transforms`（20 float/对象）投给 worker，并带上 viewProj；
+ *   2. worker 回传 `depthIndex` → `applyDepthIndex` 存为 `orderData` 并按 generation 取回布局快照；
+ *   3. `frameUpdate`：`applyReorderCPU` 用「旧布局 → 当前布局」段表 remap，紧凑写入
+ *      `splatIndex` 实例属性（tile 增删时保持排序与大纹理映射一致、不闪烁）。
+ *
+ * 排序是**异步**的：本帧投递、后续帧消费结果，因此不依赖同帧的 `assembler.assemble()`。
+ *
+ * 能力：`usesGpuSort` 沿用基类默认 `false`（Render_Mesh 因此保留 Reorder_CPU 与
+ * Layout_Generation 路径），`indexSource` 为 `splatIndex` 实例属性（Requirement 10.5）。
+ */
+export declare class CpuSortPipeline extends GSplatPipeline {
+    private sortWorker;
+    /**
+     * 「已产出新排序结果、需要重绘」的回调。
+     *
+     * 搬移前这里是 `renderMesh.needsRender = true`；worker 回传发生在渲染循环之外，而 five 是
+     * 按需渲染，必须主动申请下一帧，否则结果要等到下次有人触发渲染才生效。由 Render_Mesh 在
+     * 构造管线时注入 `() => { this.needsRender = true; }` 以保持原行为。
+     */
+    private readonly onNeedsRender?;
+    /**
+     * splatIndex 实例属性：每实例一个全局点索引 P（CPU reorder 后紧凑写入）。材质顶点用
+     * `attribute('splatIndex')` 取点。初始容量 1，随排序结果按 2 的幂扩容
+     * （`ensureSplatIndexCapacity`）。
+     */
+    private splatIndex;
+    /** splatIndex 实例属性的当前容量（点数）；不足时按 2 的幂扩容。 */
+    private splatIndexCapacity;
+    /** 单调递增的排序请求代；每代记录其所基于的布局快照，回传时按代取回（防异步错配）。 */
+    private sortGeneration;
+    /** 当前排序输入是否已上传给 worker（场景/transform 变化时置 false 触发重传）。 */
+    private sortDataUploaded;
+    /**
+     * Sort_Worker 是否已进入不可恢复的失败态（WASM 加载失败）。一旦置位，`instanceCount`
+     * 恒为 0，Render_Mesh 持续降级为空绘制而不中断渲染循环（Requirement 16.4）。
+     */
+    private sortWorkerFailed;
+    /** 当前 order 长度（= 最近一次排序回传的 depthIndex 长度 = 该次排序时 vertexCount）。 */
+    private orderCount;
+    /**
+     * 最近一次排序回传的 depthIndex 副本（基于 orderBaseSnapshot 布局的全局点索引 P 的排列）。
+     * 作为 CPU reorder 的输入源：`applyReorderCPU` 用「orderBaseSnapshot → 当前布局」段表把它
+     * remap 到当前布局，紧凑写入 splatIndex 实例属性，从而在 tile 增删（布局变化）时保持排序与
+     * 大纹理映射一致、不闪烁。
+     */
+    private orderData;
+    /** order 内容变化（新排序回传）→ 需重跑 CPU reorder。 */
+    private orderDirty;
+    /** 布局变化（LOD 增删 / 场景重建）→ 需以新布局（新段表）重跑 CPU reorder。 */
+    private layoutDirty;
+    /** 当前存活实例数（= 最近一次 applyReorderCPU 写入 splatIndex 的点数）。 */
+    private aliveCount;
+    /** 当前 order 所基于的布局快照（= 该次排序发起时的布局）。 */
+    private orderBaseSnapshot;
+    /** generation → 该次排序发起时的布局快照。 */
+    private snapshotByGen;
+    /** viewProj 计算用临时矩阵（避免每帧分配）。 */
+    private scratchViewProj;
+    constructor(renderer: THREE.WebGPURenderer, onNeedsRender?: () => void);
+    /**
+     * 本帧可绘制实例数 = CPU reorder 写入的存活点数。
+     *
+     * worker 处于 WASM 失败态、或尚无有效排序结果（`orderCount <= 0`）时为 0，
+     * 与改造前 Render_Mesh 空绘制降级门中属于本管线的两项判据逐项一致
+     * （数据纹理是否就绪等资源判据仍留在 Render_Mesh 侧）。
+     */
+    get instanceCount(): number;
+    /**
+     * 绘制索引来源：`splatIndex` 实例属性。
+     *
+     * 注意扩容会**换掉属性对象**（`ensureSplatIndexCapacity` 新建更大的
+     * `InstancedBufferAttribute`），因此 Render_Mesh 需每帧比较身份，变化时重新
+     * `geometry.setAttribute('splatIndex', attribute)` 并同步 `_maxInstanceCount = attribute.count`。
+     */
+    get indexSource(): PipelineIndexSource;
+    /**
+     * 排序输入变脏（对象集合变化、某对象 transform 变化、管线刚切换）。
+     *
+     * 除基类的脏标记外还要清 `sortDataUploaded`（下次排序必定重传 worker 输入）并置
+     * `layoutDirty`（以当前布局的新段表重跑 reorder）。搬移前 `sortDataUploaded=false` 与
+     * `layoutDirty=true` 只在场景重建时置位、transform 变化只置 `sortInputsDirty`；此处合并后
+     * 输出不变：transform 变化帧本就因 `inputsDirty` 走 `postSortData`，且布局未变时段表
+     * 与上次等价，reorder 结果逐点相同。
+     */
+    markInputsDirty(): void;
+    /**
+     * 请求排序：必要时重传排序输入，然后投递本帧 viewProj。
+     * **不做节流判断**——是否调用由外层 Sort_Throttle 决定（Requirement 7.1）。
+     */
+    requestSort(ctx: PipelineFrameParams): void;
+    /**
+     * 每帧：order 或布局变化时把排序结果修正到当前布局（防 tile 增删闪烁）。
+     * 相机静止帧不重跑。
+     */
+    frameUpdate(ctx: PipelineFrameParams): void;
+    /** 终止 worker 并清理排序状态引用（Requirement 10.8）。 */
+    dispose(): void;
+    /**
+     * 确保 splatIndex 实例属性容量 >= requiredCount；不足时按 2 的幂扩容（保留旧内容）。
+     * 返回当前（可能是新建的）属性。
+     */
+    private ensureSplatIndexCapacity;
+    /**
+     * 把排序输入喂给 Sort_Worker：位置 + transformIndex 来自 assembler.extractSortInputs()，
+     * 变换矩阵来自 transformStore.transforms（20 float/对象，与 sort.cpp `_sort` 步长一致）。
+     * 每次上传 ++generation，回传时据此丢弃过期结果。
+     */
+    private postSortData;
+    /**
+     * 应用排序结果：
+     *   1. 保存 depthIndex 副本到 `orderData`（作为 CPU reorder 的输入源；实际 remap 在
+     *      frameUpdate 中由 applyReorderCPU 完成，此处不写 splatIndex）。
+     *   2. 置 orderDirty（新排序回传 → 需重跑 CPU reorder）。
+     *   3. 按 generation 取回该次排序真正基于的布局快照，作为 reorder 基准，并清理更旧快照
+     *      （worker 结果按 generation 单调返回，更旧快照不会再用到）。
+     * 保证：每次回传的 depthIndex 恒为「该代排序时 totalPoints」的一个排列，点数守恒。
+     */
+    private applyDepthIndex;
+    /** 捕获当前布局：assembler.regions 的 {object, start, count}（顺序即全局点区间顺序）。 */
+    private snapshotLayout;
+    /**
+     * 用「排序时旧布局 → 当前布局」构造 reorder 段表：
+     *   - 存活对象：{ oldStart, oldEnd, delta = 当前 start - 旧 start, removed: false }
+     *   - 被删对象：{ oldStart, oldEnd, delta: 0, removed: true }
+     * 段按 oldStart 升序（base 已按 start 升序）、区间不重叠；相邻同类段（同 removed 且
+     * removed 或 delta 相同、且首尾相接）合并以压低段数（供 applyReorderCPU 二分查找）。
+     */
+    private buildSegments;
+    /**
+     * 二分查找覆盖全局点索引 P 的段（段按 oldStart 升序、区间 [oldStart,oldEnd) 连续无重叠）。
+     * 找不到（P 越界，理论上不会发生）返回 null。
+     */
+    private findSegment;
+    /**
+     * CPU reorder：把最近一次排序回传的 depthIndex（orderData，基于 orderBaseSnapshot 旧布局的
+     * 全局点索引 P 的排列）用「旧布局 → 当前布局」段表 remap 到当前布局，紧凑写入 splatIndex 实例属性：
+     *   - 存活对象点 P → 写入 P + delta；
+     *   - 被删对象点（removed）→ 跳过（不写，实例数不计）。
+     * 从而在 tile 增删（布局变化）时保持排序顺序与大纹理映射一致、不闪烁（等价 five 的 ReorderPass）。
+     * 结果存活点数写入 `aliveCount`，由 Render_Mesh 经 `instanceCount` 取用。
+     *
+     * 搬移说明：原实现在此顺带写 `material.numPoints = assembler.totalPoints`（shader 端
+     * `P >= numPoints` 的保护性剔除）；该赋值与 `syncMaterialTextures` 中的同名赋值取值相同，
+     * 且新流程中 `syncMaterialTextures` 在本方法之前执行，故此处不再重复写材质（管线不触碰材质）。
+     */
+    private applyReorderCPU;
+}

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,6 +17,8 @@ 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';
@@ -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,6 @@ 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";