@d5techs/3dgs-lib 1.4.84 → 1.4.86

package/dist/App.d.ts

@@ -74,11 +74,20 @@ export declare class App {
     private isRunning;
     private animationId;
     private useMobileRenderer;
+    private mobileOptimizationsEnabled;
+    private mobileMaxVisibleCap;
     private lastCompactData;
     private adaptivePerformanceEnabled;
     private adaptiveConfig;
     private lastAppliedRenderScale;
     private baseRenderScale;
+    private dynamicResolutionEnabled;
+    private dynResLastViewMatrix;
+    private dynResStillFrames;
+    private dynResCurrentScale;
+    private readonly DYNRES_MOVE_SCALE;
+    private readonly DYNRES_STILL_SCALE;
+    private readonly DYNRES_STILL_THRESHOLD;
     private boundOnResize;
     /** 额外渲染回调（在 gizmo 之前、场景辅助之后执行） */
     private extraRenderCallbacks;
@@ -94,9 +103,17 @@ export declare class App {
      */
     private applyAppleGPUDefaults;
     /**
-     * 创建桌面端 GSSplatRenderer 并自动应用平台优化
+     * 启用/禁用移动端性能优化（默认关闭）
+     * 开启后，加载模型时将自动应用：f16 半精度、16-bit 排序、像素剔除、动态分辨率等。
+     * 应在 init() 之后、加载模型之前调用。
      */
-    private createDesktopGSRenderer;
+    enableMobileOptimizations(enabled?: boolean): void;
+    isMobileOptimized(): boolean;
+    /**
+     * 创建 GSSplatRenderer 并自动应用平台优化
+     * @param forMobile 移动端模式：半精度（32B/splat）+ SH L0，内存降为 1/8
+     */
+    private createGSRendererUnified;
     /**
      * 加载 GLB 文件
      */
@@ -144,6 +161,7 @@ export declare class App {
      */
     stop(): void;
     private animate;
+    private updateDynamicResolution;
     private updateAdaptivePerformance;
     private render;
     private onResize;

package/dist/core/OrbitControls.d.ts

@@ -23,6 +23,7 @@ export declare class OrbitControls {
     enableDamping: boolean;
     dampingFactor: number;
     private isDragging;
+    get isInteracting(): boolean;
     private lastX;
     private lastY;
     private deltaTheta;
@@ -33,6 +34,7 @@ export declare class OrbitControls {
     private deltaPanZ;
     moveSpeed: number;
     private pressedKeys;
+    private _wasKeyboardMoving;
     private touchMode;
     private lastTouchDistance;
     private lastTouchCenter;
@@ -77,6 +79,12 @@ export declare class OrbitControls {
     private onTouchEnd;
     private getTouchDistance;
     private getTouchCenter;
+    /**
+     * 将 orbit 目标重新锚定到屏幕中心的模型表面点，
+     * 保持相机世界坐标不变，仅重算 distance/theta/phi。
+     * 用于 WASD 移动或触摸缩放结束后修复旋转中心偏移。
+     */
+    private recenterOrbitTarget;
     /**
      * 将球坐标写入相机位置（内部方法，不处理阻尼）
      */

package/dist/gs/GSSplatRenderer.d.ts

@@ -30,6 +30,12 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private sorter;
     private shMode;
     private boundingBox;
+    /** 紧凑布局模式：64B/splat，无 SH，适合移动端 */
+    private compactLayout;
+    /** 半精度模式：32B/splat，所有数据用 f16 打包 */
+    private halfPrecision;
+    /** 排序位宽：16-bit 排序减少一半 radix sort pass */
+    private sortBits;
     private uniformData;
     private cpuPositions;
     private position;
@@ -40,6 +46,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private pixelCullThreshold;
     private maxVisibleSplats;
     private depthRangeLimit;
+    private lodSkipRate;
     private lastSortViewMatrix;
     private lastSortProjMatrix;
     private lastSortModelMatrix;
@@ -51,6 +58,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private sortStateInitialized;
     private sortFrequency;
     private frameCounter;
+    private debugFrameLogged;
     private editorStateBuffer;
     private editorPipeline;
     private editorBindGroupLayout;
@@ -66,6 +74,21 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private dnRTHeight;
     private dnResult;
     constructor(renderer: Renderer, camera: Camera);
+    /**
+     * 启用/禁用紧凑布局模式（64B/splat，无 SH）。
+     * 必须在 setCompactData / setData 之前调用。
+     */
+    setCompactLayout(compact: boolean): void;
+    /**
+     * 设置排序位宽。16-bit 模式排序 pass 从 4 降到 2，排序速度翻倍。
+     * 必须在 setData / setCompactData 之前调用。
+     */
+    setSortBits(bits: 16 | 32): void;
+    /**
+     * 启用/禁用半精度模式（32B/splat，所有数据 f16 打包）。
+     * 自动启用 compactLayout。必须在 setCompactData 之前调用。
+     */
+    setHalfPrecision(half: boolean): void;
     private createPipeline;
     setDepthWriteEnabled(enabled: boolean): void;
     private createUniformBuffer;
@@ -99,6 +122,13 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
      */
     setDepthRangeLimit(limit: number): void;
     getDepthRangeLimit(): number;
+    /**
+     * 设置 LOD 抽稀率（0~1）
+     * 远处 splat 按此比例随机跳过（确定性哈希，无闪烁）
+     * 0 = 不抽稀
+     */
+    setLodSkipRate(rate: number): void;
+    getLodSkipRate(): number;
     /**
      * 设置排序频率
      * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推

package/dist/gs/GSSplatSorter.d.ts

@@ -2,7 +2,7 @@
  * GSSplatSorter - GPU Radix Sort 深度排序器
  *
  * 基于 rfs-gsplat-render 的 3-Pass Radix Sort 架构实现:
- * - 4 个 pass (8-bit 增量，总共 32 位)
+ * - N 个 pass (8-bit 增量，32 位或 16 位模式)
  * - 每个 pass 包含: Upsweep -> Spine -> Downsweep
  * - 稳定排序，解决远距离闪烁问题
  *
@@ -27,6 +27,8 @@ export interface CullingOptions {
     maxVisibleCount?: number;
     /** 深度范围限制（view-space 距离），超过此深度的 splat 被剔除，0 = 不限制 */
     depthRangeLimit?: number;
+    /** LOD 抽稀率（0~1），远处 splat 最多跳过此比例，0 = 不抽稀 */
+    lodSkipRate?: number;
 }
 /**
  * 排序器配置选项
@@ -67,19 +69,15 @@ export declare class GSSplatSorter {
     private spineBindGroups;
     private downsweepBindGroups;
     private numPartitions;
+    private numSortPasses;
     private screenWidth;
     private screenHeight;
     private cullingOptions;
-    constructor(device: GPUDevice, splatCount: number, splatBuffer: GPUBuffer, cameraBuffer: GPUBuffer, _options?: SorterOptions);
+    constructor(device: GPUDevice, splatCount: number, splatBuffer: GPUBuffer, cameraBuffer: GPUBuffer, _options?: SorterOptions, compact?: boolean, half?: boolean, sortBits?: 16 | 32);
     /**
      * 创建 Radix Sort 的 bind groups
-     * 4 个 pass，使用 ping-pong buffers
-     *
-     * Ping-pong 模式:
-     * - Pass 0: depthKeys/visibleIndices -> keysTempBuffer/valuesTempBuffer
-     * - Pass 1: keysTempBuffer/valuesTempBuffer -> depthKeys/visibleIndices
-     * - Pass 2: depthKeys/visibleIndices -> keysTempBuffer/valuesTempBuffer
-     * - Pass 3: keysTempBuffer/valuesTempBuffer -> (depthKeys)/sortedIndicesBuffer
+     * numSortPasses 个 pass，使用 ping-pong buffers
+     * 最后一个 pass 的 values 输出到 sortedIndicesBuffer
      */
     private createRadixSortBindGroups;
     /**
@@ -103,6 +101,11 @@ export declare class GSSplatSorter {
      * 获取 DrawIndirect buffer
      */
     getDrawIndirectBuffer(): GPUBuffer;
+    /**
+     * 异步读回 drawIndirect buffer 内容（调试用）
+     * 返回 [vertexCount, instanceCount, firstVertex, firstInstance]
+     */
+    readbackIndirect(): Promise<Uint32Array>;
     /**
      * 获取 splat 总数量
      */

package/dist/gs/PLYLoaderMobile.d.ts

@@ -74,3 +74,9 @@ export declare function parsePLYBuffer(buffer: ArrayBuffer, options?: MobileLoad
  * @param includeFullSH 是否包含完整 SH 系数（256 字节/splat），否则只包含基本数据（64 字节/splat）
  */
 export declare function compactDataToGPUBuffer(data: CompactSplatData, includeFullSH?: boolean): Float32Array;
+/**
+ * 半精度 GPU buffer：32 字节/splat = 8 × u32
+ * 布局：[mean.xy, mean.z|0, scale.xy, scale.z|opacity, rot.xy, rot.zw, color.rg, color.b|0]
+ * 使用 WGSL unpack2x16float 解码
+ */
+export declare function compactDataToGPUBufferHalf(data: CompactSplatData): Uint32Array;

package/dist/utils/DebugOverlay.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DebugOverlay — 移动端屏幕上的调试面板
+ * 用于在无法连接开发者工具时查看 WebGPU 错误和日志
+ */
+export declare class DebugOverlay {
+    private container;
+    private logList;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    log(msg: string, level?: "info" | "warn" | "error"): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    hide(): void;
+    show(): void;
+    /**
+     * 绑定 WebGPU device 的全局错误捕获
+     */
+    attachDevice(device: GPUDevice): void;
+    /**
+     * 检查 shader 编译结果
+     */
+    checkShader(module: GPUShaderModule, label: string): Promise<boolean>;
+    /**
+     * 包裹一个异步操作，捕获 validation/oom 错误
+     */
+    wrapGPU<T>(device: GPUDevice, label: string, fn: () => T): Promise<T>;
+}
+export declare function getDebugOverlay(): DebugOverlay | null;
+export declare function createDebugOverlay(): DebugOverlay;

package/dist/utils/index.d.ts

@@ -3,4 +3,5 @@
  */
 export { isMobileDevice, getRecommendedDPR, isWebGPUSupported, } from './device';
 export { computeBoundingBox, mergeBoundingBoxes, createBoundingBoxFromMinMax, transformBoundingBox, } from './geometry';
+export { DebugOverlay, getDebugOverlay, createDebugOverlay, } from './DebugOverlay';
 export { loadTextureFromURL, loadTextureFromBlob, loadTextureFromBuffer, createTextureFromImageBitmap, TextureCache, } from './texture';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d5techs/3dgs-lib",
-  "version": "1.4.84",
+  "version": "1.4.86",
   "description": "可扩展的 WebGPU 3D 渲染引擎",
   "type": "module",
   "main": "./dist/3dgs-lib.cjs",