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

package/five/gaussian-splatting/arena/splatArena.d.ts

@@ -0,0 +1,227 @@
+import type { PBMGaussianSplattingObject } from '../../model/objects/pbmGaussianSplattingObject';
+/**
+ * Compute_Path 的默认点数门控（对应 512 MiB Arena）。
+ *
+ * 这道锁与设备上报的 `maxStorageBufferBindingSize` **并列**，取两者较小值。之所以要自己再加
+ * 一道：`InternalWebGPURenderer` 已按 adapter 上报值申请上限，桌面上通常是 GiB 量级，原先由
+ * 规范默认值 128 MiB 顺带充当的那道"保险丝"就没了。没有它，超大场景会真去分配巨块显存，
+ * 在显存紧张的设备上把"优雅回落 Fallback_Path"变成分配失败或 device lost（黑屏级故障）。
+ *
+ * 取值依据：Arena 每点 32 字节，1600 万点即 512 MiB。移动端多数设备上报的绑定上限本就低于
+ * 此值、由设备那道锁先生效，因此这个默认值实际约束的是桌面。按场景调整走 `maxPoints`。
+ */
+export declare const DEFAULT_MAX_COMPUTE_POINTS = 16000000;
+/**
+ * Arena 布局表的一项。顺序与传入 `sync` 的对象顺序（即 `TransformStore` 的对象顺序）一致。
+ *
+ * 全部字段只读：消费方对表项写入不得影响 `SplatArena` 的内部状态（Requirement 14.1）。
+ * 刻意**不复用** `SplatAssembler` 的 `AssembledRegion`——后者的 `start` 是可变字段且被
+ * `assemble()` 就地改写，与这里的只读契约冲突。
+ */
+export interface ArenaLayoutEntry {
+    /** 该 tile 的源对象。 */
+    readonly object: PBMGaussianSplattingObject;
+    /** 在 Arena 内的起始**点**偏移（非字节）。字节偏移 = `startPoint * 32`。 */
+    readonly startPoint: number;
+    /** 点数，恒大于 0（点数为 0 的对象不入表，故表中不存在长度为 0 的区间）。 */
+    readonly count: number;
+    /** transformIndex 的权威值。Arena 内 word7 的高 16 位**不是**权威值。 */
+    readonly transformIndex: number;
+    /** layerIndex 的权威值。 */
+    readonly layerIndex: number;
+}
+/** `resolveIndices` 的返回形状，与 `SplatAssembler.sync` 完全一致。 */
+interface ResolvedIndices {
+    transformIndex: number;
+    layerIndex: number;
+}
+/**
+ * GPU 端紧凑装配器：per-tile 常驻 storage buffer + 一块紧凑连续的大 Arena。
+ *
+ * 只暴露 CPU 侧契约（`buffer` / `totalPoints` / `layout` / `revision` / `unusable`）；
+ * Layout_Table 的 GPU 侧镜像与按点索引的二分查找留给第一个 Arena 消费方所在的 spec。
+ */
+export declare class SplatArena {
+    private readonly device;
+    /**
+     * per-tile 常驻缓冲缓存。**强引用 Map 而非 WeakMap**，理由见 `releaseTile` 的注释。
+     * key 为 GS_Object，value 为其 Tile_Buffer（容量 `numPoints * 32`）。
+     */
+    private readonly tileBuffers;
+    /** key = GS_Object；value = 注册到 `THREE.EventDispatcher` 上的 `'dispose'` 监听器，用于反注册。 */
+    private readonly disposeListeners;
+    /** 紧凑装配的大 buffer。首次需要时创建，容量不足时重建，`dispose` 时销毁。 */
+    private arena;
+    /** Arena 已分配的字节容量（High_Water_Capacity），单调不减，需求缩小时不缩容。 */
+    private highWaterBytes;
+    /** 当前布局表。仅在 `revision` 递增时重建数组与表项对象。 */
+    private layoutTable;
+    /** 全部表项点数之和。 */
+    private totalPointsValue;
+    /** Tile_Set_Revision：自 0 起单调不减，tile 集合变化时递增 1。 */
+    private revisionValue;
+    /** 本帧（或此后某帧）是否还欠一次 Arena_Assembly。 */
+    private assemblyPending;
+    /** 上一次的布局签名，用于判定 tile 集合是否变化。 */
+    private lastSignature;
+    /**
+     * 已被新 Arena 替换、但**尚未销毁**的旧 buffer。
+     * 必须等调用方 `queue.submit` 之后由 `flushPendingDestroy()` 销毁——队列里可能还有引用它的命令。
+     */
+    private pendingDestroy;
+    private _disposed;
+    /**
+     * Compute_Path 允许的最大点数（门控参数，见 `DEFAULT_MAX_COMPUTE_POINTS`）。
+     *
+     * 运行时可写，但**调小不会回收已分配的容量**：判定只发生在 `sync` 触发的扩容路径上。
+     */
+    maxPoints: number;
+    /** 只接收已就绪的 device，本类生命周期内不请求 adapter/device。 */
+    constructor(device: GPUDevice);
+    /** Arena 的 `GPUBuffer`。尚未创建过或 `unusable` 时为 `null`。 */
+    get buffer(): GPUBuffer | null;
+    /** 当前 Layout_Table 覆盖的总点数。消费方以它作为可读点数的唯一上界。 */
+    get totalPoints(): number;
+    /** 当前布局表。`unusable` 时返回长度 0 的表。 */
+    get layout(): readonly ArenaLayoutEntry[];
+    /** Tile_Set_Revision。它的变化是消费方发现 `GPUBuffer` 对象已被替换的唯一信号。 */
+    get revision(): number;
+    /**
+     * 本装配器是否已不可用。三个来源都是**单向不可逆**的：Arena 创建失败、所需容量超设备上限、
+     * 已 `dispose`。为真时上层应回落 Fallback_Path（后者消费 `SplatAssembler`，与 Arena 无关）。
+     */
+    get unusable(): boolean;
+    /**
+     * 按有序对象列表增量同步（**纯 CPU，不编码任何 GPU 命令**）。
+     *
+     * 签名与 `SplatAssembler.sync` 完全一致，使调用点能把**同一个 `objects` 数组与同一个
+     * `resolveIndices` 闭包**同时传给两者——Layout_Table 的顺序一致性（design.md 的 Property 5）
+     * 就是由这个调用点结构保证的，而不是靠额外校验。
+     *
+     * `device.queue.writeBuffer` 走队列、不经 encoder，属于本方法允许的范围。
+     *
+     * 四步：
+     * ① 移除不在新集合中的对象（销毁其 Tile_Buffer、反注册监听、删两个 Map 条目）
+     * ② 为尚无 Tile_Buffer 的对象创建并一次性上传（数据未就绪的跳过、下帧重试）
+     * ③ 用单一累加器重建 Layout_Table（点数为 0 或无 Tile_Buffer 的对象不入表）
+     * ④ 比对布局签名，决定是否置 `assemblyPending` 并递增 `revision`
+     */
+    sync(objects: readonly PBMGaussianSplattingObject[], resolveIndices: (obj: PBMGaussianSplattingObject) => ResolvedIndices): void;
+    /**
+     * 不分配任何对象地判断既有 Layout_Table 是否已经等于本次应得的结果。
+     *
+     * 只在**完全一致**（表项数、每项的对象引用、startPoint、count、transformIndex、layerIndex
+     * 全都相同）时才算可复用，此时不新建数组也不新建表项对象（Requirement 14.6）。
+     *
+     * 注意这里为真并不意味着可以跳过步骤 ④：布局表不含「无 Tile_Buffer 的对象」，因此一个尚未
+     * 就绪的对象进出集合时布局表不变而布局签名会变，那种情况仍需按签名递增 revision。
+     *
+     * @returns 可复用时返回总点数，否则返回 -1
+     */
+    private tryReuseLayout;
+    /**
+     * 布局签名：tile 集合是否变化的唯一判据。
+     *
+     * 它恰好覆盖 Requirement 9.10 的四条充要条件：项数与 uuid 序列变化（新增 / 移除）、
+     * uuid 序列的排列变化（顺序变化）、数值部分变化（`numPoints` 变化）、
+     * 由 `-1` 变为实际点数（先前未就绪的对象首次成功创建 Tile_Buffer）。
+     *
+     * **不得复用 `Render_Mesh.isSceneNeedsRebuild` 的哈希**：后者用 `uuid:gsViewLayerKey`、
+     * 不含 `numPoints`。而 `numPoints` 会在对象存活期间因异步加载补齐而变化——那时后者不变，
+     * 但 Arena 必须重拼，漏掉这次重拼的症状是偶发缺片而不是稳定错误。
+     *
+     * 同样重要的是它**不含**：相机相关量、`transformChanged`、`transformIndex`、`layerIndex`。
+     * 因此「静止帧零流量」（Property 3）与「索引变化只更新表项」（Requirement 9.11）由构造直接成立，
+     * 不需要任何额外分支。
+     */
+    private computeLayoutSignature;
+    /**
+     * 为单个对象创建 Tile_Buffer 并一次性上传，随后注册 `'dispose'` 监听。
+     *
+     * **内容必须是 `packedData` 前 `numPoints * 8` 个 u32 的逐字节副本**：一次 `writeBuffer`
+     * 搬完，不做任何改写。这与 `SplatAssembler.assemble()` 的「逐 splat 覆写 word7」相反，
+     * 原因见文件头。上传后该 buffer 的内容在其整个生命周期内不再被 CPU 写入。
+     *
+     * @returns 是否顺利（`false` 表示本次跳过并已告警，下帧重试；点数为 0 的正常跳过返回 `true`）
+     */
+    private createTileBuffer;
+    /**
+     * 在对象首次成功创建 Tile_Buffer 时挂一个 `'dispose'` 监听。注册前查重，
+     * 使同一对象在任意时刻至多有一个监听器（Requirement 13.5）。
+     */
+    private registerTileDisposer;
+    /**
+     * 释放单个 tile 的全部资源：销毁 Tile_Buffer、删缓存条目、反注册监听并删监听器条目。
+     *
+     * **幂等**：条目已删时直接返回、不重复 `destroy`、不抛异常。两条释放路径
+     * （从集合移除、`'dispose'` 事件）可能先后触发同一对象（Requirement 13.9）。
+     *
+     * ---
+     * **用强引用 Map 而非 WeakMap 的论证（Requirement 13.7）**：释放由两条**确定路径**驱动
+     * 而不依赖垃圾回收——`sync` 步骤 ① 的「集合移除」与这里的 `'dispose'` 事件——且两条路径
+     * 都必然走到本方法、必然删掉两个 Map 的条目，故不产生泄漏。反过来，WeakMap 会让显存归还
+     * 时机取决于 GC，无法满足「离开视野的 tile 立即归还显存」。
+     *
+     * **一个已核实的事实（勿据此误判主次）**：`'dispose'` 事件路径在当前代码里**不会触发**。
+     * tile 卸载走的是 `TileNode.dispose()`，而后者只执行 `disposers` 闭包、不遍历对象逐个调
+     * `dispose()`；且 `TileNode` 构造期的 traverse 没有把 `PBMGaussianSplattingObject` 推入
+     * `pbmObjects`。因此**「从集合移除即释放」是当前唯一实际生效的路径**，承担全部显存归还责任；
+     * 事件路径是防御性的第二条路（零成本、语义正确，将来有直接 `dispose()` 单个 3DGS 对象的
+     * 调用方时资源不会漏），不是主路。
+     */
+    private releaseTile;
+    /**
+     * 把本次 Arena_Assembly 的全部拷贝命令录进调用方的 encoder。**只录命令，不做 submit。**
+     *
+     * 静止帧（tile 集合未变化）在首行即返回，因此该帧的 `copyBufferToBuffer` 次数为 0、
+     * 上传字节数为 0（Property 3）。
+     *
+     * 装配覆盖当前**全部**存活且已成功创建 Tile_Buffer 的 tile（含点数与内容均未变化的），
+     * 不做任何形式的增量差异拷贝——数据源全部常驻，全量重拼与增量在结果上等价而实现简单得多。
+     */
+    encodeAssembly(encoder: GPUCommandEncoder): void;
+    /**
+     * 供调用方在 `queue.submit` **之后**调用，销毁被本帧替换掉的旧 Arena。
+     *
+     * 不在 `encodeAssembly` 内直接 `destroy()`：那时队列中可能还有引用旧 buffer 的命令，
+     * 提前销毁会让这些命令引用已失效的资源（Requirement 11.3）。
+     */
+    flushPendingDestroy(): void;
+    /**
+     * 按高水位策略确保 Arena 容量足够。
+     *
+     * 需求缩小时不缩容、不重建（Requirement 11.4）。容量增长时新建 buffer，旧 buffer 存入
+     * `pendingDestroy` 等 submit 之后再销毁，并递增 `revision` 使消费方知道 `GPUBuffer`
+     * 对象已被替换（Requirement 11.9）。
+     *
+     * 重建后的数据完好性靠「在新 Arena 上重跑覆盖全部存活 tile 的完整装配」保证，数据源是
+     * 常驻的 Tile_Buffer 而**不从旧 Arena 拷**——重拼结果与「从零装配一次」在定义上是同一个东西，
+     * 既省一次搬移，也自然绕开 WebGPU 禁止同缓冲自拷贝的约束。
+     *
+     * 超过 `maxPoints` 门控或 `createBuffer` 失败时**直接抛**，不做降级——门控是我们自己设的
+     * 阈值，撞了就该暴露出来去调阈值，而不是静默回落。
+     *
+     * @returns `'ok'` 复用既有容量；`'grew'` 本次新建了更大的 Arena
+     */
+    private ensureCapacity;
+    /** 设备上报的单个 storage buffer 绑定上限；缺失或为 0 时用兜底值。 */
+    private get maxStorageBufferBindingSize();
+    /** 点数门控换算成的字节上限。非法取值（NaN / 负数）按 0 处理，即彻底停用 Compute_Path。 */
+    private get maxPointsBytes();
+    /**
+     * Arena 的有效容量上限：设备上报的绑定尺寸上限与自设点数门控的**较小者**。
+     *
+     * 两处判定共用它——`ensureCapacity` 判总量、`createTileBuffer` 判单个对象。两者必须取同一个
+     * 上限，否则会出现"单对象通过了但总量注定失败"的半通过状态。
+     */
+    private get effectiveCapacityBytes();
+    /**
+     * 释放本装配器持有的全部资源，并置 `_disposed`（单向不可逆）。
+     *
+     * 执行后三项契约为空值语义：`buffer` 为 `null`、`totalPoints` 为 0、`layout` 长度为 0，
+     * 且两个 Map 的条目数均为 0。逐项释放各自包 try/catch，任一项抛异常不影响其余项。
+     */
+    dispose(): void;
+    private destroyArenaBuffer;
+}
+export {};

package/five/gaussian-splatting/cullConstants.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 最小屏幕尺寸阈值（像素），语义为「椭圆长轴的像素长度」。取值同 SuperSplat 的默认值。
+ *
+ * **量纲陷阱**：判据写 `sqrt(2 * λ₁) < minPixelSize`，**不带** SuperSplat 那个 `2 *`。
+ * five 的协方差在 pack 阶段整体 ×4，故 `λ_five = 4 * λ_real`，`sqrt(2 * λ_five)` 已等于
+ * `2 * sqrt(2 * λ_real)`。照抄 `2 *` 会让实际阈值变成 4 像素，症状是远景过度剔除。
+ */
+export declare const MIN_PIXEL_SIZE_DEFAULT = 2;
+/**
+ * 特征值分解中 `term2` 平方的下限。
+ *
+ * `term2 = sqrt(max(此值, traceOver2² - det))`，随后 `λ₁ = traceOver2 + term2`、
+ * `λ₂ = traceOver2 - term2`。**下限加在 term2 的平方上而不是加在 λ₂ 上**——这是 five 的写法，
+ * SuperSplat 的 `max(mid - radius, 0.1)` 是另一回事，两者效果相反（前者让 splat 更扁、
+ * 后者更圆）。用错位置的症状是所有小 splat 的形状都与 Fallback 不同。
+ *
+ * 被它压成 `λ₂ <= 0` 的点由 Projector 剔除，与 Fallback 的 `If(eigenValue2 > 0)` 对应。
+ */
+export declare const TERM2_SQ_FLOOR = 0.1;
+/**
+ * 屏幕半径上限的绝对上界（像素）。实际上限为 `min(此值, min(画面宽, 画面高))`。
+ *
+ * 取 2048 与 Fallback 的 `MAX_SCREEN_SPACE_SPLAT_SIZE` 及 five 的 `maxScreenSpaceSplatSize`
+ * 一致。曾取 1024，使近处超大 splat 在 Hybrid 上截断更早、两条路径可见不同。
+ */
+export declare const MAX_RADIUS_CAP = 2048;
+/**
+ * 协方差的 pack 量纲换算系数。pack 阶段把 3D 协方差整体 ×4 存入 half，故着色器内的 2D
+ * 协方差也是真实屏幕空间协方差的 4 倍。
+ *
+ * 屏幕空间低通核以 px²（方差）为单位给出，**加到对角线之前必须乘以本系数**。漏掉它补偿量
+ * 只有应有的四分之一。
+ *
+ * 不透明度补偿系数 `ρ = sqrt(det(Σ) / det(Σ+εI))` 与本系数无关：由行列式的齐次性
+ * `det(k·Σ) = k²·det(Σ)`，只要 ε 与 Σ 同样被 ×4，比值中的 k² 会约掉。
+ */
+export declare const COV_PACK_SCALE = 4;
+/**
+ * 未经抗锯齿训练的数据的默认纯膨胀量（屏幕空间方差 px²）。只放大 splat、**不**调整不透明度，
+ * 即 Inria 原版 3DGS 的 dilation trick，用于让亚像素 splat 不至于闪烁。
+ *
+ * 0.3 即 Inria 原版与 five 的取值。five 的 `cov2Dm` 是**真实**屏幕协方差（其打包阶段
+ * `packGSData.ts` 算 `Σ = R·S²·Rᵀ` 无缩放，`focal` 亦为标准定义），所以它加的 0.3 就是真实
+ * 的 0.3 px²。
+ *
+ * **本值曾被误设为 0.075**，依据是「five 往已 ×4 的协方差上加 0.3，换算回真实量纲即 0.3/4」。
+ * 那条推理把 **five-webgpu 自己 Fallback 的量纲 bug** 当成了 five 的行为：×4 只存在于本项目
+ * 的 `wasm/data.cpp`（`packHalf2x16(4.0f * s00, …)`），five 没有这一步。结果是两条路径的低通量
+ * 都只有 five 的四分之一，症状是小 splat 偏小偏锐、远景闪烁锯齿（大 splat 几乎无差别，因为
+ * 低通量占比小）。
+ */
+export declare const PRE_BLUR_DEFAULT_NON_AA = 0.3;
+/**
+ * 经抗锯齿训练的数据的默认 2D mip 低通核（屏幕空间方差 px²）。除膨胀协方差外还按
+ * `ρ = sqrt(det(Σ) / det(Σ + εI))` 补偿不透明度使能量守恒，等价于 gsplat 的
+ * `rasterize_mode="antialiased"`。
+ *
+ * 0.3 即 Mip-Splatting 训练时所用的核。**这个值不得改动**：抗锯齿训练拟合出的不透明度隐含
+ * 「渲染端会用同样的 ε 做补偿」这一假设。
+ *
+ * 两条路径都实现了本分支（Fallback 经 transforms 纹理 col 4 取每对象参数），故行为一致。
+ * five 没有这条路径，它对这类数据偏亮偏锐——**此处刻意不与 five 对齐**。
+ */
+export declare const BLUR_DEFAULT_AA = 0.3;
+/** 雅可比构造中深度的除零保护下限。取值同 SuperSplat 的 `max(depth, 0.001)`。 */
+export declare const DEPTH_EPSILON = 0.001;
+/** 不透明度补偿中行列式的除零保护下限。 */
+export declare const DET_EPSILON = 1e-9;

package/five/gaussian-splatting/hybridConstants.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 一个 draw instance 承载的 quad 数。**须与 `gsplatQuad.wgsl` 与 `gsplatHybridIndirect.wgsl`
+ * 的同名常量一致。**
+ *
+ * 它决定顶点数（`6 × 本值`）与 instance 数（`ceil(Render_Count / 本值)`，由 Indirect_Pass 在
+ * GPU 侧算）。取值越大 draw call 的 instance 数越少，但末个 instance 内空转的 quad 越多
+ * （空转 quad 由顶点着色器输出 degenerate 位置，代价极低）。
+ *
+ * 与 Fallback 的 `Effective_Instance_Size` 是两个独立的量：后者服务 TSL 材质的 Order_Texture
+ * 取点路径、可由用户调节；本常量编译期固定。
+ */
+export declare const QUAD_PER_INSTANCE = 128;
+/** 一个 quad 的索引数（两个三角形）。**须与 `gsplatQuad.wgsl` 的顶点取模除数一致。** */
+export declare const INDICES_PER_QUAD = 6;
+/**
+ * 一条 Projected_Record 的字节数。**布局表见 `gsplatProjector.wgsl` 与 `gsplatQuad.wgsl`
+ * 的文件头，两处必须逐字一致。**
+ *
+ * 20 字节 = 屏幕中心（snorm16×2）+ 线性视深度（f32）+ RGB（10/10/10 unorm + 2 bit 共享指数）
+ * + 椭圆长轴向量（f16×2）+ 短轴长度（f16）与 alpha（u8）。
+ *
+ * **短轴只存长度**，方向由长轴旋转 90° 重建（依据：2×2 对称矩阵的两个特征向量必定正交），
+ * 省下 2 字节。对照 PlayCanvas 的 `gsplat-unified` 用 32 字节。
+ */
+export declare const PROJECTED_RECORD_BYTES = 20;
+/** 一条 Projected_Record 占的 u32 数。storage buffer 按 u32 寻址。 */
+export declare const U32_PER_PROJECTED_RECORD = 5;
+/**
+ * Projector_Pass 的工作组线程数。**须与 `gsplatProjector.wgsl` 的 `@workgroup_size` 一致。**
+ *
+ * 它同时是紧凑写入的粒度：每个工作组用一次全局 `atomicAdd` 为组内存活点预留连续区间，
+ * 因此全局原子操作次数是 `ceil(Total_Points / 本值)` 而不是存活点数。
+ */
+export declare const PROJECTOR_WORKGROUP_SIZE = 256;
+/**
+ * `drawIndexedIndirect` 参数缓冲的字节数。
+ *
+ * 实需 20 字节（5 个 u32）。取 32 是为了将来追加第二组参数（排序间接派发化之后的 dispatch
+ * 三元组）不必改容量。usage 必须含 `GPUBufferUsage.INDIRECT`。
+ */
+export declare const INDIRECT_ARGS_BYTES = 32;
+/**
+ * 排序键的右移位数。**须与 `gsplatProjector.wgsl` 的 `SORT_KEY_SHIFT` 一致。**
+ *
+ * 键取「按位取反的深度位模式」右移 12 位：压到 20 位使 `RadixSortModule`（4 bit 一趟）的趟数
+ * 从 8 降到 5。丢掉的是尾数低 12 位、指数域完整保留，相当于一次对数量化，近处精度高、远处低。
+ */
+export declare const SORT_KEY_SHIFT = 12;
+/** 排序键的有效位宽，即 `RadixSortModule.encode` 的 `numBits` 实参。 */
+export declare const SORT_KEY_BITS: number;
+/**
+ * 无效槽位的排序键哨兵，20 位全 1。**须与 `gsplatProjector.wgsl` 的同名常量一致。**
+ *
+ * 排序按 `Total_Points` 上界派发，`[Render_Count, Total_Points)` 区间的键由 `fill_sort_keys`
+ * 入口预填本值从而排到末尾。它严格大于任何有效键：有限正浮点的指数域不全 1，故取反右移后
+ * 恒小于 `0xFFFFF`。
+ *
+ * **不能用 `clearBuffer` 填 0 代替**：升序排序里 0 是最小键，无效槽位会排到最前被优先绘制。
+ */
+export declare const SORT_KEY_INVALID: number;

package/five/gaussian-splatting/instancePacking.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Effective_Instance_Size 的上限。编译期固定常量，不随设备能力、GPU 型号、
+ * Total_Points 或 Pipeline_Mode 变化（Requirement 1.5 / 12.5）。
+ *
+ * 取 256 的依据：Packed_Quad_Geometry 顶点数 = 4K ≤ 1024，最大索引 = 4K - 1 ≤ 1023，
+ * 因此索引可继续用 Uint16Array 承载（PlayCanvas 用 Uint32Array 是因为它不设此上限）。
+ */
+export declare const MAX_INSTANCE_SIZE = 256;
+/** 求值失败原因，供调用方组织告警文案（`null` 表示取值合法）。 */
+export type InstanceSizeRejectReason = 'not-finite' | 'out-of-range' | 'cpu-path';
+export interface ResolveInstanceSizeResult {
+    /** Effective_Instance_Size，恒为 [1, MAX_INSTANCE_SIZE] 内整数。 */
+    readonly value: number;
+    /** 非 null 时表示 requested 未被原样采纳，调用方据此决定是否告警。 */
+    readonly reason: InstanceSizeRejectReason | null;
+}
+/**
+ * 把 Requested_Instance_Size 解析为 Effective_Instance_Size。
+ *
+ * **纯函数**：输出只由三个入参决定，不读写任何外部状态、不输出告警。
+ * 这是 Requirement 1.11（setter 内同步求值）与每帧求值两处结果一致的保证方式——
+ * 只要入参相同，两处必得同值，不需要缓存同步或脏标记。
+ *
+ * 签名中刻意不含 `totalPoints`，使 Requirement 1.10（求值不以 Total_Points 为输入）
+ * 从类型层面成立。`requested` 声明为 `unknown` 而非 `number`，使「写入非 number」
+ * 这条运行时路径在类型层面可达、不被 TS 判为死代码。
+ *
+ * @param requested 调用方写入的原始值（可能是任意 number，甚至非 number）
+ * @param currentPipelineMode Current_Pipeline_Mode（`GSPLAT_PIPELINE_RASTER_*`）
+ * @param pipelineResolved Current_Pipeline_Mode 是否已完成解析（首帧之前为 false）
+ */
+export declare function resolveInstanceSize(requested: unknown, currentPipelineMode: number, pipelineResolved: boolean): ResolveInstanceSizeResult;
+/**
+ * 生成 Packed_Quad_Geometry 的顶点与索引数据（Requirement 2.1 / 2.3）。
+ *
+ * 布局逐项对齐 PlayCanvas `GSplatResourceBase.createMesh`：第 i 个 quad 的 4 个顶点
+ * 依次为 `(-1,-1,i)`、`(1,-1,i)`、`(1,1,i)`、`(-1,1,i)`，6 个索引为
+ * `[b, b+1, b+2, b, b+2, b+3]`（`b = 4i`）。
+ *
+ * `quadCount = 1` 时产出与本特性引入前逐字节相同的数据（Requirement 2.6），
+ * 因此 `createGeometry()` 也走这个函数，不保留第二份硬编码。
+ */
+export declare function buildPackedQuadGeometryData(quadCount: number): {
+    positions: Float32Array;
+    indices: Uint16Array;
+};

package/five/gaussian-splatting/mirrors/layoutMirror.d.ts

@@ -0,0 +1,44 @@
+import { MirrorBuffer } from './mirrorBuffer';
+import type { ArenaLayoutEntry } from '../arena/splatArena';
+/**
+ * Arena 布局表的 GPU 镜像。
+ *
+ * `gsplat-compute-arena` 把这块镜像明确留给「第一个 Arena 消费方」，本特性即是该消费方。
+ * 剔除通道由点索引二分查找本表，取得该点所属对象的 transformIndex 与 layerIndex——
+ * **这是取这两个索引的唯一权威途径**，Arena 内 word7 只是源数据快照、不是权威值。
+ *
+ * 表项数量级为数十，二分查找约 5 至 6 轮，整张表远小于缓存行总量、必然常驻缓存。
+ * 备选方案「每点一个 tile 序号的数组」要多占 `点数 × 4` 字节（100 万点即 4 MB）
+ * 并多一个填充通道，已在 `gsplat-compute-arena` 的 design 中否决。
+ */
+export declare class LayoutMirror extends MirrorBuffer {
+    protected readonly bytesPerRecord: number;
+    protected readonly label = "layout";
+    private readonly getLayout;
+    /**
+     * 上次上传所对应的 Arena `revision`。初值 -1 使首次 `checkRevision` 必然置脏。
+     */
+    private lastRevision;
+    /**
+     * @param device 已就绪的 GPUDevice
+     * @param getLayout 取当前布局表的闭包。用闭包而非直接持有 `SplatArena`，是为了避免
+     *   镜像与 Arena 相互持有引用，也使本类不必关心 Arena 的可用性判定
+     */
+    constructor(device: GPUDevice, getLayout: () => readonly ArenaLayoutEntry[]);
+    /**
+     * 比对 Arena 的 `revision`，变化则置脏。
+     *
+     * **脏判据取 `revision` 而非 tile 集合哈希或对象数**：`revision` 是 Arena 自己维护的
+     * 权威信号，它在两种情况下递增——tile 集合变化，以及 Arena 因容量增长而重建。
+     * 后者同样需要重新确认布局表内容，用集合哈希会漏掉它。
+     *
+     * @param revision 当前 `SplatArena.revision`
+     */
+    checkRevision(revision: number): void;
+    /**
+     * 当前布局表项数。**着色器的二分查找必须用这个值作上界，不能用 `arrayLength`**——
+     * 后者返回的是按高水位分配的容量，大于实际项数时会落进未初始化的记录。
+     */
+    get entryCount(): number;
+    protected fill(): number;
+}

package/five/gaussian-splatting/mirrors/mirrorBuffer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * CPU 数据到 GPU storage buffer 的镜像。三块 Mirror 的共同骨架。
+ *
+ * 生命周期：`markDirty()` 由数据变化方调用 → `upload()` 由渲染器每帧调用（仅脏时真上传）
+ * → `dispose()` 释放。
+ *
+ * **`upload()` 必须在 encoder 之外调用**：它走 `device.queue.writeBuffer`，该调用与
+ * encoder 内命令的相对顺序由提交顺序决定，在 `submit` 之前调用即保证先生效。
+ */
+export declare abstract class MirrorBuffer {
+    /** 每条记录的字节数。子类给出，必须是 4 的整数倍。 */
+    protected abstract readonly bytesPerRecord: number;
+    /** 缓冲名，同时作为 Warn_Gate 的原因键。必须取自有限常量集合（见下方注释）。 */
+    protected abstract readonly label: string;
+    protected readonly device: GPUDevice;
+    /** CPU 侧暂存区，按容量分配，`upload()` 时整段或部分写入 GPU。 */
+    protected data: ArrayBuffer;
+    private buf;
+    /** 已分配的记录数（高水位，单调不减直到 dispose）。 */
+    private capacityRecords;
+    /** 当前有效记录数，由子类在 `fill()` 中确定。 */
+    private records;
+    private dirty;
+    private disposed;
+    constructor(device: GPUDevice);
+    /** GPU 缓冲。尚未分配或 `unusable` 时为 `null`。 */
+    get buffer(): GPUBuffer | null;
+    /** 当前有效记录数。消费方以它作为可读记录数的唯一上界。 */
+    get recordCount(): number;
+    /** 已 `dispose`。 */
+    get unusable(): boolean;
+    /** 本帧是否需要重传。供渲染器在诊断中观察，正常路径不需要读。 */
+    get isDirty(): boolean;
+    /**
+     * 标记需要重传。由数据变化方调用（例如 tile 集合变化、对象矩阵变化、补偿参数变化）。
+     *
+     * 刻意不做「自动检测变化」：那需要每帧比对全部记录内容，代价与直接重传相当，
+     * 而调用方本来就知道自己改了什么。
+     */
+    markDirty(): void;
+    /**
+     * 仅在脏时把 CPU 数据写进 GPU 缓冲。干净帧上传字节数为 0。
+     *
+     * 必须在 encoder 之外、且在任何读该缓冲的通道编码之前调用。
+     */
+    upload(): void;
+    /**
+     * 确保容量足够容纳 `needed` 条记录。容量不足时重建 GPU 缓冲与 CPU 暂存区。
+     *
+     * 由子类在 `fill()` 内、写入暂存区**之前**调用。
+     *
+     * 创建失败即抛，不做降级。
+     *
+     * @returns 是否可用（`false` 仅表示已 dispose）
+     */
+    protected ensureCapacity(needed: number): boolean;
+    /**
+     * 把 CPU 侧数据填进 `this.data`，返回有效记录数。
+     *
+     * 子类实现须：① 先调 `ensureCapacity()`；② 按 `bytesPerRecord` 步长写入；
+     * ③ 返回实际记录数，或返回 -1 表示本次无法填充（保持脏、下帧重试）。
+     */
+    protected abstract fill(): number;
+    /**
+     * 释放全部资源并置 `disposed`（单向不可逆）。
+     * 执行后 `buffer` 为 `null`、`recordCount` 为 0。
+     */
+    dispose(): void;
+    private destroyBuffer;
+    /** 开发期自检：子类的 `bytesPerRecord` 必须是 4 的整数倍。构造后调用一次即可。 */
+    protected assertAlignment(): void;
+}

package/five/gaussian-splatting/mirrors/mirrorSet.d.ts

@@ -0,0 +1,17 @@
+import type { LayoutMirror } from './layoutMirror';
+import type { TransformMirror } from './transformMirror';
+import type { ObjectParamsMirror } from './objectParamsMirror';
+/**
+ * Projector_Pass 所需的三块镜像。
+ *
+ * 打成一个对象传递而非三个独立参数：它们由 `Render_Mesh` 与 Arena 同一时机创建、同一时机
+ * 销毁，且任一缺失都要整体跳过 Projector_Pass。
+ */
+export interface GSplatMirrorSet {
+    /** Arena 布局表的镜像，同时提供二分查找的上界 `entryCount`。 */
+    readonly layout: LayoutMirror;
+    /** 每对象 `matrixWorld` 的镜像。 */
+    readonly transform: TransformMirror;
+    /** 每对象抗锯齿补偿参数的镜像。 */
+    readonly objectParams: ObjectParamsMirror;
+}

package/five/gaussian-splatting/mirrors/objectParamsMirror.d.ts

@@ -0,0 +1,35 @@
+import { MirrorBuffer } from './mirrorBuffer';
+import type { PBMGaussianSplattingObject } from '../../model/objects/pbmGaussianSplattingObject';
+/**
+ * 每对象屏幕空间抗锯齿补偿参数的 GPU 镜像。
+ *
+ * 剔除通道由 transformIndex 取本表，得到该对象的两个补偿量：
+ * - `preBlurAmount`：纯膨胀，只放大协方差、不动不透明度（用于**未经**抗锯齿训练的数据）
+ * - `blurAmount`：低通核，放大协方差**并**按 `sqrt(det(Σ)/det(Σ+εI))` 补偿不透明度
+ *   （用于经抗锯齿训练的数据，即 Mip-Splatting / gsplat 的 `rasterize_mode="antialiased"`）
+ *
+ * 两者的默认值由对象的 `antiAliased` 标志推导，业务方可按对象手动覆盖。
+ *
+ * 参数以**真实屏幕空间方差 px²**为单位，着色器加到协方差对角线之前须乘 `COV_PACK_SCALE`
+ * （= 4.0），因为 five 的协方差在 pack 阶段整体 ×4。
+ */
+export declare class ObjectParamsMirror extends MirrorBuffer {
+    protected readonly bytesPerRecord: number;
+    protected readonly label = "object-params";
+    private readonly getObjects;
+    /**
+     * @param device 已就绪的 GPUDevice
+     * @param getObjects 取当前有序对象列表的闭包。**其顺序必须与 `TransformStore` 的
+     *   对象索引顺序一致**，使 transformIndex 可直接作为本表的记录下标——调用方通过传入
+     *   与 `transformStore.sync` 同一个数组来保证这一点
+     */
+    constructor(device: GPUDevice, getObjects: () => readonly PBMGaussianSplattingObject[]);
+    /**
+     * 检查是否有对象的补偿参数发生变化，有则置脏。
+     *
+     * **不清除对象的 `renderParamsChanged` 标记**：该标记可能有其他消费方，清除责任不在本类。
+     * 重复重传数 KB 的代价远低于误清标记导致别处漏更新的风险。
+     */
+    checkDirty(): void;
+    protected fill(): number;
+}

package/five/gaussian-splatting/mirrors/transformMirror.d.ts

@@ -0,0 +1,26 @@
+import { MirrorBuffer } from './mirrorBuffer';
+import type { TransformStore } from '../transformStore';
+/**
+ * 每对象世界矩阵的 GPU 镜像。
+ *
+ * 剔除通道需要它把局部空间的位置与协方差变换到世界与视空间：
+ * `Σ_view = L · Σ_local · Lᵀ`，其中 `L` 是 `view × model` 的线性部分。
+ *
+ * **只镜像 16 个矩阵分量**，不含 `transformsTexture` 里的预算逆矩阵（col 5..8）与
+ * selected 标记（col 4）——剔除只需正向变换，选中态与剔除无关。
+ *
+ * 数据源取 `TransformStore.transforms`（公开 getter，每对象 20 float 步长，前 16 个是
+ * matrixWorld 列主序），因此**本类不需要改动 `TransformStore`**，只是只读取用它已维护的
+ * 数据（Requirement 1.14 / 13.2）。
+ */
+export declare class TransformMirror extends MirrorBuffer {
+    protected readonly bytesPerRecord: number;
+    protected readonly label = "transform";
+    private readonly getStore;
+    /**
+     * @param device 已就绪的 GPUDevice
+     * @param getStore 取 `TransformStore` 的闭包
+     */
+    constructor(device: GPUDevice, getStore: () => TransformStore);
+    protected fill(): number;
+}