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

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

@@ -0,0 +1,36 @@
+/** 单个合成管线及其 group(0) 绑定布局。 */
+export interface CompositePipeline {
+    readonly pipeline: GPURenderPipeline;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+}
+/** 合成管线集合；颜色格式变化时整体重建。 */
+export interface CompositePipelines {
+    readonly colorFormat: GPUTextureFormat;
+    /**
+     * 叠加合成。group(0)：binding 0 = 叠加平面（一个缓冲 R / G / B 三段，只读存储），
+     * binding 1 = {screenWidth, screenHeight}（u32×2 uniform，可复用显示参数缓冲）。
+     * 绘制：`draw(3)`，渲染通道只挂颜色附件。
+     */
+    readonly additive: CompositePipeline;
+    /**
+     * 层合成（混合半透明组）。group(0)：binding 0 = 透明层缓冲（只读存储），
+     * binding 1 = {screenWidth, screenHeight}（u32×2 uniform）。
+     * 混合因子用混合常量：每组渲染通道 `setBlendConstant(a)` 后 `draw(3)`，只挂颜色附件。
+     */
+    readonly blend: CompositePipeline;
+}
+/** 叠加合成着色器完整代码（常量 + composite-additive.wgsl）。 */
+export declare function buildCompositeAdditiveShaderCode(): string;
+/** 层合成着色器完整代码（composite-blend.wgsl，不依赖透明常量）。 */
+export declare function buildCompositeBlendShaderCode(): string;
+/** 叠加合成管线描述符的颜色目标：color = one/one/add，alpha = zero/one，只写 RGB。 */
+export declare function additiveColorTarget(colorFormat: GPUTextureFormat): GPUColorTargetState;
+/**
+ * 层合成管线描述符的颜色目标：color = constant/one-minus-constant/add（a 为混合常量），
+ * alpha = zero/one，只写 RGB。结果 = 层颜色 × a + 原颜色 × (1 − a)。
+ */
+export declare function blendColorTarget(colorFormat: GPUTextureFormat): GPUColorTargetState;
+/**
+ * 按合成渲染目标颜色格式创建合成管线。颜色格式变化时调用方应重新调用本函数。
+ */
+export declare function createCompositePipelines(device: GPUDevice, colorFormat: GPUTextureFormat): CompositePipelines;

package/five/renderer/compute-renderers/frame-plan.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 计算着色器点云每帧的绘制规划（纯函数，无 GPU 依赖）。
+ *
+ * - `classifyBlocks`：按块参数判定每块类别（跳过 / 不透明 / 叠加 / 混合半透明），并给出 a；
+ * - `groupBlendBlocks`：混合半透明块按 (楼层号, f32(a)) 分组，组间从远到近排序；
+ * - `planFrame`：按分类与分组结果生成本帧步骤序列（纯数据）；
+ * - `planExtraBufferReleases`：额外缓冲释放决策。
+ *
+ * 分类只看块自身参数与帧级相机朝向，结果与块顺序无关。
+ */
+import { type TileCategory } from './transparency-math';
+import type { PointCloudTransparencyMode } from './transparency-settings';
+/** 分类所需的块参数。 */
+export interface BlockParams {
+    floorIndex: number;
+    shownFloorIndex: number;
+    floorStyle: string;
+    opacity: number;
+    modelAlpha: number;
+    useAddBlend: boolean;
+}
+/** 每块绘制类别。 */
+export type BlockKind = 'skip' | 'opaque' | 'additive' | 'blend';
+/** 单块分类结果。 */
+export interface BlockClassification {
+    kind: BlockKind;
+    /** 点透明度 a（64 位，写入块参数时由 Float32 存储舍入） */
+    alpha: number;
+}
+/** 分类输入（帧级量 + 每块参数）。 */
+export interface ClassifyBlocksInput {
+    blocks: readonly BlockParams[];
+    /** 相机朝向 y 分量 */
+    cameraForwardY: number;
+    /** 半透明处理方式 */
+    mode: PointCloudTransparencyMode;
+    /** 透明层（及层写入流水线、层合成管线）是否可用；不可用时半透明块按不透明绘制 */
+    blendLayerAvailable: boolean;
+    /** 叠加平面（及叠加流水线、叠加合成管线）是否可用；不可用时跳过叠加块 */
+    additiveBufferAvailable: boolean;
+}
+/** 分类输出。`blocks[i]` 与输入 `blocks[i]` 一一对应。 */
+export interface ClassifyBlocksResult {
+    blocks: BlockClassification[];
+    hasAdditive: boolean;
+    hasBlend: boolean;
+}
+/** 单块分类，`classifyBlocks` 逐块调用。 */
+export declare function classifyBlock(block: BlockParams, cameraForwardY: number, mode: PointCloudTransparencyMode, blendLayerAvailable: boolean, additiveBufferAvailable: boolean): BlockClassification;
+/** 按块参数判定每块类别，输出顺序与输入一致。 */
+export declare function classifyBlocks(input: ClassifyBlocksInput): ClassifyBlocksResult;
+/** 非跳过类别对应的 `tilePack.z` 取值；跳过块返回 null。 */
+export declare function tileCategoryOf(kind: BlockKind): TileCategory | null;
+/** 分组输入：只取混合半透明块。 */
+export interface BlendBlockInput {
+    /** classifyBlocks 输出下标 */
+    index: number;
+    floorIndex: number;
+    /** 64 位 a，内部取 Math.fround */
+    alpha: number;
+    /** 世界空间包围盒 [minX, minY, minZ, maxX, maxY, maxZ]；没有包围盒时为 null */
+    worldBox: readonly number[] | null;
+}
+/** 一个半透明组。 */
+export interface BlendGroup {
+    /** 规整后的楼层号 */
+    floorIndex: number;
+    /** Math.fround(a)，层合成的混合常量 */
+    alpha: number;
+    /** 组距离：相机到组包围盒（各块世界包围盒的并集）的最近点距离 */
+    distance: number;
+    /** 组内块下标，升序 */
+    blockIndices: number[];
+}
+/**
+ * 楼层号规整：非有限值（NaN、±∞）→ 0（与 `PBMPointCloud.floorIndex` 的默认值相同），−0 → 0。
+ * 规整后才能作为分组键并参与排序比较。
+ */
+export declare function normalizeFloorIndex(f: number): number;
+/**
+ * 混合半透明块分组并按从远到近排序：
+ * 1. 键 = (normalizeFloorIndex(floorIndex), Math.fround(alpha))；
+ * 2. 组包围盒 = 组内各块 worldBox 的并集，缺失的不参与；
+ * 3. 组距离 = 相机到组包围盒的最近点距离，全部缺失时为 Number.MAX_VALUE；
+ * 4. 距离降序 → 楼层号升序 → a 升序（键唯一，排序为全序，与输入顺序无关）；
+ * 5. 每组 blockIndices 升序。
+ */
+export declare function groupBlendBlocks(blocks: readonly BlendBlockInput[], cameraPos: readonly [number, number, number]): BlendGroup[];
+/** 计算阶段：不透明（含非拆分帧的唯一计算通道）/ 混合半透明（每组一次）/ 叠加。 */
+export type FrameStage = 'opaque' | 'blend' | 'additive';
+/**
+ * 帧步骤（纯数据），描述本帧的执行顺序；five-renderer 从中取各计算阶段的块列表。
+ * - `clearCounters`：`encoder.clearBuffer(counters)`，每个计算阶段开始前一次；半透明组带组号；
+ * - `compute`：计算通道，`blockIndices` 为该阶段参与的块（`classifyBlocks` 输出下标，升序）；
+ * - `display`：像素缓冲全屏写入合成渲染目标的颜色和深度；
+ * - `threeScene`：非拆分帧整场景一次 `renderer.render`；
+ * - `threeOpaque` / `threeTransparent`：拆分帧的 three 不透明段 / 透明段；
+ * - `clearLayer`：清透明层（该组计算通道内的第一个调度）；
+ * - `compositeBlend`：层合成（混合常量 = 该组 a）；
+ * - `clearAdditive`：清零叠加平面（整个缓冲）；
+ * - `compositeAdditive`：叠加合成。
+ */
+export type FrameStep = {
+    kind: 'clearCounters';
+    stage: FrameStage;
+    group?: number;
+} | {
+    kind: 'compute';
+    stage: FrameStage;
+    group?: number;
+    blockIndices: number[];
+} | {
+    kind: 'display';
+} | {
+    kind: 'threeScene';
+} | {
+    kind: 'threeOpaque';
+} | {
+    kind: 'threeTransparent';
+} | {
+    kind: 'clearLayer';
+    group: number;
+} | {
+    kind: 'compositeBlend';
+    group: number;
+    alpha: number;
+} | {
+    kind: 'clearAdditive';
+} | {
+    kind: 'compositeAdditive';
+};
+/** 帧规划结果。 */
+export interface FramePlan {
+    /** 是否为拆分帧（存在混合半透明块或叠加块） */
+    split: boolean;
+    hasBlend: boolean;
+    hasAdditive: boolean;
+    /** 半透明组（远 → 近），与输入相同 */
+    groups: readonly BlendGroup[];
+    steps: FrameStep[];
+}
+/**
+ * 按分类与分组结果生成本帧步骤序列。
+ *
+ * 非拆分帧：清计数器 → 计算通道 → 显示通道 → three 整场景一次。
+ * 拆分帧：清计数器 → 计算通道1（不透明块）→ 显示通道 → three 不透明段
+ *   → [每组 g（远 → 近）：清计数器 → 清透明层 → 计算(blend) → 层合成(a_g)]
+ *   → [有叠加块：清零叠加平面 → 清计数器 → 叠加计算 → 叠加合成] → three 透明段。
+ * 拆分帧没有不透明块时计算通道1与显示通道照常执行，`blockIndices` 为空。
+ * 是否拆分只由本帧输入决定，流程切换从变化后的第一帧生效。
+ */
+export declare function planFrame(classification: ClassifyBlocksResult, groups: readonly BlendGroup[]): FramePlan;
+export interface ExtraBufferReleaseInput {
+    /** 本帧 scene.traverse 收集到的全部点云块中是否有 useAddBlend 为真的块 */
+    anyAddBlendParam: boolean;
+    /** 设置项的 pendingBlendRelease */
+    pendingBlendRelease: boolean;
+}
+export interface ExtraBufferReleasePlan {
+    /** 帧开头释放透明层（'blend' → 'opaque' 之后的第一次重绘） */
+    releaseLayerAtStart: boolean;
+    /** 帧末释放叠加平面（所有点云块的 useAddBlend 都为假） */
+    releaseAdditiveAtEnd: boolean;
+}
+/** 额外缓冲释放决策；缓冲不存在时调用方的释放为空操作。 */
+export declare function planExtraBufferReleases(input: ExtraBufferReleaseInput): ExtraBufferReleasePlan;

package/five/renderer/compute-renderers/gsplat-hybrid-renderer.d.ts

@@ -0,0 +1,386 @@
+import * as THREE from 'three/webgpu';
+import type { SplatArena } from '../../gaussian-splatting/arena/splatArena';
+import type { GSplatMirrorSet } from '../../gaussian-splatting/mirrors/mirrorSet';
+/**
+ * 取 three 纹理背后 `GPUTexture` 所需的最小 backend 接口（即 `renderer.backend`）。
+ * 只用 `get(texture).texture`，故不引入 three 内部类型。
+ */
+export interface HybridTextureBackend {
+    get(object: object): {
+        texture?: GPUTexture;
+    } | undefined;
+}
+/**
+ * 基于 compute 预投影 + 硬件光栅化的 3DGS 渲染器。
+ *
+ * 从调用方接收 `GPUDevice`，自身不请求 adapter / device。每帧一个 `GPUCommandEncoder`、
+ * 恰好一次 `queue.submit`；编码次序见 `submitFrame`。
+ */
+export declare class GSplatHybridRenderer {
+    private readonly device;
+    /** Composite_Target 的颜色格式，Draw_Pass 的管线状态需要它。 */
+    private readonly format;
+    /** 深度附件格式。与 three 的 Composite_Target 一致，构造期传入。 */
+    private readonly depthFormat;
+    /**
+     * 复用的通用基数排序模块。Fallback_Path 的排序链路正在用同一个类，**只实例化与调用、
+     * 不改其源码**。
+     *
+     * 它**不支持间接派发**（元素数恒为 CPU 已知值），故深度排序仍按 `Total_Points` 上界派发、
+     * 拿不到紧凑输出的收益；无效槽位靠哨兵排到末尾。
+     */
+    private radixSort;
+    /** Projector_Pass 的 uniform（176 字节，与 `gsplatCull.wgsl` 的 `FrameUniforms` 逐字段相同）。 */
+    private projectorUniformBuffer;
+    /** Draw_Pass 的 uniform（32 字节：viewport + projP22 + projP32 + pad）。 */
+    private drawUniformBuffer;
+    /**
+     * SH 烘焙 / clipper / 入场动画的逐帧参数（64 字节，与 `gsplatProjector.wgsl` 的
+     * `EffectUniforms` 逐字段相同）。写入见 `writeEffectUniform`。
+     */
+    private effectUniformBuffer;
+    /** 取 three 纹理背后 `GPUTexture` 用的 backend（构造期注入，缺省时恒走非 BAKED 变体）。 */
+    private readonly backend;
+    /** `SHBaker` 的 RenderTarget 纹理（引用，本类不持有其生命周期）。 */
+    private bakedTexture;
+    /** 调用方是否要求使用烘焙颜色（`appliedDegree > 0`）。 */
+    private bakedEnabled;
+    /**
+     * `GPUTexture → GPUTextureView` 缓存。RT 重建后 `GPUTexture` 换手，新句柄查不到缓存即新建
+     * view，view 换手又自然触发 bind group 重建；旧句柄随 GC 回收，不需要显式失效。
+     */
+    private readonly bakedViewCache;
+    /** 烘焙纹理内容版本号，`notifyBakedContentChanged` 自增；用于让静止帧复用失效。 */
+    private bakedContentRevision;
+    /**
+     * 每存活点 20 字节的紧凑记录。按 `Total_Points` 分配（存活数由 GPU 产生、CPU 分配时不可知），
+     * 高水位增长、单调不减。
+     */
+    private projectedCacheBuffer;
+    /** `projectedCacheBuffer` 已分配的点数容量（高水位）。 */
+    private projectedCacheCapacityPoints;
+    /**
+     * 深度排序键，每点一个 u32。容量按 2048 元素向上对齐，与
+     * `RadixSortModule.ELEMENTS_PER_WORKGROUP` 同粒度——该模块以 `destructiveKeys: true` 借用本
+     * 缓冲作 ping-pong 的一侧，容量小于它自己的分配会让末尾工作组写到缓冲之外。
+     */
+    private sortKeysBuffer;
+    /** `sortKeysBuffer` 已分配的元素数（2048 的整数倍，高水位）。 */
+    private sortKeysCapacityElements;
+    /**
+     * 存活点数，4 字节的原子计数器。三个消费者：Indirect_Pass 换算 instance 数、顶点着色器判
+     * 越界、回读给诊断。**顶点着色器读它必须绑为 `read-only-storage`**——它由 GPU 写，而
+     * uniform 只能由 CPU 写。
+     */
+    private renderCountBuffer;
+    /**
+     * `drawIndexedIndirect` 的参数（32 字节）。usage 必须含 `INDIRECT`。前 5 个字是 draw 五元组，
+     * 字 5-7 保留给排序间接派发化之后的 dispatch 三元组。
+     */
+    private indirectArgsBuffer;
+    /**
+     * quad 的索引缓冲，构造期一次性建、与点数无关。顶点着色器没有顶点缓冲（`CORNERS` 是着色器
+     * 内的常量数组），索引只用来驱动 `vertex_index`——**因此内容必须是恒等序列**，见
+     * `createQuadIndexBuffer`。
+     */
+    private quadIndexBuffer;
+    /** 廉价回读的 staging（4 字节，只带回 Render_Count）。 */
+    private readbackBuffer;
+    private readbackInFlight;
+    /** 最近一次成功回读到的存活点数；尚未回读成功过时为 `null`。 */
+    private lastRenderCount;
+    /**
+     * Projector 的两个编译变体（BAKED / 非 BAKED），每个含 `main` 与 `fill_sort_keys` 两条管线。
+     *
+     * `fill_sort_keys` 把 `sortKeys` 前 `Total_Points` 项填 `SORT_KEY_INVALID`。**与 Projector 同
+     * 模块、同 layout**，故不需要额外的 bind group，且必须在 Projector 之前、同一个 compute pass
+     * 内派发。不用 `clearBuffer`（填 0 会让无效槽位排到最前被优先绘制），也不用 CPU `writeBuffer`
+     * （每帧要上传 `Total_Points × 4` 字节）。
+     */
+    private readonly plainVariant;
+    private readonly bakedVariant;
+    private readonly indirectPipeline;
+    /**
+     * Draw_Pass 的渲染管线。混合与深度状态与 Fallback 材质等价（`NormalBlending`、深度只测不写）。
+     * 片元着色器输出**非预乘** alpha，由混合状态完成合成。
+     */
+    private readonly drawPipeline;
+    private readonly indirectBindGroupLayout;
+    /**
+     * Draw_Pass 的 bind group layout。**显式声明，不用 `layout: 'auto'`**——本项目在自动布局上
+     * 踩过坑（纹理可过滤性推导错误导致 `createBindGroup` 每帧抛错），且显式布局才能让「哪个
+     * binding 是什么」在 TS 侧一眼可查。
+     */
+    private readonly drawBindGroupLayout;
+    private projectorBindGroup;
+    /**
+     * Projector 通道的句柄快照。**含变体的 layout 与烘焙纹理的 `GPUTextureView`**，故元素类型比
+     * 另两条通道宽——纹理视图与缓冲一样可能被换手，同样要纳入比对。
+     */
+    private projectorSources;
+    private indirectBindGroup;
+    private indirectSources;
+    private drawBindGroup;
+    private drawSources;
+    private disposed;
+    /** 画面像素宽高，由 `resize` 维护。为 0 时 `submitFrame` 直接返回。 */
+    private width;
+    private height;
+    /** 上一帧的相机快照：`matrixWorld`（前 16）与 `projectionMatrix`（后 16）。 */
+    private readonly lastCameraSnapshot;
+    private lastArenaRevision;
+    private lastTotalPoints;
+    private lastViewportWidth;
+    private lastViewportHeight;
+    /** 上一帧所用的烘焙 view（非 BAKED 变体为 `null`）与烘焙内容版本。 */
+    private lastBakedView;
+    private lastBakedRevision;
+    /**
+     * 上一帧是否成功编码了完整的 compute 链。
+     *
+     * 只有为真时才允许复用——否则 `projectedCache` 与 `renderCount` 可能从未被写过，复用会画出
+     * 未初始化的内容。
+     */
+    private lastFrameComplete;
+    /** 已 `dispose`。为真时 `submitFrame` 第一行返回。 */
+    get unusable(): boolean;
+    /** 最近一次成功回读到的存活点数。`null` 表示尚未取到，与「存活为 0」语义不同。 */
+    get renderCount(): number | null;
+    private static readonly PROJECTOR_UNIFORM_SIZE;
+    private static readonly OFF_VIEW;
+    private static readonly OFF_VIEW_PROJ;
+    private static readonly OFF_FOCAL;
+    private static readonly OFF_VIEWPORT;
+    private static readonly OFF_TOTAL_POINTS;
+    private static readonly OFF_ENTRY_COUNT;
+    private static readonly OFF_MIN_PIXEL_SIZE;
+    private static readonly OFF_MAX_RADIUS_CAP;
+    private static readonly OFF_COV_PACK_SCALE;
+    private static readonly OFF_TERM2_SQ_FLOOR;
+    private static readonly OFF_DEPTH_EPSILON;
+    private static readonly OFF_DET_EPSILON;
+    private readonly projectorUniformScratch;
+    private static readonly DRAW_UNIFORM_SIZE;
+    private static readonly OFF_DRAW_VIEWPORT;
+    private static readonly OFF_DRAW_P22;
+    private static readonly OFF_DRAW_P32;
+    private readonly drawUniformScratch;
+    private static readonly EFFECT_UNIFORM_SIZE;
+    private static readonly OFF_AGG_BOUNDS_MIN;
+    private static readonly OFF_AGG_PROGRESS;
+    private static readonly OFF_AGG_BOUNDS_MAX;
+    private static readonly OFF_AGG_POINT_DURATION;
+    private static readonly OFF_CAMERA_WORLD_POS;
+    private static readonly OFF_AGG_ENABLED;
+    private static readonly OFF_SH_BAKED;
+    private static readonly OFF_NUM_GS_LAYERS;
+    private static readonly OFF_NUM_GS_CLIPPERS;
+    private readonly effectUniformScratch;
+    /** 廉价回读的字节数：只带回 Render_Count 一个 u32。 */
+    private static readonly CHEAP_READBACK_SIZE;
+    /** 每帧复用的 u32 写入 scratch，避免逐帧新建 typed array。 */
+    private readonly u32Scratch;
+    /**
+     * @param backend three 的 `renderer.backend`，用于取烘焙 RenderTarget 背后的 `GPUTexture`。
+     *   缺省时 `setBakedSource` 无效、恒走非 BAKED 变体
+     */
+    constructor(device: GPUDevice, format: GPUTextureFormat, depthFormat: GPUTextureFormat, backend?: HybridTextureBackend | null);
+    /**
+     * 建一个 Projector 变体：bind group layout + `main` / `fill_sort_keys` 两条管线。
+     *
+     * 前四项与 `gsplatCull.wgsl` 相同（Arena 与三块镜像），4-7 是本特性的输出与 uniform，
+     * 9（仅 BAKED）是烘焙纹理，11 是 Effect uniform。8 留给诊断变体的 gateCounters，10 未使用。
+     */
+    private createProjectorVariant;
+    /**
+     * 设置 SH 烘焙纹理来源。只保存引用，`GPUTexture` 在每帧 `prepareFrame` 时经
+     * `backend.get(texture).texture` 解析（RT 重建会换手）。`GPUTexture` 尚不存在（RT 未被渲染过）、
+     * 未注入 backend 或 `enabled = false` 时，本帧用非 BAKED 变体（SPZ DC 颜色）。
+     */
+    setBakedSource(texture: THREE.Texture | null, enabled: boolean): void;
+    /**
+     * 通知烘焙纹理内容已更新（本帧有烘焙任务）。纹理对象不变而内容变化时，静止帧的整链复用
+     * 必须失效，否则会重放旧颜色。
+     */
+    notifyBakedContentChanged(): void;
+    /** 解析本帧的烘焙 view；不可用时返回 `null`（本帧走非 BAKED 变体）。 */
+    private resolveBakedView;
+    /**
+     * 画面尺寸变更。**只记录尺寸，不重建任何资源**——本渲染器的缓冲全部按点数分配，与画面
+     * 尺寸无关（软光栅那条路径才有按方格数分配的缓冲）。
+     *
+     * 尺寸进入两处 uniform：Projector 的 `focal` / `viewport`（决定椭圆的像素尺寸与出屏判定），
+     * Draw 的 `viewport`（把像素单位的椭圆轴换算回 NDC）。两处都在 `submitFrame` 里逐帧写。
+     */
+    resize(width: number, height: number): void;
+    /** 创建一块缓冲。失败即抛，由调用栈冒泡出去暴露问题，不做降级。 */
+    private createBuffer;
+    private destroyBufferSafely;
+    /**
+     * 建 quad 的索引缓冲：`0, 1, 2, …, 6 * QUAD_PER_INSTANCE - 1` 的**恒等序列**。
+     *
+     * **indexed draw 里 `@builtin(vertex_index)` 就是索引缓冲里取出的那个值**，不是绘制序号。
+     * 而 `gsplatQuad.wgsl` 按 `vi / 6` 取 quadSlot、`vi % 6` 取 corner，因此索引内容只能是恒等
+     * 序列。最初照搬 Fallback packing 几何体的 `quad * 4 + [0,1,2, 0,2,3]`，结果 `vi` 拿到
+     * `0,1,2,0,2,3, 4,5,6,…`：第一个 quad 恰好正确、从第二个起全部错位，顶点互相串到别的 quad
+     * 上，画面变成无数无规则三角形而所有指标都正常。两者索引的职责不同——Fallback 有真正的顶点
+     * 缓冲、索引用来寻址顶点属性，本路径没有顶点缓冲、索引值直接成为 `vertex_index`。
+     *
+     * 恒等序列意味着这块缓冲不携带信息，`drawIndexedIndirect` 已退化成 `drawIndirect`。
+     * **后续可去掉本缓冲与 `setIndexBuffer`、把 Indirect_Pass 的输出改回 4 元组。**
+     */
+    private createQuadIndexBuffer;
+    /**
+     * 确保 Projected_Cache 的容量足够 `totalPoints` 个点。高水位增长、点数缩小时不缩容。
+     *
+     * @returns 是否可用。为 false 时调用方应跳过本帧
+     */
+    private ensureProjectedCache;
+    /**
+     * 确保排序键缓冲的容量足够。容量按 2048 元素向上对齐——与
+     * `RadixSortModule.ELEMENTS_PER_WORKGROUP` 同粒度，**这是硬要求而非保守估计**（理由见字段
+     * 声明处）。
+     */
+    private ensureSortKeys;
+    /**
+     * 写 Projector uniform 里**不随帧变化**的六个常量。构造期一次，此后不再写。
+     *
+     * 六个常量全部取自 `cullConstants.ts`，与 Fallback_Path 及诊断的 CPU 参考实现同源——
+     * 这是「常量唯一来源」这条性质的实现方式，不在着色器里写字面量。
+     */
+    private writeProjectorUniformConstants;
+    /**
+     * 写 Projector uniform 的逐帧字段：两个矩阵、focal、viewport、点数与布局表项数。
+     *
+     * 整块写 176 字节而不是逐字段写：常量部分早已在同一块 scratch 里，一次 `writeBuffer` 比
+     * 六次更省，且避免「改了字段忘了同步偏移」这类错误只在某个字段上显现。
+     */
+    private writeProjectorFrameUniform;
+    /**
+     * 写 Draw uniform：viewport 与投影矩阵的 `elements[10]` / `elements[14]`。顶点着色器用后两者
+     * 从线性视深度重建 `clip.z`。**用矩阵元素而非 `far/(far-near)` 闭式**，以自动适配正交与
+     * 非对称投影。
+     */
+    private writeDrawUniform;
+    private static sourcesEqual;
+    /**
+     * Projector 的 bind group。`variant` 与 `bakedView` 都纳入句柄快照：换变体（layout 不同）或
+     * 烘焙 RT 重建（view 换手）都会重建。
+     */
+    private ensureProjectorBindGroup;
+    private ensureIndirectBindGroup;
+    /**
+     * Draw_Pass 的 bind group。
+     *
+     * `sortedIndices` 由 `RadixSortModule.encode` 返回，**必须显式取用返回的句柄**并纳入快照：
+     * 它是模块内部 ping-pong 的一侧，身份随排序趟数的奇偶切换，不可按趟数推算。
+     */
+    private ensureDrawBindGroup;
+    /**
+     * 本帧数据未就绪，跳过绘制。多数原因（Arena 尚未 sync、点数为 0）是正常路径。
+     *
+     * 置 `lastFrameComplete = false`：本帧没有完整链路，下一帧不得复用
+     *（`projectedCache` 可能从未被写过）。
+     */
+    private reportSkip;
+    /**
+     * 写 Effect uniform 的逐帧字段：`cameraWorldPos`、`shBaked`（与本帧所选变体一致）。
+     * 入场动画与 clipper 的字段先占位（尚未迁进着色器），命中这两种情形的场景由
+     * `Render_Mesh` 侧强制回落 Fallback。
+     *
+     * `cameraWorldPos` 取 `matrixWorld` 的平移列而**不是** `matrixWorldInverse` 的——后者是
+     * `-R·t`、不是相机位置。
+     */
+    private writeEffectUniform;
+    /**
+     * 判定本帧能否直接重放上一帧的绘制结果（相机与数据都未变）。
+     *
+     * **必须在 `prepareFrame` 之前调用**：那里会 `upload()` 三块镜像，而 `upload` 会清掉
+     * `isDirty`，之后就查不出数据是否变过了。
+     *
+     * 相机比对取 `matrixWorld` 与 `projectionMatrix` 的全部元素而不是算出来的 `viewProj`：
+     * 前者是后者的唯一来源，逐元素相等即 `viewProj` 与 `focal` 都不变，且省一次矩阵乘法。
+     */
+    private canReplayLastFrame;
+    /** 记录本帧的相机与数据快照，供下一帧的复用判定使用。 */
+    private captureFrameSnapshot;
+    /**
+     * 把 3DGS 的绘制命令录进**外部传入的** render pass，不自己 `beginRenderPass`。
+     *
+     * 之所以不自建 pass：3DGS 在 Fallback 语义下是 transparent 队列的**第一个**对象
+     * （`Render_Mesh.renderOrder = -99999999999`），其后所有半透明与 overlay 对象都要叠在它之上。
+     * 自建 pass 只能排在 three 整个 `render()` 之后，等于把 3DGS 挪到全场最后画，把 grid、
+     * `intersectMesh`（`renderOrder = 9999999999`）这类顶层辅助元素全盖住。录进 three 正在用的
+     * 那条 pass、且时机取在 `Render_Mesh.onAfterRender`，位置才与 Fallback 逐帧一致。
+     *
+     * 附件与深度状态由 three 的 pass 决定，本方法只设 pipeline / bindGroup / indexBuffer。
+     * 「只测不写」仍由 `drawPipeline` 的 `depthWriteEnabled: false` 保证。
+     */
+    private encodeDrawInto;
+    /**
+     * 帧前准备：全部在 encoder 之外完成（镜像 upload、uniform 写入、按需扩容、bind group）。
+     *
+     * 返回 `null` 表示本帧不具备绘制条件，调用方跳过 ③~⑥ 但仍提交已编码的装配与清零（两者与
+     * 画面无关且幂等）。**镜像不可用不标记本渲染器不可用**——那是容量超限，与本渲染器自身的
+     * 资源无关，且降级由镜像自己记住。
+     */
+    private prepareFrame;
+    /**
+     * 编码并提交一帧。每帧一个 `GPUCommandEncoder`、恰好一次 `queue.submit`。
+     *
+     * ## 编码次序
+     *
+     * ```
+     * ① Arena 装配 → ② 清 renderCount / indirectArgs
+     * → ③ 一个 compute pass：fill_sort_keys → Projector → Indirect
+     * → ④ 深度排序 → ⑤ Render_Count 回读拷贝 → ⑥ submit（本类自己的 encoder）
+     * → ⑦ 把 Draw 命令录进 three 的 render pass（属于 three 的 command buffer）
+     * ```
+     *
+     * **⑥ 与 ⑦ 分属两个 command buffer**，这是被 WebGPU 的规则逼出来的：compute pass 不能在
+     * render pass 活跃期间开启，而本方法的调用时机（`Render_Mesh.onAfterRender`）正处在 three
+     * 的 render pass 内。于是 compute 走自己的 encoder 先 submit，draw 录进 three 那条 pass、
+     * 随 three 的 buffer 后 submit。同一 queue 按 submit 顺序执行且有隐式内存屏障，故 draw 一定
+     * 看得到 compute 的结果。反过来（draw 先 submit）会读到上一帧的 `projectedCache`。
+     *
+     * **① 必须最先**：拷贝命令一旦落在 pass 之后，Projector 读到的就是上一帧的 Arena 内容。
+     *
+     * **③ 三趟能合进一个 pass**：同 pass 内相邻 dispatch 之间有隐式的执行序与内存可见性保证，
+     * 而这三趟是一条线性依赖链（填哨兵 → 覆盖前 `Render_Count` 项并写计数器 → 读计数器写
+     * draw args）。前两趟共用同一个 bind group，故 `setBindGroup` 只调一次。
+     *
+     * **④ 不能也合进去**：`RadixSortModule.encode` 内部自己 `beginComputePass`。
+     *
+     * **⑦ 的附件由 three 的 pass 决定**，本类不再自建 render pass（理由见 `encodeDrawInto`）。
+     * `Render_Count` 为 0 时 `instanceCount` 也是 0，`drawIndexedIndirect` 是合法空操作，**故这
+     * 条命令照常录制**——跳过它需要 CPU 知道 Render_Count，而回读滞后一帧。
+     *
+     * @param drawPass three 当前活跃的 render pass，Draw 命令录进它（本类不 begin / 不 end）
+     * @param arena 装配器，为 `null` 时不编码任何拷贝、且跳过 ③~⑦
+     * @param camera 当前相机，`view` / `viewProj` / `focal` 都由它导出
+     * @param mirrors Projector_Pass 所需的三块镜像，为 `null` 时跳过 ③~⑦
+     */
+    submitFrame(drawPass: GPURenderPassEncoder, arena: SplatArena | null, camera: THREE.Camera, mirrors: GSplatMirrorSet | null): void;
+    /**
+     * 编码 Render_Count 的回读拷贝。已有回读在途时不编码（返回 `null`）。
+     *
+     * staging 每次新建、用完即销毁：4 字节的分配开销远低于「维护一个池子」的复杂度，且新建
+     * 天然避免「上一次的映射还没解除」这类状态纠缠。在途标志因此只用于抑制并发，不用于复用。
+     */
+    private encodeCheapReadback;
+    /**
+     * 完成一次 Render_Count 的回读。
+     *
+     * 失败静默：`dispose` 或 device lost 之后映射必然失败，那属于正常收尾而非故障。回读只服务
+     * 诊断（面板上的存活点数），失败不影响画面。
+     */
+    private finishCheapReadback;
+    /**
+     * 释放全部 GPU 资源。**幂等。** 管线与 layout 无需显式释放（WebGPU 无对应 API）；bind group
+     * 的引用置空使它们不再钉住被销毁的缓冲。
+     *
+     * 回读的 staging 不在这里销毁：它可能正处于 `mapAsync` 在途，由 `finishCheapReadback` 的
+     * `finally` 负责。
+     */
+    dispose(): void;
+}