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

package/five/gaussian-splatting/gpu-sort/prefixSumKernel.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 并行前缀和（Blelloch exclusive scan）内核。
+ *
+ * 移植自 PlayCanvas `scene/graphics/prefix-sum-kernel.js`，改写为直接调用原生 WebGPU API。
+ * 与 3DGS 业务完全解耦：只认 `GPUDevice`、一个 uint32 storage buffer 与元素数。
+ *
+ * 结构：256 线程 / 512 元素每 workgroup，单 workgroup 内做 Blelloch scan，
+ * 每个 workgroup 的总和写入 blockSums；blockSums 元素数 > 1 时递归地对 blockSums 再做一次
+ * scan，最后逆序把各层 scan 结果加回下层。层数约为 `ceil(log₅₁₂(count))`，实践中不超过 3。
+ */
+export declare class PrefixSumKernel {
+    private readonly device;
+    /** 各 scan 层，index 0 为最外层（调用方的 buffer） */
+    private readonly passes;
+    /** 本次 encode 实际参与 dispatch 的层数（容量按高水位保留，规模按当前 count 走） */
+    private activeLevels;
+    /** 当前 pass 结构绑定的输入 buffer，identity 变化时需重建绑定组 */
+    private dataBuffer;
+    private readonly bindGroupLayout;
+    private readonly scanPipeline;
+    private readonly addBlockPipeline;
+    private readonly maxWorkgroupsPerDimension;
+    /** uniform 写入 scratch，避免每次 writeBuffer 新建 typed array */
+    private readonly uniformScratch;
+    constructor(device: GPUDevice);
+    /**
+     * 把 `dataBuffer` 的前 `count` 个 u32 原地替换为它们的 exclusive scan 结果。
+     *
+     * 只向传入的 encoder 录制命令，不做 submit；uniform 通过 `queue.writeBuffer` 更新，
+     * 队列顺序保证其在本 encoder 提交前生效。
+     *
+     * dispatch 次数为 `2L - 1`（L 层 scan + L-1 层 add_block_sums）。
+     *
+     * @param encoder 调用方的命令编码器
+     * @param dataBuffer 待 scan 的 storage buffer（usage 需含 STORAGE）
+     * @param count 参与 scan 的元素数
+     */
+    encode(encoder: GPUCommandEncoder, dataBuffer: GPUBuffer, count: number): void;
+    /**
+     * 按新的输入 buffer 与元素数调整 pass 结构。
+     *
+     * 仅在「输入 buffer 变了」或「元素数超出层 0 的已分配容量」时重建结构——后者同时覆盖了
+     * 「需要更多层」的情形（层数是 count 的单调函数）。规模缩小时保留高水位容量，只更新各层
+     * 的 count / dispatch 规模与生效层数（Requirement 14.6 / 14.7）。
+     *
+     * 相对 PlayCanvas 的一处修正：原实现只比较层数，元素数在同层数内增长时 blockSum 容量会
+     * 不足；这里以 `allocatedCount` 作为重建判据。
+     */
+    private resize;
+    /**
+     * 递归建层：本层建 blockSumBuffer / uniform / bindGroup，
+     * `workgroupCount > 1` 时对 blockSumBuffer 再递归建一层，并把本层标记为需要 add_block_sums。
+     */
+    private createPassesRecursive;
+    /**
+     * 单维 workgroup 数超过设备上限时退化为 2D dispatch：`x = floor(sqrt(n))`、`y = ceil(n / x)`。
+     * shader 用 `w_id.x + w_id.y * w_dim.x` 扁平化编号，多出来的 workgroup 由 elementCount
+     * 边界检查丢弃（Requirement 14.5-14.7 之外的 2.6）。
+     */
+    private findOptimalDispatchSize;
+    /** 释放各层 buffer 但保留 pipeline 与 layout（供 resize 重建结构时使用）。 */
+    private destroyPasses;
+    /** 释放全部自有 GPU 资源。pipeline / layout 无显式销毁 API，随对象一起被回收。 */
+    destroy(): void;
+}

package/five/gaussian-splatting/gpu-sort/radixSortModule.d.ts

@@ -0,0 +1,128 @@
+export declare const WORKGROUP_SIZE_X = 16;
+export declare const WORKGROUP_SIZE_Y = 16;
+/** 16 × 16 = 256 线程 / workgroup */
+export declare const THREADS_PER_WORKGROUP: number;
+/** 每线程处理 8 个元素 */
+export declare const ELEMENTS_PER_THREAD = 8;
+/** 256 × 8 = 2048 元素 / workgroup。与 Order_Texture 宽度相同，容量对齐策略利用了这一点 */
+export declare const ELEMENTS_PER_WORKGROUP: number;
+/** 每 pass 处理 4 bit */
+export declare const BITS_PER_PASS = 4;
+/** 1 << 4 = 16 个桶 */
+export declare const BUCKET_COUNT: number;
+export interface RadixSortResult {
+    /** 排序后的索引缓冲。前 elementCount 个元素为按 key 升序排列的原始下标。 */
+    sortedIndices: GPUBuffer;
+}
+export interface RadixSortOptions {
+    /**
+     * 允许在首个 pass 读完后覆写调用方的 keys，把它借用为 ping-pong 的一侧，省一份 N × 4。
+     * 借用的 buffer 不由本模块销毁；调用方需保证每次排序前自行重写 keys 内容。
+     */
+    destructiveKeys?: boolean;
+    /** 容量下限（元素数），纯分配参数，不参与排序，用于让调用方对齐分配粒度。 */
+    minCapacity?: number;
+}
+/**
+ * compute pipeline / shader module 创建失败时抛出的可识别错误。
+ * 上层（GpuSortPipeline）捕获它以置 `unusable` 标记并降级到 CPU 排序管线。
+ */
+export declare class RadixSortPipelineError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/** 判断任意异常是否为本模块的 pipeline 创建失败错误。 */
+export declare function isRadixSortPipelineError(error: unknown): error is RadixSortPipelineError;
+/**
+ * 通用 GPU radix sort（4-bit multipass）。
+ *
+ * 移植自 PlayCanvas `scene/graphics/radix-sort/compute-radix-sort-multipass.js`，改写为直接调用
+ * 原生 WebGPU API。与 3DGS 业务完全解耦：只认 `GPUDevice`、一个 uint32 key 缓冲、元素数与位宽，
+ * 不感知 splat、相机与纹理格式，也不含 key 计算与节流判断（Requirement 1）。
+ *
+ * 每 pass 三段：histogram → `PrefixSumKernel` exclusive scan → ranked scatter（reorder）。
+ * 不依赖 subgroup 特性；单维 workgroup 数超上限时退化为 2D dispatch。
+ */
+export declare class RadixSortModule {
+    private readonly device;
+    private readonly prefixSum;
+    private readonly histogramBindGroupLayout;
+    private readonly reorderBindGroupLayout;
+    private readonly histogramPipelineLayout;
+    private readonly reorderPipelineLayout;
+    private readonly histogramModule;
+    private readonly reorderModule;
+    /**
+     * pipeline 按 pass 索引缓存，`numBits` 变化时只补建缺失的 pass。
+     * reorder 的 `IS_LAST_PASS` 不由 pass 索引单独决定（同一 pass 在不同 numPasses 下可能是末 pass），
+     * 因此末 pass 变体单独一份缓存。
+     */
+    private readonly histogramPipelines;
+    private readonly reorderPipelines;
+    private readonly reorderLastPipelines;
+    private keys0;
+    /** 非破坏性模式下模块自有的第二份 keys；破坏性模式下为 null（改借用调用方 keys） */
+    private ownKeys1;
+    private values0;
+    private values1;
+    /** digit-major 的 workgroup 直方图：[digit * workgroupCount + workgroupId] */
+    private blockSums;
+    /** 已分配的元素数（2048 的整数倍），即高水位。blockSums 容量为 `16 × capacity / 2048` */
+    private capacity;
+    /** 当前缓冲集合是按破坏性模式分配的 */
+    private destructiveKeys;
+    /** 当前绑定组里引用的调用方 keys，identity 变化时需重建绑定组 */
+    private callerKeys;
+    private readonly uniformBuffer;
+    private readonly uniformScratch;
+    private writtenWorkgroupCount;
+    private writtenElementCount;
+    /** 绑定组缓存。键由参与的 buffer 组合而成，ping-pong 的组合数有限，缓存后不再每帧新建 */
+    private readonly histogramBindGroups;
+    private readonly reorderBindGroups;
+    private readonly maxWorkgroupsPerDimension;
+    constructor(device: GPUDevice);
+    /**
+     * 把 `keys` 的前 `elementCount` 个元素按升序排序，返回对应的索引缓冲。
+     *
+     * 只向传入的 encoder 录制命令，不做 submit——调用方可把 keygen、排序与后续拷贝录进同一个
+     * encoder 一次提交。uniform 通过 `queue.writeBuffer` 更新，队列顺序保证其在提交前生效。
+     *
+     * 结果落在哪个 ping-pong buffer 由 pass 数奇偶决定，不额外分配输出缓冲（Requirement 2.7）。
+     *
+     * @param encoder 调用方的命令编码器
+     * @param keys uint32 key 缓冲（usage 需含 STORAGE；`destructiveKeys` 时它会被当作 ping-pong 一侧写入）
+     * @param elementCount 本次参与排序的元素数
+     * @param numBits key 有效位数，应为 4 的倍数
+     * @param opts `destructiveKeys` 借用调用方 keys 省一份缓冲；`minCapacity` 仅影响分配
+     * @throws RadixSortPipelineError compute pipeline 创建失败
+     */
+    encode(encoder: GPUCommandEncoder, keys: GPUBuffer, elementCount: number, numBits: number, opts?: RadixSortOptions): RadixSortResult;
+    /** 释放全部自有 GPU 资源。借用的调用方 keys 不在此列。 */
+    destroy(): void;
+    /** 破坏性模式下 keys1 是调用方的 keys，否则是模块自有的那一份。 */
+    private resolveKeys1;
+    /**
+     * 按高水位分配 ping-pong 与 blockSums 缓冲。
+     *
+     * 容量向上对齐到 `ELEMENTS_PER_WORKGROUP`（2048）个元素，使 values 缓冲的字节长度天然是
+     * `2048 × 4 = 8192` 的整数倍，直接满足 Order_Texture 整行 `copyBufferToTexture` 的尺寸要求。
+     * 元素数缩小时保留高水位不缩容（Requirement 14.5 / 14.6）。
+     */
+    private ensureCapacity;
+    private destroyOwnBuffers;
+    /** 规模变化时才改写 uniform，避免每帧无谓的 writeBuffer。 */
+    private writeUniforms;
+    /**
+     * 单维 workgroup 数超过设备上限时退化为 2D dispatch：`x = floor(sqrt(n))`、`y = ceil(n / x)`。
+     * shader 用 `w_id.x + w_id.y * w_dim.x` 扁平化编号，补齐出的多余 workgroup 由 uniform 里的
+     * workgroupCount / elementCount 边界检查丢弃（Requirement 2.6）。
+     */
+    private findOptimalDispatchSize;
+    private getHistogramPipeline;
+    private getReorderPipeline;
+    /** 缓冲身份标签，用于绑定组缓存键。ping-pong 只在有限几个 buffer 间轮换。 */
+    private bufferTag;
+    private getHistogramBindGroup;
+    private getReorderBindGroup;
+    private clearBindGroupCache;
+}

package/five/gaussian-splatting/gpu-sort/shaders/prefixSum.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/gaussian-splatting/gpu-sort/shaders/radixHistogram.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/gaussian-splatting/gpu-sort/shaders/radixReorder.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/gaussian-splatting/gpu-sort/shaders/sortKeygen.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/gaussian-splatting/gpu-sort/sortAdapter.d.ts

@@ -0,0 +1,234 @@
+import * as THREE from 'three/webgpu';
+import type { Camera } from '../../core/camera';
+import type { PBMGaussianSplattingObject } from '../../model/objects/pbmGaussianSplattingObject';
+/**
+ * Order_Texture 宽度固定 2048，高 `ceil(totalPoints / 2048)`。
+ *
+ * 这个值与 `ELEMENTS_PER_WORKGROUP`、Data_Texture 宽度、材质里的 `ORDER_TEXTURE_WIDTH` 相同，
+ * 是本特性多处对齐关系的公共基数：排序结果缓冲按 2048 元素粒度分配，所以整行
+ * `copyBufferToTexture`（每行 8192 字节，是 256 的整数倍）天然不会越界。
+ */
+export declare const ORDER_TEXTURE_WIDTH = 2048;
+/** 当前帧全部 splat 的 Depth_Metric 取值区间。两端通常均为负值且 `minDist < maxDist`。 */
+export interface DistanceRange {
+    /** 最远处（Depth_Metric 最小值） */
+    minDist: number;
+    /** 最近处（Depth_Metric 最大值） */
+    maxDist: number;
+}
+/** Key_Bit_Width 自适应的计算结果。 */
+export interface KeyBitConfig {
+    /** 由点数推出的原始位数，已 clamp 到 [10, 20] */
+    numBits: number;
+    /** 对齐到 radix 边界（4 的倍数）后的实际位宽，取值 {12, 16, 20} */
+    keyBitWidth: number;
+    /** 量化桶数 `1 << keyBitWidth` */
+    bucketCount: number;
+}
+/**
+ * 按 Total_Points 自适应 Key_Bit_Width（Requirement 3.1 / 3.3）。
+ *
+ * `numBits = clamp(round(log2(totalPoints / 4)), 10, 20)` 让量化精度随场景规模增长，
+ * 再向上对齐到 4 的倍数，使 radix sort 的 pass 数（`keyBitWidth / 4`）为整数。
+ */
+export declare function computeKeyBitConfig(totalPoints: number): KeyBitConfig;
+/**
+ * 3DGS 与 `RadixSortModule` 之间的对接层。
+ *
+ * **本文件是 `gpu-sort/` 下允许与 3DGS 业务耦合的例外**（Requirement 1.2）：它引用 three 与 five
+ * 的模型类型，把 five 的 Data_Texture / Transform_Store 接到与业务无关的通用排序模块上。
+ *
+ * 职责分三块：
+ * 1. Distance_Range 计算（CPU，遍历各对象包围盒 8 角点）
+ * 2. Key_Bit_Width 自适应与 keygen compute pass（读 Data_Texture / Transform_Store 直接算 Sort_Key，
+ *    不经任何 CPU 侧中间数组）
+ * 3. 调用 `RadixSortModule` 并把排序结果 `copyBufferToTexture` 写入 Order_Texture
+ *
+ * 入口是 `encode`：一次调用把上述三步录进调用方的同一个 encoder，由调用方 submit。
+ */
+export declare class SortAdapter {
+    private readonly renderer;
+    private readonly device;
+    /** 通用排序模块。构造失败时其错误会被包装为 `RadixSortPipelineError` 向上抛出。 */
+    private readonly radixSort;
+    private readonly keygenBindGroupLayout;
+    private readonly keygenPipeline;
+    private readonly uniformBuffer;
+    /** KeygenUniforms 的 CPU 侧暂存，f32 / u32 两个视图共享同一段内存。 */
+    private readonly uniformScratch;
+    private readonly uniformF32;
+    private readonly uniformU32;
+    private keyBuffer;
+    /** 已分配的 key 元素数（2048 的整数倍） */
+    private keyCapacity;
+    private orderGpuTexture;
+    /** 包装 `orderGpuTexture` 的 three 纹理，供材质绑定。尺寸变化时与原生纹理一同重建。 */
+    private orderThreeTexture;
+    /** 当前 Order_Texture 的高度。与新算出的高度相同时复用，不同则销毁重建。 */
+    private orderTextureHeight;
+    /** `GPUTextureView` 缓存。three 侧纹理重建时旧 `GPUTexture` 被 GC，条目随之失效。 */
+    private readonly textureViewCache;
+    private keygenBindGroup;
+    private boundDataTexture;
+    private boundTransformTexture;
+    private boundKeyBuffer;
+    /** 诊断开关。见 `debugValidateOrder`。 */
+    private validateOrderEnabled;
+    /** 回读用 staging buffer。仅在诊断开启时惰性创建，关闭时销毁。 */
+    private stagingBuffer;
+    /** staging buffer 已分配的元素数（2048 的整数倍，高水位复用）。 */
+    private stagingCapacity;
+    /**
+     * 是否已有一次回读在途。
+     *
+     * `mapAsync` 期间的 buffer 不能作为 `copyBufferToBuffer` 的目标，且逐帧堆积回读毫无意义，
+     * 因此在途时直接跳过本帧的校验。
+     */
+    private validationInFlight;
+    private readonly maxWorkgroupsPerDimension;
+    /**
+     * keygen 所需 workgroup 数超出设备单维上限（约 `256 × 65535 ≈ 1677 万`点）。
+     * keygen shader 只用 `gid.x` 编址，无法像排序模块那样退化为 2D dispatch，因此这种极端规模下
+     * 本适配器不可用，由上层经 `checkLimits` 统一降级到 CPU 排序管线。
+     */
+    private keygenDispatchUnsupported;
+    constructor(renderer: THREE.WebGPURenderer, device: GPUDevice);
+    /**
+     * 本适配器是否已不可用。为真时上层应经 `checkLimits` 降级到 CPU 排序管线。
+     * 目前唯一来源是 keygen dispatch 规模超设备单维上限（见 `keygenDispatchUnsupported`）。
+     */
+    get unusable(): boolean;
+    /**
+     * 开发期排列性诊断开关（Requirement 13.3 / 13.4），**默认关闭**。
+     *
+     * 开启后每次排序会把 `Sorted_Indices_Buffer` 的前 `totalPoints` 个元素经 staging buffer 回读，
+     * 校验其构成 `[0, totalPoints)` 的一个排列（design.md 的 Property 1）。回读依赖 `mapAsync`，
+     * 有同步停顿，只应在排查问题时临时打开。
+     *
+     * 关闭状态下不创建 staging buffer、不录任何拷贝命令、不发起任何回读，因此零开销。
+     */
+    get debugValidateOrder(): boolean;
+    set debugValidateOrder(value: boolean);
+    /**
+     * 供材质绑定的 Order_Texture（three 纹理包装）。首次成功排序前为 `null`，
+     * 此时材质用自身的 1×1 R32UI 占位纹理保证可编译。
+     */
+    get orderTexture(): THREE.Texture | null;
+    /**
+     * 排序主流程：Distance_Range → keygen → radix sort → 写 Order_Texture。
+     *
+     * 全部命令录进调用方的 encoder，一次 submit 即可，中途不做 GPU 回读也不等待。
+     *
+     * @param encoder 调用方的命令编码器
+     * @param objects 当前布局中的 3DGS 对象，顺序与 assembler / transformStore 一致
+     * @param camera 本帧相机
+     * @param dataTexture Data_Texture（`SplatAssembler.dataTexture`）
+     * @param transformTexture Transform_Store 纹理（`TransformStore.texture`）
+     * @param totalPoints 当前布局总点数
+     * @returns 是否成功录入。以下情形返回 `false` 且不录任何 dispatch，调用方应保持上一次的
+     *   Order_Texture（或在从未排序时令 `instanceCount = 0`），下帧重试：
+     *   - `totalPoints === 0`（Requirement 16.5）
+     *   - Data_Texture / Transform_Store 尚未拿到原生 `GPUTexture`（Requirement 16.2）
+     *   - keygen dispatch 规模超设备单维上限（此后 `unusable` 为真，由上层降级）
+     */
+    encode(encoder: GPUCommandEncoder, objects: readonly PBMGaussianSplattingObject[], camera: Camera, dataTexture: THREE.Texture | null, transformTexture: THREE.Texture | null, totalPoints: number): boolean;
+    /**
+     * 计算当前帧的 Distance_Range（Requirement 5.1 / 5.2 / 5.3 / 5.5）。
+     *
+     * 遍历每个对象**对象空间** AABB 的 8 个角点，经该对象 `matrixWorld` 变换到世界空间后求
+     * Depth_Metric，取全部结果的 min / max。成本为 `对象数 × 8` 次矩阵变换，不触碰 splat 点数据。
+     *
+     * 相机 Z 轴取 `matrixWorld` 第三列（**+Z，不取负**）：three 约定相机看向 -Z，所以 +Z 指向相机
+     * 背后，越远的点 Depth_Metric 越小（越负）。因此 `minDist` 对应最远处、`maxDist` 对应最近处，
+     * 归一化后最远点 `t = 0` → Sort_Key 最小 → 升序排序天然是「由远到近」。
+     *
+     * 副作用：把相机位置与 Z 轴写入模块级 `_camPos` / `_camZ`，`writeKeygenUniforms` 紧随其后取用。
+     *
+     * @returns 无有效 AABB 或区间退化（单点场景、所有点共面且垂直于视线）时兜底返回 `{ 0, 1 }`，
+     *   避免 `invRange` 为 Infinity。
+     */
+    computeDistanceRange(objects: readonly PBMGaussianSplattingObject[], camera: Camera): DistanceRange;
+    /**
+     * 录入 keygen compute pass：为每个 splat 算出 Sort_Key 并写入 Key_Buffer。
+     *
+     * 只向 encoder 录命令，不 submit；uniform 经 `queue.writeBuffer` 更新，队列顺序保证其在
+     * 命令缓冲执行前生效。
+     *
+     * @param encoder 调用方的命令编码器
+     * @param objects 当前布局中的 3DGS 对象，顺序与 assembler / transformStore 一致
+     * @param camera 本帧相机
+     * @param dataTexture Data_Texture（`SplatAssembler.dataTexture`）
+     * @param transformTexture Transform_Store 纹理（`TransformStore.texture`）
+     * @param totalPoints 当前布局总点数
+     * @param bucketCount 量化桶数（`computeKeyBitConfig` 的结果）
+     * @returns 写入的 Key_Buffer；点数为 0、纹理尚未就绪或 dispatch 规模超上限时返回 `null`
+     *   （调用方据此本帧跳过排序，下帧重试）
+     */
+    encodeKeygen(encoder: GPUCommandEncoder, objects: readonly PBMGaussianSplattingObject[], camera: Camera, dataTexture: THREE.Texture | null, transformTexture: THREE.Texture | null, totalPoints: number, bucketCount: number): GPUBuffer | null;
+    /** 释放自有 GPU 资源：Key_Buffer、uniform buffer、Order_Texture 与排序模块。 */
+    dispose(): void;
+    /**
+     * 录入排序结果到 staging buffer 的拷贝，并安排一次异步回读校验。
+     *
+     * 拷贝必须录进**同一个 encoder**：`sortedIndices` 是排序模块的 ping-pong buffer，下一帧就会被
+     * 覆写，submit 之后再取内容已经不是本帧结果。
+     *
+     * 回读本身完全异步（`onSubmittedWorkDone` → `mapAsync`），不阻塞 encode 主流程；上一次回读
+     * 仍在途时直接跳过（`mapAsync` 期间的 buffer 不能作为拷贝目标）。
+     */
+    private encodeOrderValidation;
+    /** staging buffer 按 2048 元素粒度分配并高水位复用，与 Key_Buffer 同一策略。 */
+    private ensureStagingBuffer;
+    private destroyStagingBuffer;
+    /** 等待本帧命令执行完毕后回读 staging buffer 并做排列性校验。 */
+    private readbackAndValidate;
+    /**
+     * 校验前 `totalPoints` 个元素构成 `[0, totalPoints)` 的一个排列（design.md 的 Property 1）。
+     *
+     * 一旦发现越界或重复即 `console.error` 并中断本次校验——排序一旦出错通常是成片的，
+     * 逐个报告只会淹没控制台。
+     */
+    private validatePermutation;
+    /**
+     * 按当前点数准备 Order_Texture：高度不变则复用，变化则销毁旧纹理按新尺寸重建
+     * （Requirement 6.2 / 6.4 / 14.4）。
+     *
+     * usage 只需 `TEXTURE_BINDING | COPY_DST`：材质 `textureLoad` 读取 + `copyBufferToTexture` 写入。
+     * 重建时同时换掉包装用的 three 纹理对象——材质按引用同步（`syncDynamicUniforms`），
+     * three 也据此重建 bind group。
+     */
+    private ensureOrderTexture;
+    private destroyOrderTexture;
+    /**
+     * 按 `RadixSortModule` 的 2048 元素粒度分配 Key_Buffer 并按高水位复用。
+     *
+     * 与排序模块的容量策略保持同一粒度，使 `destructiveKeys` 模式下 Key_Buffer 能直接充当
+     * ping-pong 的一侧；点数缩小时不缩容，避免分配抖动。
+     */
+    private ensureKeyBuffer;
+    /** 已分配的 key 元素数，供排序模块以同一粒度对齐其内部容量（`minCapacity`）。 */
+    private get keyBufferCapacity();
+    /**
+     * 计算 Distance_Range 并写入 KeygenUniforms。
+     *
+     * 每次实际排序都重算（Requirement 5.4），因此不做脏检查——相机与区间几乎每次都在变。
+     */
+    private writeKeygenUniforms;
+    /**
+     * 取 three 纹理背后的原生 `GPUTexture`，拿不到时用 `initTexture` 强制上传后重取。
+     *
+     * three 的 `DataTexture` 通常在首次被材质使用时才上传，而排序发生在渲染之前。若只是等待就绪，
+     * 会形成「拿不到纹理 → 不排序 → `instanceCount = 0` 不渲染 → 纹理永远不上传」的死锁，
+     * 显式 `initTexture` 打破它。
+     */
+    private resolveGpuTexture;
+    /** `GPUTextureView` 按 `GPUTexture` 身份缓存，不每帧重建。 */
+    private getTextureView;
+    /**
+     * keygen 绑定组缓存。缓存键是两个 `GPUTexture` 与 Key_Buffer 的身份——three 侧纹理对象被替换时
+     * （`TransformStore.sync` 每次都重建纹理、`SplatAssembler.assemble` 在高度变化时重建）
+     * 必须重建绑定组，只看 `totalPoints` 是不够的。
+     */
+    private getKeygenBindGroup;
+    private invalidateKeygenBindGroup;
+}

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;
+}