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

package/five/model/objects/pbmGaussianSplattingRenderMesh.d.ts

@@ -1,5 +1,7 @@
 import * as THREE from 'three/webgpu';
 import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplattingNodeMaterial';
+import { SplatArena } from '../../gaussian-splatting/arena/splatArena';
+import type { GSplatMirrorSet } from '../../gaussian-splatting/mirrors/mirrorSet';
 /**
  * 3DGS 渲染 Mesh（WebGPU / TSL 版）
  *
@@ -9,14 +11,15 @@ import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplatt
  *     经 THREE.DataTexture 上传供主材质采样）
  *   - `TransformStore`：细粒度 transform 更新（9 texel/对象，含 CPU 预算 inverse）+ 排序用 20 float/对象
  *   - `LayerRegistry`：layerKey → 稳定 layerIndex
- *   - `SHStore`：按对象顺序连续写入 SH 纹理
+ *   - `SHAssembler` / `SHBaker` / `SHBakeScheduler`：per-tile SH 纹理 + 按视角预烘焙颜色
+ *     （按当前渲染路径的全局点索引写入烘焙纹理，两条渲染路径只读烘焙结果）
  *
- * 布局三一致（Requirements 13.1 / 13.2）：`SplatAssembler.regionList` 顺序 ≡ `TransformStore`
- * 索引顺序 ≡ `SHStore` 写入顺序。四个协作者都从**同一有序 `objects` 数组、同一顺序**同步，
- * 因此不会产生 transformIndex / SH 错位；`onBeforeRender` 中另加防御性一致性断言兜底。
+ * 布局一致：`SplatAssembler.regionList` 顺序 ≡ `TransformStore` 索引顺序。协作者都从
+ * **同一有序 `objects` 数组、同一顺序**同步，因此不会产生 transformIndex 错位；
+ * `onBeforeRender` 中另加防御性一致性断言兜底。
  *
  * 排序：本类**不再自己排序**。排序、绘制索引来源与绘制实例数一律经 `GSplatPipeline` 抽象基类
- * 消费（Requirement 10.2）：
+ * 消费：
  *   - `RASTER_CPU_SORT`（`CpuSortPipeline`）：wasm worker 排序 + Reorder_CPU，索引来自
  *     `splatIndex` 实例属性；
  *   - `RASTER_GPU_SORT`（`GpuSortPipeline`）：GPU radix sort，索引来自 R32UI Order_Texture。
@@ -38,7 +41,19 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     private assembler;
     private transformStore;
     private layerRegistry;
-    private shStore;
+    private shAssembler;
+    private shBaker;
+    private shScheduler;
+    private shJobs;
+    /** Compute 路径下由 `arena.layout` 映射出的烘焙区间（复用，避免每帧分配） */
+    private shEntries;
+    private shCapacityWarned;
+    /** 本帧是否读烘焙颜色（appliedDegree > 0 且容量 ok） */
+    private shBakedActive;
+    /** 上次烘焙时所处路径（true = Compute）；路径切换时全局点索引整体改变，需全部重烘焙 */
+    private shLastComputePath;
+    /** WebGL 后端的 MAX_TEXTURE_SIZE（首次查询后缓存） */
+    private glMaxTextureSize;
     /**
      * 当前生效的排序管线。由 `syncPipelineMode` 按 Current_Pipeline_Mode 创建 / 重建，
      * 尚未创建（首帧之前）时为 null。
@@ -60,7 +75,7 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
      */
     private _pipelineRenderer;
     /**
-     * 传给管线的每帧参数。**跨帧复用同一个对象**（Requirement 10.7），每帧填字段后传入，
+     * 传给管线的每帧参数。**跨帧复用同一个对象**，每帧填字段后传入，
      * 不在渲染循环里新建。`camera` 由每帧填充，构造时无值。
      */
     private _frameParams;
@@ -70,17 +85,163 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
      */
     private assemblePending;
     private forceClipperUniformRefresh;
-    private usedSHDegree;
+    /** 实际生效的 SH 阶数 = min(usedSHDegree, 数据阶数, MAX_RENDER_SH_DEGREE)，全局唯一 */
+    private appliedSHDegree;
+    /**
+     * Requested_Instance_Size 的原始写入值。
+     *
+     * 默认 **128**，与 PlayCanvas `GSplatResourceBase.instanceSize` 取同一经验值
+     * （其为无 setter 的 static getter，应用层包括 SuperSplat 都用这一个值）。
+     *
+     * 注意这里**有意偏离** requirements.md 的 Requirement 1.2 / 12.6（原定默认 1 以保证
+     * 「默认配置与本特性引入前逐字节等价」）：默认值经决策直接定为 128，因此本特性在默认
+     * 配置下即生效，不再具备零回归保证。回退方式是把本行改回 1。
+     *
+     * 仅在 `RASTER_GPU_SORT` 路径下生效；CPU 排序路径由 `resolveInstanceSize` 强制为 1
+     * 并输出一条告警（每 (mode, requested) 组合至多一条，不逐帧刷屏）。
+     */
+    private _requestedInstanceSize;
+    /** Effective_Instance_Size。由 setter 与每帧的 `syncInstancePacking` 同步求值。 */
+    private _effectiveInstanceSize;
+    /**
+     * 当前 Packed_Quad_Geometry 实际承载的 quad 数。初值 1（`createGeometry` 建的是 K = 1）。
+     *
+     * **用显式字段而非从 `geometry.getAttribute('position').count / 4` 反推**，两条理由：
+     *   1. 反推需要读属性对象再做一次除法，违反 Requirement 5.3 对每帧一致性检查
+     *      「常数次整数比较」的开销约束；
+     *   2. 几何体重建失败时属性可能处于「已换 position 未换 index」的中间态，
+     *      此时反推会得出一个与索引缓冲不自洽的值。
+     * 该字段只在 position 与 index **都**成功替换后才更新。
+     */
+    private _geometryQuadCount;
+    /** Current_Pipeline_Mode 是否已解析过（`syncPipelineMode` 至少跑过一次）。 */
+    private _pipelineResolved;
+    /** dispose 后置位，屏蔽后续重建与告警。 */
+    private _disposed;
+    /**
+     * Compute_Path 的点数门控：总点数超过它即回落 Fallback_Path。
+     *
+     * 与设备上报的 `maxStorageBufferBindingSize` 并列，取两者较小者。这道锁存在的理由是
+     * `InternalWebGPURenderer` 已按 adapter 上报值申请设备上限（桌面通常是 GiB 量级），原先由
+     * 规范默认值 128 MiB 顺带充当的"保险丝"没了，需要一道自己能定的闸门来兜住超大场景的显存。
+     * 默认值与依据见 `DEFAULT_MAX_COMPUTE_POINTS`。
+     *
+     * 每帧透传给 Arena（`prepareComputePath`），因此运行时修改在下一帧生效；但**调小不回收已
+     * 分配的容量**，只在下次需要扩容时才生效（见 `SplatArena.maxPoints`）。
+     */
+    maxComputePoints: number;
+    /**
+     * Arena（GPU 端紧凑装配器）。**延迟创建**：`GPUDevice` 只能从 `onBeforeRender` 的 renderer
+     * 拿到，因此首帧才创建；后端非 WebGPU、device 未就绪或创建失败时保持 `null`。
+     */
+    private _arena;
+    private _layoutMirror;
+    private _transformMirror;
+    private _objectParamsMirror;
+    /**
+     * 三块镜像打成的一个集合对象，供 `FiveRenderer` 直接传给 `submitFrame`。
+     *
+     * **在创建时构造一次并缓存**，不在访问器里每次新建：该访问器每个 Render_Frame 被读一次，
+     * 逐帧新建对象只是白给 GC 添活。
+     */
+    private _mirrorSet;
+    /**
+     * `ObjectParamsMirror` 的对象列表来源。
+     *
+     * 存的是 `rebuildScene` 收到的**那个** objects 数组，因此其顺序与 `transformStore.sync`
+     * 完全一致——这正是「transformIndex 可直接作为镜像记录下标」的前提。集合未变化的帧不走
+     * `rebuildScene`，此时数组内容与当前场景一致（集合哈希相等），沿用无误。
+     */
+    private _mirrorObjects;
+    /**
+     * 最近一次由 `FiveRenderer` 回写的存活点数；尚未取得过时为 `null`。
+     *
+     * `null` 与 `0` 必须可区分：前者是「Compute_Path 未生效或尚未完成首次回读」，
+     * 后者是「本帧确实没有点存活」。示例侧据此显示 `-` 而非 0。
+     */
+    private _survivorCount;
+    /** 本帧 Compute_Path 是否实际生效，由 `onBeforeRender` 每帧重新解析。 */
+    private _computePathActive;
     constructor();
     /**
      * Requested_Pipeline_Mode（`GSPLAT_PIPELINE_*`）。写入后在**下一帧**由
      * `syncPipelineMode` 解析并按需重建管线，便于开发期在同场景下对比两条管线
-     * （Requirement 13.2）。
      */
     get pipelineMode(): number;
     set pipelineMode(value: number);
     /** 实际生效的 Current_Pipeline_Mode（解析后的结果，永不为 `AUTO`）。 */
     get currentPipelineMode(): number;
+    /**
+     * 本帧 Compute_Path 是否**实际生效**（只读）。
+     *
+     * 供 `FiveRenderer` 在 `renderer.render()` **之后**读取——本属性由 `onBeforeRender` 写入，而
+     * `onBeforeRender` 由 three 在渲染本 Mesh 时回调，即发生在 `render()` 内部。在 `render()`
+     * 之前读取拿到的是上一帧的取值。
+     */
+    get computePathActive(): boolean;
+    /**
+     * Hybrid_Path 的 compute 渲染器。与 `_arena`、三块 Mirror 一样由本类持有、同一时机创建、
+     * 在 `dispose` 中一并释放。
+     */
+    private _hybridRenderer;
+    /** 资源初始化失败即置位，**此后不再重试**（避免逐帧抛同一个异常）。 */
+    private _computeFailure;
+    /**
+     * Arena（只读）。尚未创建（非 WebGPU 后端 / device 未就绪 / 创建失败）时为 `null`。
+     *
+     * 读取本属性与读取 Arena 自身的 `buffer` / `totalPoints` / `layout` / `revision` 一样是同步、
+     * 无副作用的：不触发装配、不创建或销毁资源。
+     */
+    get arena(): SplatArena | null;
+    /**
+     * Cull_Pass 所需的三块镜像（只读）。尚未创建时为 `null`，渲染器据此整体跳过剔除路径
+     * （不视为错误）。
+     *
+     * 与 `arena` 一样是同步、无副作用的读取：不上传、不置脏、不创建或销毁资源。镜像的
+     * `upload()` 由渲染器在 encoder 之外调用，本访问器只交出引用。
+     */
+    get mirrors(): GSplatMirrorSet | null;
+    /**
+     * 存活点数（只读）。`null` 表示尚不可得——Compute_Path 未生效、或异步回读尚未成功过一次。
+     *
+     * 取值来自 `GSplatComputeRenderer` 的廉价异步回读，因此**滞后于当前帧**（一帧以上）。
+     * 示例侧显示时须标注该值为异步取得。
+     *
+     * **`null` 与 `0` 语义不同**，消费方不得把两者合并：`null` 是「取不到」，`0` 是「确实
+     * 一个点都没存活」。
+     */
+    get survivorCount(): number | null;
+    /**
+     * 回写存活点数。**只应由 `FiveRenderer` 在每帧提交 3DGS Compute_Path 时调用。**
+     *
+     * ## 为什么是回写而不是本类直接转发
+     *
+     * 存活点数的权威来源是 `GSplatComputeRenderer`，而**本类不持有它**：该渲染器由
+     * `FiveRenderer` 创建与持有，本类只能从 `onBeforeRender` 拿到 three 的 `WebGPURenderer`，
+     * 拿不到那个 compute 渲染器实例。可选做法有三种：
+     *
+     *   - 让本类反向持有 compute 渲染器：得改动所有权关系，且要处理「渲染器换实例 / 被降级」
+     *     的失效，代价最大；
+     *   - 让示例侧直接问 `FiveRenderer`：需要在 `Five` 上再开一条对外通路，改动面比本方案大，
+     *     且与既有「3DGS 状态一律经 Render_Mesh 暴露」的读法不一致；
+     *   - **（本实现）由 `FiveRenderer` 在提交帧时把值回写过来。** 一个 setter、一处调用，
+     *     不动任何所有权关系。
+     *
+     * 代价是本类的这个取值依赖调用方按帧回写；不回写时保持上一次的取值，语义上仍然成立
+     * （它本就是「最近一次成功回读的值」）。
+     */
+    setSurvivorCount(value: number | null): void;
+    /**
+     * Requested_Instance_Size：打包进单个绘制实例的 quad 数（Instance_Size / K）。
+     *
+     * 读取返回最近一次写入的**原始值**，不做取整与 clamp。
+     * 写入在**返回前**同步更新 `effectiveInstanceSize`，而几何体与
+     * 着色器程序的同步延迟到下一个 Render_Frame。
+     */
+    get requestedInstanceSize(): number;
+    set requestedInstanceSize(value: number);
+    /** Effective_Instance_Size（只读）：校验与路径约束后实际生效的取值。 */
+    get effectiveInstanceSize(): number;
     /** 平移增量阈值（世界单位）：超过才重排。 */
     get sortCameraDistance(): number;
     set sortCameraDistance(value: number);
@@ -90,6 +251,13 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     /** 最小重排间隔（ms）：即使脏也不超过此频率，0=不限。 */
     get sortMinIntervalMs(): number;
     set sortMinIntervalMs(value: number);
+    /**
+     * SH 重烘焙阈值角度（度），合法区间 [0, 90)，默认 10。
+     * 相机相对 tile 上次烘焙位置的视角变化超过该角度才重新计算 SH 颜色；0 等价于逐帧精确计算。
+     * 修改本身不触发强制重烘焙；非法值告警并忽略。
+     */
+    get shRebakeAngle(): number;
+    set shRebakeAngle(value: number);
     private createGeometry;
     private createMaterial;
     private createDefaultLayerClipperRanges;
@@ -106,32 +274,206 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     /**
      * 场景变化时按**同一有序 objects**依次同步四个协作者，保证布局三一致：
      * layerRegistry / transformStore 先行（assembler 的 resolveIndices 依赖二者的 indexOf/layerIndexOf），
-     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ shStore.sync；大纹理组装
+     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ syncSH；大纹理组装
      * 延迟到 onBeforeRender 中的 assembler.assemble()。
      */
     private rebuildScene;
+    /** per-tile SH 纹理增量同步（只上传新增 tile） */
+    private syncSH;
+    /** 后端最大 2D 纹理尺寸：WebGPU 取 device limits，WebGL 取 MAX_TEXTURE_SIZE。 */
+    private getMaxTextureSize;
+    /**
+     * 每帧 SH 预烘焙：挑出需要重算的 tile 写入烘焙纹理（按本帧渲染路径的全局点索引寻址）。
+     * 须在 `_computePathActive` 本帧终裁之后（寻址取决于路径）、`syncMaterialTextures` / `drawHybrid` 之前调用。
+     */
+    private updateSHBake;
     /**
-     * 防御性断言：regionList 顺序 ≡ objects 顺序 ≡ TransformStore 索引顺序（Requirements 13.1/13.2）。
+     * 防御性断言：regionList 顺序 ≡ objects 顺序 ≡ TransformStore 索引顺序。
      * 四者由 rebuildScene 从同一 objects 同序同步，正常情况下恒成立；不成立即视为错误状态并告警。
      */
     private assertLayoutConsistency;
     /** 把 store 产出的纹理与 SH 阶数同步到材质。 */
     private syncMaterialTextures;
     /**
-     * 每帧一次的 Pipeline_Mode 检查与管线切换（Requirement 8.2）。
+     * 每帧一次的 Pipeline_Mode 检查与管线切换。
      *
      * 之所以每帧检查而非首帧一次性初始化：`pipelineMode` 的运行时修改要在下一帧生效
-     * （Requirement 8.6 / 13.2），且 `totalPoints` 增长导致 limits 越界、或 GPU 管线运行期失效
+     *，且 `totalPoints` 增长导致 limits 越界、或 GPU 管线运行期失效
      * （compute pipeline 创建失败 / device lost，经 `unusable` 汇聚）时都要能自动降级。
      * 所有降级情形统一归结为「`resolvePipelineMode` 返回 `RASTER_CPU_SORT`」后由本方法完成切换
-     * （Requirement 15.4），因此不存在第二条降级代码路径。
+     *，因此不存在第二条降级代码路径。
      *
-     * 模式未变且管线已就绪时只做一次整数比较即返回，开销可忽略（Requirement 8.10）。
+     * 模式未变且管线已就绪时只做一次整数比较即返回，开销可忽略。
      *
      * @param renderer 本帧渲染器（由 `onBeforeRender` 传入，是取 `GPUDevice` 的唯一入口）
      * @param totalPoints 当前布局的 Total_Points，用于按实际规模检查 limits
      */
     private syncPipelineMode;
+    /**
+     * 每帧一次的 instance packing 同步。
+     *
+     * 三件事，顺序固定：
+     *   ① 按当前 Current_Pipeline_Mode 重新求值 Effective_Instance_Size
+     *   ② 与几何体承载的 quad 数比对，不一致则重建 `position` 与 `index`
+     *   ③ 把取值同步给材质（K 是编译期常量，变化需重建程序）
+     *
+     * 一致时的开销是常数次整数比较，不随 Total_Points 增长；
+     * 本方法自身不新建 TypedArray 与 GPU buffer（只有 ② 触发重建时才分配）。
+     *
+     * @param totalPoints 当前布局的 Total_Points（仅用于「是否为 0」的分支，不参与 K 的求值）
+     * @returns 本帧是否可以提交绘制（几何体处于失败态时为 false，调用方令 Instance_Count = 0）
+     */
+    private syncInstancePacking;
+    /** K 是编译期字面量常量，变化必须重建程序。 */
+    private syncMaterialInstanceSize;
+    /**
+     * 重建 Packed_Quad_Geometry 的 `position` 与 `index`。
+     *
+     * **替换属性对象而非新建几何体**：Requirement 5.9 要求保持同一 `InstancedBufferGeometry`
+     * 实例、保留 `splatIndex` 占位属性对象及其 `_maxInstanceCount` 维护逻辑，因此这里
+     * **不调用** `geometry.dispose()`。
+     *
+     * three 侧的正确性依据：`RenderObject.needsGeometryUpdate` 会把 `attributesId` 里记录的
+     * 每个属性 id 与当前 `geometry.getAttribute(name).id` 逐个比对，不等即触发 `setGeometry()`
+     * 清空属性缓存并在下次 `getAttributes()` 重新收集。所以「替换属性对象」是 three WebGPU
+     * 后端官方支持的更新路径。`itemSize`（3）与类型（Float32）都不变，vertex buffer layout
+     * 不变，render pipeline 本身不因几何体重建而失效（它会因材质 `needsUpdate` 重建，与此无关）。
+     *
+     * 本方法不向外抛异常：失败时还原重建前的属性并返回 `false`。
+     *
+     * @param quadCount 目标 quad 数（Effective_Instance_Size）
+     * @returns 是否重建成功
+     */
+    private rebuildPackedQuadGeometry;
+    /**
+     * 释放被替换属性占用的 GPU buffer。
+     *
+     * three 没有公开的「单独释放一个 BufferAttribute」API，但内部路径是明确的：
+     * `Renderer._attributes.delete(attribute)` → `DataMap.delete` 清缓存 →
+     * `backend.destroyAttribute(attribute)` → `WebGPUAttributeUtils.destroyAttribute`
+     * 销毁 `GPUBuffer`。
+     *
+     * 这是**内部 API**，因此全程可选链 + `try/catch`：若 three 版本调整了内部结构，
+     * 这里退化为「不显式释放」，旧 `GPUBuffer` 随 attribute 对象被 GC 回收，
+     * **不影响渲染正确性**，只是释放时机变晚。
+     *
+     * 渲染器复用既有的 `_pipelineRenderer` 字段（`syncPipelineMode` 里已记录本帧渲染器），
+     * 不为此新增 renderer 引用。
+     */
+    private releaseAttributeGpuResource;
+    /**
+     * 求值本帧 Instance_Count。
+     *
+     * 按 `pipeline.requiresOrderTexture` 分流而非 `instanceof`：该 getter 是
+     * `GSplatPipeline` 的既有能力查询契约，不需要新增接口，也不引入对管线实现类型的依赖。
+     *
+     * `pipeline.instanceCount` 的契约语义保持不变（仍是「可绘制的 splat 数」），`ceil` 除法只
+     * 发生在这里，因此上游 spec gsplat-gpu-sort 无需修改。
+     *
+     * `Math.ceil(raw / k)` 用浮点除法而非整数运算是安全的：`raw` 上限约 1677 万（受 keygen
+     * dispatch 上限约束）、`k <= 256`，二者都在双精度可精确表示的范围内，无舍入风险。
+     * Requirement 4.5（`0 < raw < k` 时取 1）与 4.6 的双向不等式都是 `ceil` 的定义性质，
+     * 不需要额外代码。
+     *
+     * @param pipeline 本帧生效的管线
+     * @param resourcesReady Render_Mesh 侧的资源就绪判据
+     * @returns 提交给 `geometry.instanceCount` 的实例数；任何不可用情形均为 0
+     */
+    private resolveInstanceCount;
+    /**
+     * 后端是否为 WebGPU 且 `GPUDevice` 已就绪。**每帧实算，不缓存。**
+     *
+     * 曾经是「三态缓存 + 连续 120 帧未就绪则置终态 false」。那个超时终态在 iPhone 上会误杀：
+     * WebGPU device 的异步创建比桌面慢，前 120 帧都拿不到 device，于是被永久判定为不可用，
+     * 之后 device 就绪了也不再启用 —— 表现为「backend 显示 WEBGPU 但 3dgs path 恒为 FALLBACK，
+     * 且没有任何报错」。两个判据每帧都可查、没有任何计算量，缓存它没有收益。
+     */
+    private probeComputeBackend;
+    /**
+     * Compute_Path 的每帧起点：**探测 → Arena 延迟创建 → `arena.beginFrame()` → 解析
+     * `_computePathActive`**，四件事按此次序一次做完。
+     *
+     * **调用位置必须在 `isSceneNeedsRebuild` / `rebuildScene` 之前**，理由是两条依赖交叉：
+     *   - Arena 只能从 `renderer` 拿 device，故创建必须在 `onBeforeRender` 内；
+     *   - `rebuildScene` 内部会调 `arena.sync`，而 `beginFrame()` 必须早于本帧任何 `sync`
+     *     （它负责归零每帧流量计数器并结算上一帧的流量校验）。
+     *
+     * 把四件事都放在 `collectObjects` 之后、`isSceneNeedsRebuild` 之前，两条依赖同时满足：
+     * device 已可取得，且本帧的 `sync` 一定发生在 `beginFrame()` 之后。
+     *
+     * `_computePathActive` 也在此解析而非等到 `syncPipelineMode` 之后：它的三个输入（探测结论、
+     * 开关、Arena 可用性）在这里全部已知，而**下游的 `assembler.assemble()` 早于
+     * `syncPipelineMode`**，若等到那之后再解析就来不及跳过组装。解析结果与放在哪里无关——
+     * `unusable` 只会在 `encodeAssembly`（`FiveRenderer` 侧，本帧 `render()` 之后）与 `dispose`
+     * 中改变，本方法与 `syncPipelineMode` 之间不存在任何能改变它的调用。
+     */
+    private prepareComputePath;
+    /** 建 Arena、Hybrid 渲染器与三块 Mirror。三者可用性对 Compute_Path 是「与」关系，同生同灭。 */
+    private createComputeResources;
+    /**
+     * 建 Hybrid 渲染器。color / depth 格式**必须与 Draw 命令所在 render pass 的附件严格一致**，
+     * 否则 `setPipeline` 被校验层拒绝。
+     *
+     * color 从 three 当前 render target 的纹理类型推：`FiveRenderer` 的合成 RT 是
+     * `{ type: outputType }` + 默认 `RGBAFormat`，于是 `HalfFloatType → 'rgba16float'`，
+     * 其余（`UnsignedByteType`）→ `'rgba8unorm'`。depth 取 `'depth24plus'`：three 为合成目标建的
+     * `DepthTexture`（默认 `DepthFormat` + `UnsignedIntType`）落到 WebGPU 后端就是它。
+     *
+     * 对数深度缓冲下返回 `null`：`gsplatQuad.wgsl` 用 `clip.z = -P22 · depth + P32` 重建裁剪空间
+     * 深度，只对常规投影成立，而 three 在该标志为真时走 `viewZToLogarithmicDepth`。症状是 3DGS
+     * 相对不透明几何整体偏前或偏后。
+     */
+    private createHybridRenderer;
+    /**
+     * Hybrid_Path 的绘制：编码 compute 链并把 Draw 命令录进 three 当前活跃的 render pass。
+     *
+     * 由 `onBeforeRender` 末尾调用，那一刻三个前提同时成立：Layout_Table 已就绪、不透明几何已画完
+     * 且深度已写入、其后的半透明与 overlay 对象还没开始画（本 Mesh 的
+     * `renderOrder = -99999999999` 是 transparent 队列第一个）。放到 `render()` 之后画会把 grid、
+     * `intersectMesh` 这类 overlay 全盖住。
+     */
+    private drawHybrid;
+    /**
+     * 取 three 当前活跃的 `GPURenderPassEncoder` 与它的状态缓存失效化回调。
+     *
+     * 依赖三个非公开字段：`renderer._currentRenderContext`（`renderObject` 期间有效）、
+     * `backend.get(rc).currentPass`、`.currentSets`。取不到就跳过本帧绘制而不是抛给渲染循环，
+     * 故 three 升级若改名，症状是 Compute_Path 下 3DGS 不显示而非崩溃。
+     */
+    private getActiveRenderPass;
+    /**
+     * 创建三块 Mirror 并缓存它们的集合对象。仅由 `prepareComputePath` 在创建 Arena 的同一处调用。
+     *
+     * 三个取数闭包都指向本类自己的状态，因此镜像与本类之间**只有单向引用**（镜像持闭包，本类
+     * 持镜像），不构成互相持有：
+     *   - Layout：读 `_arena.layout`。Arena 在 `unusable` 时自己返回空表，故这里不必再判可用性；
+     *   - Transform：读 `transformStore`（其 `transforms` 是公开 getter，每对象 20 float、
+     *     前 16 个即 matrixWorld 列主序），因此**不需要改动 `TransformStore`**；
+     *   - Object_Params：读 `_mirrorObjects`，即 `rebuildScene` 收到的那个有序数组。
+     */
+    private createMirrors;
+    /**
+     * 级联销毁三块 Mirror 并清掉集合缓存。`MirrorBuffer.dispose()` 幂等且内部捕获异常，
+     * 因此这里不需要 try/catch。
+     */
+    private disposeMirrors;
+    /**
+     * 判定本帧场景是否用到了 Hybrid_Path 还没迁进 compute 的功能。
+     *
+     * 两项功能（viewlayer clipper、入场动画）在 Fallback 的 TSL 顶点着色器里已实现，
+     * `gsplatProjector.wgsl` 还没写。命中任一项就走 Fallback，画面因此始终正确、只是拿不到
+     * Hybrid 的性能收益。SH 由 SHBaker 预烘焙、两条路径同读烘焙颜色，不是回落判据。
+     *
+     * **本方法与 `gsplat-hybrid-projection` 的任务 2.2 / 2.3 是一组的：那两项完成后，对应的判据
+     * 要一并删掉，本方法随之整个消失。** 别把它当成长期存在的能力检查。
+     *
+     * 判据的取值来源刻意不走 `this.material.numGsClippers`：它由 `updateClipperUniforms` 更新，
+     * 排在本判定**之后**，读它会拿到上一帧的值——症状是加 clipper 的那一帧先用 Hybrid 画一帧不带
+     * 该功能的画面、下一帧才切回 Fallback，即闪一帧。改读数据源就没有这个延迟。
+     *
+     * @returns 命中的原因键，未命中时 `null`
+     */
+    private resolveHybridUnsupportedReason;
     onBeforeRender: (renderer: any, scene: THREE.Scene, camera: THREE.Camera, ..._rest: any[]) => void;
     dispose(): void;
 }

package/five/model/parameter.d.ts

@@ -80,6 +80,10 @@ export interface ParameterMaterialValue {
     boundingBox: THREE.Box3;
     /** 3dgs球谐阶数*/
     gaussianSplattingSHDegree: number;
+    /**
+     * 是否开启 3dgs 加载入场动画（点云扩散生长 + 运镜）
+     */
+    enableGaussianSplattingInitAnimation: boolean;
     maxDisplayBoost: number;
     /** 自定义节点列表（TSL Node 级别的材质扩展） */
     customNodes: readonly PBMCustomNode[];

package/five/renderer/compute-renderers/binned/binned-core.d.ts

@@ -1,3 +1,5 @@
+import { BinnedPipelineCache, type BinnedPipelines, type BinnedStage, type TransparentBinnedStage } from './binned-pipelines';
+import type { ExtraBuffers } from '../transparency-buffers';
 /** 光栅参数（像素直径）：≤ SMALL 单线程绘制，≤ LARGE 按点协作，更大按 8×8 子块协作 */
 export declare const RASTER_CONFIG: {
     readonly smallThreshold: 8;
@@ -15,10 +17,17 @@ export declare const RASTER_CONFIG: {
  * 分桶协作光栅的 GPU 资源与命令编码。
  * classify 按点尺寸分类：Small 直接绘制，Medium / Large 入桶；
  * 随后 coop_medium 每个 workgroup 绘制一个点，coop_large 每个 workgroup 绘制一个 8×8 子块。
+ *
+ * 按阶段编码：各阶段复用同一组桶、子块、计数器与 indirect 参数。
+ * 每个阶段开始前须 `encodeClearCounters(encoder)`（在计算通道之外），随后在计算通道内
+ * 对各块 `encodeStageClassify`，最后 `encodeStageCoop`。透明阶段先调用 `prepareStage`
+ * 准备流水线与平面绑定组。
  */
 export declare class BinnedCore {
     private readonly device;
     private readonly frameUniformBuffer;
+    /** 各阶段的流水线；不透明变体在构造时创建，透明变体惰性创建 */
+    readonly pipelines: BinnedPipelineCache;
     private readonly pipes;
     private readonly counters;
     private readonly args;
@@ -30,17 +39,51 @@ export declare class BinnedCore {
     private argsBG;
     private coopBG;
     private boundFramebuffer;
+    /** 透明阶段 coop group0（不含 framebuffer）；透明变体共用同一布局，随桶重分配重建 */
+    private transparentCoopBG;
+    /** 透明阶段 coop group1（空绑定组） */
+    private emptyBG;
+    private readonly stageStates;
     constructor(device: GPUDevice, tileBindGroupLayout: GPUBindGroupLayout, frameUniformBuffer: GPUBuffer);
     get bucketCapacity(): number;
     get subBlockCapacity(): number;
     /** 每帧编码前调用：按点数调整容量（只增不减），并保证 bind group 引用当前 framebuffer */
     prepare(totalPoints: number, framebuffer: GPUBuffer): void;
+    /** 每个阶段开始前调用（计算通道之外）：清零 medium / large / subBlock / overflow 计数 */
     encodeClearCounters(encoder: GPUCommandEncoder): void;
-    /** 一个 tile 的分类 dispatch */
+    /** 获取某阶段流水线（透明变体首次调用时创建）；失败返回 Error，上层按缓冲创建失败降级 */
+    getStagePipelines(stage: BinnedStage): BinnedPipelines | Error;
+    /**
+     * 透明阶段的块绑定组（classify group0，无 binding 0 framebuffer，binding 1..7 与不透明块绑定组相同）。
+     * 透明变体共用同一个 tileBGL，所以每块只需一份，各透明阶段通用。
+     * `entries` 传 binding 1..7（不含 framebuffer）。流水线创建失败时返回 Error。
+     */
+    createTransparentTileBindGroup(entries: GPUBindGroupEntry[], stage?: TransparentBinnedStage): GPUBindGroup | Error;
+    /**
+     * 透明阶段编码前调用（须在 `prepare` 之后）：取得流水线、确保透明 coop 绑定组与空绑定组，
+     * 并按 (revision, depthView) 复用或重建平面绑定组。叠加需要叠加平面（单缓冲）；
+     * 混合半透明需要透明层与不透明深度视图。
+     * 成功返回 null；流水线创建失败或缓冲缺失时返回 Error，本阶段不应编码。
+     */
+    prepareStage(stage: TransparentBinnedStage, buffers: ExtraBuffers, revision: number, depthView?: GPUTextureView | null): Error | null;
+    /** 一个 tile 的分类 dispatch（不透明） */
     encodeClassify(pass: GPUComputePassEncoder, tileBindGroup: GPUBindGroup, pointCount: number): void;
-    /** 所有 tile 分类完成后：写 indirect 参数，再协作绘制 Medium / Large 点 */
+    /** 所有 tile 分类完成后：写 indirect 参数，再协作绘制 Medium / Large 点（不透明） */
     encodeCoop(pass: GPUComputePassEncoder): void;
+    /**
+     * 按阶段变体对一个块分类。不透明传渲染器的块绑定组（含 framebuffer）；
+     * 透明阶段传 `createTransparentTileBindGroup` 创建的块绑定组，且本帧须已 `prepareStage` 成功。
+     * 透明阶段未准备好时不编码，返回 false。
+     */
+    encodeStageClassify(pass: GPUComputePassEncoder, stage: BinnedStage, tileBindGroup: GPUBindGroup, pointCount: number): boolean;
+    /**
+     * 某阶段所有块分类完成后：args-builder 写 indirect 参数，再 coop_medium / coop_large。
+     * 透明阶段未准备好时不编码，返回 false。
+     */
+    encodeStageCoop(pass: GPUComputePassEncoder, stage: BinnedStage): boolean;
     dispose(): void;
+    /** 透明 coop group0 / group1：透明变体共用 coopBGL 与 emptyBGL，按需创建一次，桶重分配后重建 */
+    private ensureTransparentCoopBindGroups;
     private allocate;
     private createBindGroups;
 }

package/five/renderer/compute-renderers/binned/binned-pipelines.d.ts

@@ -1,10 +1,91 @@
+/** 绘制阶段：不透明 / 叠加 / 混合半透明（层写入），各对应一个写像素模块 */
+export type BinnedStage = 'opaque' | 'additive' | 'blend';
+export type TransparentBinnedStage = Exclude<BinnedStage, 'opaque'>;
+/**
+ * 一个阶段的分桶流水线变体。
+ *
+ * 绑定组安排：
+ * - 不透明：classify = [tileBGL(含 framebuffer), classifyBGL]；coop = [coopBGL(含 framebuffer)]。
+ * - 叠加：classify = [tileBGL(无 binding 0), classifyBGL, planesBGL(binding 0 = 叠加平面单缓冲)]；
+ *   coop = [coopBGL(无 binding 0), emptyBGL, planesBGL]。其余 binding 号与不透明一致。
+ * - 混合半透明：同叠加，planesBGL = [binding 0 = 透明层, binding 1 = 不透明深度纹理（sampleType 'depth'）]。
+ * - args-builder 各阶段都是 [argsBGL]。
+ */
 export interface BinnedPipelines {
+    readonly stage: BinnedStage;
+    /** classify 的 group0（块绑定组）布局；不透明即渲染器的 tileBindGroupLayout */
+    readonly tileBGL: GPUBindGroupLayout;
+    /** classify 的 group1（桶 / 子块 / 计数），各阶段共用 */
     readonly classifyBGL: GPUBindGroupLayout;
+    /** args-builder 的 group0，各阶段共用 */
     readonly argsBGL: GPUBindGroupLayout;
+    /** coop 的 group0 布局；透明变体共用同一个不含 framebuffer 的布局 */
     readonly coopBGL: GPUBindGroupLayout;
+    /** 透明变体 coop 的 group1（空布局）；不透明为 null */
+    readonly emptyBGL: GPUBindGroupLayout | null;
+    /** 透明变体 classify 与 coop 的 group2（平面）；不透明为 null */
+    readonly planesBGL: GPUBindGroupLayout | null;
     readonly classifier: GPUComputePipeline;
     readonly argsBuilder: GPUComputePipeline;
     readonly coopMedium: GPUComputePipeline;
     readonly coopLarge: GPUComputePipeline;
 }
-export declare function createBinnedPipelines(device: GPUDevice, tileBindGroupLayout: GPUBindGroupLayout): BinnedPipelines;
+interface WriteModuleParts {
+    /** 拼入 classify 与 coop：Payload、BUCKET_STRIDE、write_pixel、load_bucket 等 */
+    readonly shared: string;
+    /** 只拼入 classify：make_payload、store_bucket 等依赖着色或可写桶的函数 */
+    readonly classifyOnly: string;
+    /** 只含 BUCKET_STRIDE 常量声明，拼入 args-builder */
+    readonly strideDecl: string;
+}
+/** 按约定切分写像素模块（write-*.wgsl） */
+export declare function splitWriteModule(code: string): WriteModuleParts;
+export interface BinnedShaderCodes {
+    readonly classify: string;
+    readonly argsBuilder: string;
+    readonly coop: string;
+}
+/**
+ * 用给定写像素模块拼出 classify / args-builder / coop 的完整 WGSL。
+ * `constants` 拼在写像素模块之前（透明变体传 transparencyWgslConstants()），不透明变体为空。
+ */
+export declare function buildBinnedShaderCodes(writeModuleCode: string, constants?: string): BinnedShaderCodes;
+/** 某阶段三份着色器的完整 WGSL（按需拼接并缓存） */
+export declare function buildBinnedStageShaderCodes(stage: BinnedStage): BinnedShaderCodes;
+/**
+ * 块绑定组（classify group0）的布局条目，与 tile-bindings.wgsl 对应。
+ * `withFramebuffer = true` 为渲染器现有的 tileBindGroupLayout；透明变体去掉 binding 0（framebuffer），
+ * 其余 binding 号不变。
+ */
+export declare function tileBindGroupLayoutEntries(withFramebuffer: boolean): GPUBindGroupLayoutEntry[];
+/** 透明变体 classify 每着色阶段所需的 storage buffer 数（块 + 桶 + 平面），用于创建前检查设备上限 */
+export declare function transparentClassifyStorageBufferCount(stage: TransparentBinnedStage): number;
+/**
+ * 创建某阶段的分桶流水线。
+ * 不透明（默认）：`tileBindGroupLayout` 为渲染器的块布局。
+ * 透明变体：单独调用时自建全部布局（不与其它阶段共用），一般应通过 `BinnedPipelineCache` 获取。
+ */
+export declare function createBinnedPipelines(device: GPUDevice, tileBindGroupLayout: GPUBindGroupLayout, stage?: BinnedStage): BinnedPipelines;
+/**
+ * 透明流水线变体的惰性缓存。
+ *
+ * - 首次 `get(stage)` 时同步创建该阶段流水线（以及透明变体共用的布局），之后直接返回缓存；
+ *   `classifyBGL` / `argsBGL` 与不透明变体共用，上层可复用同一组桶 / args 绑定组。
+ * - 创建前检查 storage buffer 数是否超过 `maxStorageBuffersPerShaderStage`，超过时直接返回错误。
+ * - 同步异常（try/catch）与异步校验错误（pushErrorScope / popErrorScope）都记为失败，`get` 返回 Error，
+ *   上层按"缓冲创建失败"降级。校验错误（着色器编译、布局不匹配）是确定性的，不再重试，
+ *   以免每次重试都让一帧的命令缓冲失效；内存不足 / 内部错误在下一次 `get` 时重试。
+ * - 异步结果返回前（pending）`get` 照常返回流水线。
+ */
+export declare class BinnedPipelineCache {
+    private readonly device;
+    readonly opaque: BinnedPipelines;
+    private transparentShared;
+    private readonly entries;
+    constructor(device: GPUDevice, opaque: BinnedPipelines);
+    get(stage: BinnedStage): BinnedPipelines | Error;
+    /** 已有缓存（不触发创建）；未创建或失败时为 null */
+    peek(stage: BinnedStage): BinnedPipelines | null;
+    private create;
+}
+export {};

package/five/renderer/compute-renderers/color-space.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 点颜色上传用的线性 → sRGB 转换与 sRGB → RGB565 编码。
+ *
+ * 点颜色缓冲按 sRGB 值存 RGB565：上传时不做 sRGB 转线性，着色器（color.wgsl）
+ * 解码 RGB565 后再用 `srgb_to_linear` 转成线性。
+ */
+/** 线性 → sRGB（64 位），用于 Float32Array 颜色上传。 */
+export declare function linearToSrgb(v: number): number;
+/**
+ * 8 位 sRGB → RGB565：(round(r/255×31) << 11) | (round(g/255×63) << 5) | round(b/255×31)。
+ * 输入为 0–255 的整数（Uint8Array 颜色）。
+ */
+export declare function encodeSrgb8ToRgb565(r: number, g: number, b: number): number;