@d5techs/3dgs-lib 1.4.6 → 1.4.8

package/dist/App.d.ts

@@ -77,6 +77,10 @@ export declare class App {
      * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
      */
     addSplat(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean, coordinateSystem?: CoordinateSystem): Promise<number>;
+    /**
+     * 将 SplatCPU[] 转换为 CompactSplatData（用于移动端渲染器）
+     */
+    private static splatCpuToCompactData;
     /**
      * 加载 SOG 文件 (Spatially Ordered Gaussians)
      * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
@@ -201,6 +205,33 @@ export declare class App {
     setAxesVisible(visible: boolean): void;
     getAxesVisible(): boolean;
     getSceneAidsRenderer(): SceneAidsRenderer;
+    /**
+     * 设置渲染缩放比例（影响内部分辨率）
+     * 0.5 = 半分辨率（性能提升约 4 倍），1.0 = 正常
+     * 适用于移动端提质或桌面端降负载
+     */
+    setRenderScale(scale: number): void;
+    getRenderScale(): number;
+    /**
+     * 覆盖自动 DPR，传 -1 恢复自动推荐
+     */
+    setDPR(dpr: number): void;
+    getDPR(): number;
+    /**
+     * 设置桌面端亚像素剔除阈值（默认 1.0）
+     * 值越大剔除越激进，近距离性能越好，但远处细节可能丢失
+     */
+    setPixelCullThreshold(threshold: number): void;
+    /**
+     * 设置桌面端最大可见 splat 数（0 = 不限制）
+     * 限制绘制数量是应对近距离卡顿最直接的手段
+     */
+    setMaxVisibleSplats(count: number): void;
+    /**
+     * 设置排序频率（1 = 每帧，2 = 每两帧，以此类推）
+     * 降低排序频率可提升帧率，代价是移动时短暂排序瑕疵
+     */
+    setSortFrequency(frequency: number): void;
     /**
      * 销毁应用及所有资源
      */

package/dist/core/Renderer.d.ts

@@ -12,6 +12,10 @@ export declare class Renderer {
     private commandEncoder;
     private renderPassEncoder;
     private resizeObserver;
+    private _renderScale;
+    private _customDPR;
+    private _lastCSSWidth;
+    private _lastCSSHeight;
     private _clearColor;
     constructor(canvas: HTMLCanvasElement);
     /**
@@ -46,6 +50,21 @@ export declare class Renderer {
      * 创建深度纹理
      */
     private createDepthTexture;
+    private getEffectiveDPR;
+    /**
+     * 设置渲染缩放比例，用于性能/质量权衡
+     * 0.5 = 半分辨率（性能提升约 4 倍），1.0 = 正常分辨率
+     * 内部等效于降低 DPR，不影响 CSS 布局尺寸
+     */
+    setRenderScale(scale: number): void;
+    getRenderScale(): number;
+    /**
+     * 覆盖自动 DPR 推荐值
+     * 传入 -1 恢复自动模式
+     */
+    setDPR(dpr: number): void;
+    getDPR(): number;
+    private applySize;
     /**
      * 设置 resize 监听
      */

package/dist/gs/GSSplatRendererMobile.d.ts

@@ -34,6 +34,9 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     private cpuPositions;
     private frameCount;
     private sortEveryNFrames;
+    private lastSortViewMatrix;
+    private lastSortProjMatrix;
+    private sortStateInitialized;
     private position;
     private rotation;
     private scaleValue;
@@ -82,13 +85,14 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
      * 获取当前模型矩阵
      */
     getModelMatrix(): Float32Array;
+    private dummySHTexture;
     /**
      * 创建渲染管线
      */
     private createPipeline;
     /**
      * 创建 uniform buffer
-     * 布局: view (64) + proj (64) + model (64) + cameraPos (12) + pad (4) + screenSize (8) + pad (8) + textureSize (8) + pad (8) = 240 bytes
+     * 布局: view(64) + proj(64) + model(64) + cameraPos(12)+pad(4) + screenSize(8)+pad(8) + textureSize(8)+shEnabled(4)+pad(4) = 240 bytes
      */
     private createUniformBuffer;
     /**
@@ -123,21 +127,10 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
      * @param n 每 n 帧排序一次
      */
     setSortFrequency(n: number): void;
-    /**
-     * 设置 SH 模式（移动端仅支持 L0）
-     */
-    setSHMode(mode: SHMode): void;
-    /**
-     * 获取当前 SH 模式
-     */
+    private hasCameraChanged;
+    setSHMode(_mode: SHMode): void;
     getSHMode(): SHMode;
-    /**
-     * 是否支持指定的 SH 模式
-     */
     supportsSHMode(mode: SHMode): boolean;
-    /**
-     * 获取渲染器能力
-     */
     getCapabilities(): RendererCapabilities;
     /**
      * 内部销毁资源（不销毁管线）

package/dist/gs/PLYLoaderMobile.d.ts

@@ -11,7 +11,8 @@
  */
 /**
  * 坐标系类型
- * - 'blender': Blender 坐标系 (Z-up, 右手系)，加载时自动将 Y/Z 对调转换为 WebGPU 的 Y-up 坐标系
+ * - 'blender': Blender 坐标系 (Z-up, 右手系)，加载时通过 Rx(-90°) 旋转转换为 WebGPU 的 Y-up 坐标系
+ *   变换: (x,y,z)→(x,z,-y)，保持右手系手性不变
  * - 'webgpu': WebGPU 坐标系 (Y-up)，数据已经是 Y-up 格式，不做转换
  */
 export type CoordinateSystem = 'blender' | 'webgpu';
@@ -51,8 +52,8 @@ export interface CompactSplatData {
     shCoeffs?: Float32Array;
 }
 /**
- * Y↔Z 轴交换时对 SH 系数的基函数变换（interleaved 格式）。
- * 对 L1/L2/L3 三个波段分别施加正交变换矩阵，使 SH 视角相关颜色在坐标变换后保持正确。
+ * Blender→WebGPU 坐标变换 Rx(-90°) 对 SH 系数的基函数变换（interleaved 格式）。
+ * 对 L1/L2/L3 三个波段分别施加 Wigner D-矩阵，使 SH 视角相关颜色在坐标变换后保持正确。
  */
 export declare function transformSHCoeffsYZSwap(sh: Float32Array, base: number, perChannel: number): void;
 /**

package/dist/gs/TextureCompressor.d.ts

@@ -28,6 +28,10 @@ export interface CompressedSplatTextures {
     scaleRotTexture1: GPUTexture;
     scaleRotTexture2: GPUTexture;
     colorTexture: GPUTexture;
+    shBasis0Texture: GPUTexture | null;
+    shBasis1Texture: GPUTexture | null;
+    shBasis2Texture: GPUTexture | null;
+    hasSH: boolean;
     boundingBox: {
         min: [number, number, number];
         max: [number, number, number];

package/package.json

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