@d5techs/3dgs-lib 1.4.7 → 1.4.8

package/dist/3dgs-lib.js

@@ -37,7 +37,7 @@ function isMobileDevice() {
 }
 function getRecommendedDPR() {
   const isMobile = isMobileDevice();
-  const maxDpr = isMobile ? 1.5 : 3;
+  const maxDpr = isMobile ? 2 : 2;
   return Math.min(window.devicePixelRatio || 1, maxDpr);
 }
 function isWebGPUSupported() {
@@ -252,6 +252,13 @@ class Renderer {
     __publicField(this, "renderPassEncoder");
     // ResizeObserver 引用（用于清理）
     __publicField(this, "resizeObserver", null);
+    // 渲染缩放：0.5 = 半分辨率，1.0 = 正常，用于性能/质量权衡
+    __publicField(this, "_renderScale", 1);
+    // 自定义 DPR 覆盖：-1 表示使用自动推荐值
+    __publicField(this, "_customDPR", -1);
+    // 缓存最后一次的 CSS 尺寸，用于 renderScale 变更时重算
+    __publicField(this, "_lastCSSWidth", 0);
+    __publicField(this, "_lastCSSHeight", 0);
     // 背景颜色
     __publicField(this, "_clearColor", { r: 0.15, g: 0.15, b: 0.15, a: 1 });
     this.canvas = canvas;
@@ -362,6 +369,45 @@ class Renderer {
     });
     this._depthTextureView = this._depthTexture.createView();
   }
+  getEffectiveDPR() {
+    const baseDPR = this._customDPR > 0 ? this._customDPR : getRecommendedDPR();
+    return baseDPR * this._renderScale;
+  }
+  /**
+   * 设置渲染缩放比例，用于性能/质量权衡
+   * 0.5 = 半分辨率（性能提升约 4 倍），1.0 = 正常分辨率
+   * 内部等效于降低 DPR，不影响 CSS 布局尺寸
+   */
+  setRenderScale(scale) {
+    this._renderScale = Math.max(0.25, Math.min(2, scale));
+    if (this._lastCSSWidth > 0 && this._lastCSSHeight > 0) {
+      this.applySize(this._lastCSSWidth, this._lastCSSHeight);
+    }
+  }
+  getRenderScale() {
+    return this._renderScale;
+  }
+  /**
+   * 覆盖自动 DPR 推荐值
+   * 传入 -1 恢复自动模式
+   */
+  setDPR(dpr) {
+    this._customDPR = dpr;
+    if (this._lastCSSWidth > 0 && this._lastCSSHeight > 0) {
+      this.applySize(this._lastCSSWidth, this._lastCSSHeight);
+    }
+  }
+  getDPR() {
+    return this._customDPR > 0 ? this._customDPR : getRecommendedDPR();
+  }
+  applySize(cssWidth, cssHeight) {
+    this._lastCSSWidth = cssWidth;
+    this._lastCSSHeight = cssHeight;
+    const dpr = this.getEffectiveDPR();
+    this.canvas.width = Math.max(1, Math.floor(cssWidth * dpr));
+    this.canvas.height = Math.max(1, Math.floor(cssHeight * dpr));
+    this.createDepthTexture();
+  }
   /**
    * 设置 resize 监听
    */
@@ -369,10 +415,7 @@ class Renderer {
     this.resizeObserver = new ResizeObserver((entries) => {
       for (const entry of entries) {
         const { width, height } = entry.contentRect;
-        const dpr = getRecommendedDPR();
-        this.canvas.width = Math.floor(width * dpr);
-        this.canvas.height = Math.floor(height * dpr);
-        this.createDepthTexture();
+        this.applySize(width, height);
       }
     });
     this.resizeObserver.observe(this.canvas);
@@ -8434,6 +8477,65 @@ function compressSplatsToTextures(device, data) {
     { bytesPerRow: width * 4 },
     { width, height }
   );
+  let shBasis0Texture = null;
+  let shBasis1Texture = null;
+  let shBasis2Texture = null;
+  const hasSH = !!(data.shCoeffs && data.shCoeffs.length >= count * 45);
+  if (hasSH) {
+    const shCoeffs = data.shCoeffs;
+    const sh0Data = new Float32Array(totalPixels * 4);
+    const sh1Data = new Float32Array(totalPixels * 4);
+    const sh2Data = new Float32Array(totalPixels * 4);
+    for (let i = 0; i < count; i++) {
+      const base = i * 45;
+      const px = i * 4;
+      sh0Data[px + 0] = shCoeffs[base + 0];
+      sh0Data[px + 1] = shCoeffs[base + 1];
+      sh0Data[px + 2] = shCoeffs[base + 2];
+      sh1Data[px + 0] = shCoeffs[base + 3];
+      sh1Data[px + 1] = shCoeffs[base + 4];
+      sh1Data[px + 2] = shCoeffs[base + 5];
+      sh2Data[px + 0] = shCoeffs[base + 6];
+      sh2Data[px + 1] = shCoeffs[base + 7];
+      sh2Data[px + 2] = shCoeffs[base + 8];
+    }
+    shBasis0Texture = device.createTexture({
+      size: { width, height },
+      format: "rgba32float",
+      usage: textureUsage,
+      label: "sh-basis0"
+    });
+    shBasis1Texture = device.createTexture({
+      size: { width, height },
+      format: "rgba32float",
+      usage: textureUsage,
+      label: "sh-basis1"
+    });
+    shBasis2Texture = device.createTexture({
+      size: { width, height },
+      format: "rgba32float",
+      usage: textureUsage,
+      label: "sh-basis2"
+    });
+    device.queue.writeTexture(
+      { texture: shBasis0Texture },
+      sh0Data,
+      { bytesPerRow: width * 16 },
+      { width, height }
+    );
+    device.queue.writeTexture(
+      { texture: shBasis1Texture },
+      sh1Data,
+      { bytesPerRow: width * 16 },
+      { width, height }
+    );
+    device.queue.writeTexture(
+      { texture: shBasis2Texture },
+      sh2Data,
+      { bytesPerRow: width * 16 },
+      { width, height }
+    );
+  }
   return {
     width,
     height,
@@ -8442,6 +8544,10 @@ function compressSplatsToTextures(device, data) {
     scaleRotTexture1,
     scaleRotTexture2,
     colorTexture,
+    shBasis0Texture,
+    shBasis1Texture,
+    shBasis2Texture,
+    hasSH,
     boundingBox
   };
 }
@@ -8450,9 +8556,12 @@ function destroyCompressedTextures(textures) {
   textures.scaleRotTexture1.destroy();
   textures.scaleRotTexture2.destroy();
   textures.colorTexture.destroy();
+  if (textures.shBasis0Texture) textures.shBasis0Texture.destroy();
+  if (textures.shBasis1Texture) textures.shBasis1Texture.destroy();
+  if (textures.shBasis2Texture) textures.shBasis2Texture.destroy();
 }
 const DEFAULT_NUM_BUCKETS = 65536;
-const IOS_NUM_BUCKETS = 4096;
+const IOS_NUM_BUCKETS = 16384;
 const WORKGROUP_SIZE = 256;
 function isIOSDevice() {
   if (typeof navigator === "undefined") return false;
@@ -8956,9 +9065,17 @@ class GSSplatSorterMobile {
     this.drawIndirectBuffer.destroy();
   }
 }
-const shaderCodeMobileL0 = (
+const shaderCodeMobile = (
   /* wgsl */
   `
+
+const SH_C1: f32 = 0.4886025119029199;
+const GAUSSIAN_K: f32 = 4.0;
+const EXP_NEG_K: f32 = 0.01831563888873418;
+const INV_ONE_MINUS_EXP_NEG_K: f32 = 1.01865736036377408;
+const ALPHA_CULL_THRESHOLD: f32 = 0.00392156863;
+const LOW_PASS_FILTER: f32 = 0.3;
+
 struct Uniforms {
   view: mat4x4<f32>,
   proj: mat4x4<f32>,
@@ -8967,18 +9084,21 @@ struct Uniforms {
   _pad: f32,
   screenSize: vec2<f32>,
   _pad2: vec2<f32>,
-  textureSize: vec2<f32>,  // 纹理尺寸 (用于坐标计算)
-  _pad3: vec2<f32>,
+  textureSize: vec2<f32>,
+  shEnabled: f32,
+  _pad3: f32,
 }
 
 @group(0) @binding(0) var<uniform> uniforms: Uniforms;
 @group(0) @binding(1) var<storage, read> sortedIndices: array<u32>;
 
-// 纹理绑定 - 4 张纹理（使用 RGBA32Float 保证精度）
-@group(1) @binding(0) var positionTex: texture_2d<f32>;   // RGBA32Float: xyz + unused
-@group(1) @binding(1) var scaleRotTex1: texture_2d<f32>;  // RGBA32Float: scale_xyz + rot_w
-@group(1) @binding(2) var scaleRotTex2: texture_2d<f32>;  // RGBA32Float: rot_xyz + unused
-@group(1) @binding(3) var colorTex: texture_2d<f32>;      // RGBA8Unorm: rgb + opacity
+@group(1) @binding(0) var positionTex: texture_2d<f32>;
+@group(1) @binding(1) var scaleRotTex1: texture_2d<f32>;
+@group(1) @binding(2) var scaleRotTex2: texture_2d<f32>;
+@group(1) @binding(3) var colorTex: texture_2d<f32>;
+@group(1) @binding(4) var shBasis0Tex: texture_2d<f32>;
+@group(1) @binding(5) var shBasis1Tex: texture_2d<f32>;
+@group(1) @binding(6) var shBasis2Tex: texture_2d<f32>;
 
 struct VertexOutput {
   @builtin(position) position: vec4<f32>,
@@ -8996,7 +9116,6 @@ const QUAD_POSITIONS = array<vec2<f32>, 4>(
 
 const ELLIPSE_SCALE: f32 = 3.0;
 
-// 将索引转换为纹理坐标
 fn indexToTexCoord(index: u32) -> vec2<u32> {
   let texWidth = u32(uniforms.textureSize.x);
   let x = index % texWidth;
@@ -9004,7 +9123,6 @@ fn indexToTexCoord(index: u32) -> vec2<u32> {
   return vec2<u32>(x, y);
 }
 
-// 四元数转旋转矩阵
 fn quatToMat3(q: vec4<f32>) -> mat3x3<f32> {
   let w = q[0]; let x = q[1]; let y = q[2]; let z = q[3];
   let x2 = x + x; let y2 = y + y; let z2 = z + z;
@@ -9018,15 +9136,12 @@ fn quatToMat3(q: vec4<f32>) -> mat3x3<f32> {
   );
 }
 
-// 从模型矩阵提取统一缩放因子（取 X 轴向量长度）
 fn getModelScale(model: mat4x4<f32>) -> f32 {
   return length(model[0].xyz);
 }
 
-// 计算 2D 协方差
 fn computeCov2D(mean: vec3<f32>, scale: vec3<f32>, rotation: vec4<f32>, modelView: mat4x4<f32>, proj: mat4x4<f32>, modelScale: f32) -> vec3<f32> {
   let R = quatToMat3(rotation);
-  // 应用模型缩放到 splat scale
   let scaledScale = scale * modelScale;
   let s2 = scaledScale * scaledScale;
   let M = mat3x3<f32>(R[0] * s2.x, R[1] * s2.y, R[2] * s2.z);
@@ -9038,8 +9153,6 @@ fn computeCov2D(mean: vec3<f32>, scale: vec3<f32>, rotation: vec4<f32>, modelVie
   let z = -viewPos.z;
   let z_clamped = max(z, 0.001);
   let z2 = z_clamped * z_clamped;
-  // 雅可比矩阵: 从相机坐标 (x_cam, y_cam, z_cam) 到 NDC 的偏导数
-  // x_ndc = fx * x_cam / (-z_cam), 所以 dx_ndc/dz_cam = fx * x_cam / z_cam^2 (正号!)
   let j1 = vec3<f32>(fx / z_clamped, 0.0, fx * viewPos.x / z2);
   let j2 = vec3<f32>(0.0, fy / z_clamped, fy * viewPos.y / z2);
   let Sj1 = SigmaView * j1;
@@ -9047,17 +9160,22 @@ fn computeCov2D(mean: vec3<f32>, scale: vec3<f32>, rotation: vec4<f32>, modelVie
   return vec3<f32>(dot(j1, Sj1), dot(j1, Sj2), dot(j2, Sj2));
 }
 
-// 计算椭圆轴
 fn computeEllipseAxes(cov2D: vec3<f32>) -> mat2x2<f32> {
-  let a = cov2D.x; let b = cov2D.y; let c = cov2D.z;
+  var cov = cov2D;
+  cov.x += LOW_PASS_FILTER;
+  cov.z += LOW_PASS_FILTER;
+  let a = cov.x; let b = cov.y; let c = cov.z;
   let trace = a + c;
   let det = a * c - b * b;
   let disc = trace * trace - 4.0 * det;
   let sqrtDisc = sqrt(max(disc, 0.0));
   let lambda1 = max((trace + sqrtDisc) * 0.5, 0.0);
   let lambda2 = max((trace - sqrtDisc) * 0.5, 0.0);
-  let r1 = sqrt(lambda1);
-  let r2 = sqrt(lambda2);
+  if (lambda2 <= 0.0) {
+    return mat2x2<f32>(vec2<f32>(0.0), vec2<f32>(0.0));
+  }
+  let r1 = min(2.0 * sqrt(2.0 * lambda1), 1024.0);
+  let r2 = min(2.0 * sqrt(2.0 * lambda2), 1024.0);
   var axis1: vec2<f32>; var axis2: vec2<f32>;
   if (abs(b) > 1e-6) {
     axis1 = normalize(vec2<f32>(b, lambda1 - a));
@@ -9073,59 +9191,88 @@ fn computeEllipseAxes(cov2D: vec3<f32>) -> mat2x2<f32> {
 fn vs_main(@builtin(vertex_index) vertexIndex: u32, @builtin(instance_index) instanceIndex: u32) -> VertexOutput {
   var output: VertexOutput;
   
-  // 获取排序后的索引
   let splatIndex = sortedIndices[instanceIndex];
   let texCoord = indexToTexCoord(splatIndex);
   
-  // 从纹理采样位置数据（RGBA32Float，直接读取）
   let posSample = textureLoad(positionTex, texCoord, 0);
   let mean = posSample.xyz;
   
-  // 从纹理采样缩放和旋转（RGBA16Float，GPU 自动转换为 f32）
   let scaleRot1 = textureLoad(scaleRotTex1, texCoord, 0);
   let scaleRot2 = textureLoad(scaleRotTex2, texCoord, 0);
-  
   let scale = scaleRot1.xyz;
   let rotation = vec4<f32>(scaleRot1.w, scaleRot2.x, scaleRot2.y, scaleRot2.z);
   
-  // 从纹理采样颜色（RGBA8Unorm，GPU 自动归一化到 0-1）
   let colorSample = textureLoad(colorTex, texCoord, 0);
-  let color = colorSample.rgb;
+  var color = colorSample.rgb;
   let opacity = colorSample.a;
+
+  if (opacity < ALPHA_CULL_THRESHOLD) {
+    output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0);
+    return output;
+  }
   
-  // 计算顶点位置
   let quadPos = QUAD_POSITIONS[vertexIndex];
   output.localUV = quadPos;
   
-  // 计算 modelView 矩阵和模型缩放
   let modelView = uniforms.view * uniforms.model;
   let modelScale = getModelScale(uniforms.model);
   
   let cov2D = computeCov2D(mean, scale, rotation, modelView, uniforms.proj, modelScale);
   let axes = computeEllipseAxes(cov2D);
-  let screenOffset = axes[0] * quadPos.x * ELLIPSE_SCALE + axes[1] * quadPos.y * ELLIPSE_SCALE;
+
+  if (axes[0].x == 0.0 && axes[0].y == 0.0 && axes[1].x == 0.0 && axes[1].y == 0.0) {
+    output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0);
+    return output;
+  }
+
+  let basisViewport = vec2<f32>(1.0 / uniforms.screenSize.x, 1.0 / uniforms.screenSize.y);
+  let ndcOffset = (quadPos.x * axes[0] + quadPos.y * axes[1]) * basisViewport * 2.0;
   
-  // 应用 model 变换到 splat 位置
   let worldPos = uniforms.model * vec4<f32>(mean, 1.0);
   let viewPos = uniforms.view * worldPos;
-  var clipPos = uniforms.proj * viewPos;
-  clipPos.x = clipPos.x + screenOffset.x * clipPos.w;
-  clipPos.y = clipPos.y + screenOffset.y * clipPos.w;
-  output.position = clipPos;
+  let clipPos = uniforms.proj * viewPos;
+  let pW = 1.0 / (clipPos.w + 0.0000001);
+  let ndcPos = clipPos * pW;
+
+  if (abs(ndcPos.x) > 1.3 || abs(ndcPos.y) > 1.3 || ndcPos.z < -0.2 || ndcPos.z > 1.0) {
+    output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0);
+    return output;
+  }
+
+  output.position = vec4<f32>(ndcPos.xy + ndcOffset, ndcPos.z, 1.0);
+
+  // L1 SH evaluation
+  if (uniforms.shEnabled > 0.5) {
+    let sh_b0 = textureLoad(shBasis0Tex, texCoord, 0).xyz;
+    let sh_b1 = textureLoad(shBasis1Tex, texCoord, 0).xyz;
+    let sh_b2 = textureLoad(shBasis2Tex, texCoord, 0).xyz;
+    
+    let viewDir = worldPos.xyz - uniforms.cameraPos;
+    let shDir = normalize(vec3<f32>(
+      dot(viewDir, uniforms.model[0].xyz),
+      dot(viewDir, uniforms.model[1].xyz),
+      dot(viewDir, uniforms.model[2].xyz)
+    ));
+    
+    color += (-SH_C1 * shDir.y) * sh_b0
+          +  ( SH_C1 * shDir.z) * sh_b1
+          +  (-SH_C1 * shDir.x) * sh_b2;
+  }
+
   output.color = color;
   output.opacity = opacity;
-  
   return output;
 }
 
 @fragment
 fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
-  let r = length(input.localUV);
-  if (r > 1.0) { discard; }
-  let gaussianWeight = exp(-r * r * 4.0);
-  let alpha = input.opacity * gaussianWeight;
-  if (alpha < 0.004) { discard; }  // 丢弃几乎透明的像素
-  let color = clamp(input.color, vec3<f32>(0.0), vec3<f32>(1.0));
+  if (input.opacity <= 0.0) { discard; }
+  let A = dot(input.localUV, input.localUV);
+  if (A > 1.0) { discard; }
+  let weight = (exp(-GAUSSIAN_K * A) - EXP_NEG_K) * INV_ONE_MINUS_EXP_NEG_K;
+  let alpha = input.opacity * weight;
+  if (alpha < ALPHA_CULL_THRESHOLD) { discard; }
+  let color = max(input.color, vec3<f32>(0.0));
   return vec4<f32>(color * alpha, alpha);
 }
 `
@@ -9155,6 +9302,10 @@ class GSSplatRendererMobile {
     // 帧计数（用于排序频率控制）
     __publicField(this, "frameCount", 0);
     __publicField(this, "sortEveryNFrames", 1);
+    // 相机静止检测：跳过不必要的排序
+    __publicField(this, "lastSortViewMatrix", new Float32Array(16));
+    __publicField(this, "lastSortProjMatrix", new Float32Array(16));
+    __publicField(this, "sortStateInitialized", false);
     // ============================================
     // 变换相关 (position, rotation, scale)
     // ============================================
@@ -9165,6 +9316,8 @@ class GSSplatRendererMobile {
     __publicField(this, "pivot", [0, 0, 0]);
     // 旋转/缩放中心点
     __publicField(this, "modelMatrix", new Float32Array(16));
+    // 1x1 dummy SH 纹理（当无 SH 数据时使用）
+    __publicField(this, "dummySHTexture", null);
     this.renderer = renderer;
     this.camera = camera;
     this.createPipeline();
@@ -9286,7 +9439,7 @@ class GSSplatRendererMobile {
   createPipeline() {
     const device = this.renderer.device;
     const shaderModule = device.createShaderModule({
-      code: shaderCodeMobileL0,
+      code: shaderCodeMobile,
       label: "mobile-splat-shader"
     });
     this.uniformBindGroupLayout = device.createBindGroupLayout({
@@ -9303,32 +9456,27 @@ class GSSplatRendererMobile {
         }
       ]
     });
+    const texEntry = (binding) => ({
+      binding,
+      visibility: GPUShaderStage.VERTEX,
+      texture: { sampleType: "unfilterable-float" }
+    });
     this.textureBindGroupLayout = device.createBindGroupLayout({
       entries: [
-        {
-          // positionTex (RGBA32Float)
-          binding: 0,
-          visibility: GPUShaderStage.VERTEX,
-          texture: { sampleType: "unfilterable-float" }
-        },
-        {
-          // scaleRotTex1 (RGBA32Float)
-          binding: 1,
-          visibility: GPUShaderStage.VERTEX,
-          texture: { sampleType: "unfilterable-float" }
-        },
-        {
-          // scaleRotTex2 (RGBA32Float)
-          binding: 2,
-          visibility: GPUShaderStage.VERTEX,
-          texture: { sampleType: "unfilterable-float" }
-        },
-        {
-          // colorTex (RGBA8Unorm)
-          binding: 3,
-          visibility: GPUShaderStage.VERTEX,
-          texture: { sampleType: "unfilterable-float" }
-        }
+        texEntry(0),
+        // positionTex
+        texEntry(1),
+        // scaleRotTex1
+        texEntry(2),
+        // scaleRotTex2
+        texEntry(3),
+        // colorTex
+        texEntry(4),
+        // shBasis0Tex
+        texEntry(5),
+        // shBasis1Tex
+        texEntry(6)
+        // shBasis2Tex
       ]
     });
     const pipelineLayout = device.createPipelineLayout({
@@ -9372,10 +9520,16 @@ class GSSplatRendererMobile {
         depthCompare: "always"
       }
     });
+    this.dummySHTexture = device.createTexture({
+      size: { width: 1, height: 1 },
+      format: "rgba32float",
+      usage: GPUTextureUsage.TEXTURE_BINDING,
+      label: "dummy-sh"
+    });
   }
   /**
    * 创建 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
    */
   createUniformBuffer() {
     this.uniformBuffer = this.renderer.device.createBuffer({
@@ -9436,35 +9590,22 @@ class GSSplatRendererMobile {
     this.uniformBindGroup = device.createBindGroup({
       layout: this.uniformBindGroupLayout,
       entries: [
-        {
-          binding: 0,
-          resource: { buffer: this.uniformBuffer }
-        },
-        {
-          binding: 1,
-          resource: { buffer: this.sorter.getIndicesBuffer() }
-        }
+        { binding: 0, resource: { buffer: this.uniformBuffer } },
+        { binding: 1, resource: { buffer: this.sorter.getIndicesBuffer() } }
       ]
     });
+    const dummyView = this.dummySHTexture.createView();
+    const tex = this.compressedTextures;
     this.textureBindGroup = device.createBindGroup({
       layout: this.textureBindGroupLayout,
       entries: [
-        {
-          binding: 0,
-          resource: this.compressedTextures.positionTexture.createView()
-        },
-        {
-          binding: 1,
-          resource: this.compressedTextures.scaleRotTexture1.createView()
-        },
-        {
-          binding: 2,
-          resource: this.compressedTextures.scaleRotTexture2.createView()
-        },
-        {
-          binding: 3,
-          resource: this.compressedTextures.colorTexture.createView()
-        }
+        { binding: 0, resource: tex.positionTexture.createView() },
+        { binding: 1, resource: tex.scaleRotTexture1.createView() },
+        { binding: 2, resource: tex.scaleRotTexture2.createView() },
+        { binding: 3, resource: tex.colorTexture.createView() },
+        { binding: 4, resource: tex.shBasis0Texture ? tex.shBasis0Texture.createView() : dummyView },
+        { binding: 5, resource: tex.shBasis1Texture ? tex.shBasis1Texture.createView() : dummyView },
+        { binding: 6, resource: tex.shBasis2Texture ? tex.shBasis2Texture.createView() : dummyView }
       ]
     });
   }
@@ -9519,10 +9660,11 @@ class GSSplatRendererMobile {
       208,
       new Float32Array([this.renderer.width, this.renderer.height, 0, 0])
     );
+    const shEnabled = this.compressedTextures.hasSH ? 1 : 0;
     device.queue.writeBuffer(
       this.uniformBuffer,
       224,
-      new Float32Array([this.compressedTextures.width, this.compressedTextures.height, 0, 0])
+      new Float32Array([this.compressedTextures.width, this.compressedTextures.height, shEnabled, 0])
     );
     this.sorter.setScreenSize(this.renderer.width, this.renderer.height);
     this.sorter.setCullingOptions({
@@ -9531,7 +9673,8 @@ class GSSplatRendererMobile {
       pixelThreshold: 1
     });
     const isFirstFrame = this.frameCount === 1;
-    const shouldSort = isFirstFrame || this.frameCount % this.sortEveryNFrames === 0;
+    const cameraChanged = this.hasCameraChanged();
+    const shouldSort = isFirstFrame || cameraChanged && this.frameCount % this.sortEveryNFrames === 0;
     if (shouldSort) {
       this.sorter.sort();
     }
@@ -9562,36 +9705,42 @@ class GSSplatRendererMobile {
   setSortFrequency(n) {
     this.sortEveryNFrames = Math.max(1, n);
   }
+  hasCameraChanged() {
+    const view = this.camera.viewMatrix;
+    const proj = this.camera.projectionMatrix;
+    if (!this.sortStateInitialized) {
+      this.lastSortViewMatrix.set(view);
+      this.lastSortProjMatrix.set(proj);
+      this.sortStateInitialized = true;
+      return true;
+    }
+    for (let i = 0; i < 16; i++) {
+      if (Math.abs(view[i] - this.lastSortViewMatrix[i]) > 1e-6 || Math.abs(proj[i] - this.lastSortProjMatrix[i]) > 1e-6) {
+        this.lastSortViewMatrix.set(view);
+        this.lastSortProjMatrix.set(proj);
+        return true;
+      }
+    }
+    return false;
+  }
   // ============================================
   // IGSSplatRenderer 接口实现 - SH 模式
   // ============================================
-  /**
-   * 设置 SH 模式（移动端仅支持 L0）
-   */
-  setSHMode(mode) {
+  setSHMode(_mode) {
   }
-  /**
-   * 获取当前 SH 模式
-   */
   getSHMode() {
-    return SHMode.L0;
+    var _a2;
+    return ((_a2 = this.compressedTextures) == null ? void 0 : _a2.hasSH) ? SHMode.L1 : SHMode.L0;
   }
-  /**
-   * 是否支持指定的 SH 模式
-   */
   supportsSHMode(mode) {
-    return mode === SHMode.L0;
+    return mode === SHMode.L0 || mode === SHMode.L1;
   }
-  /**
-   * 获取渲染器能力
-   */
   getCapabilities() {
     return {
-      maxSHMode: SHMode.L0,
+      maxSHMode: SHMode.L1,
       supportsRawData: false,
       isMobileOptimized: true,
       maxSplatCount: 0
-      // 无限制（受 GPU 内存限制）
     };
   }
   /**
@@ -9620,6 +9769,10 @@ class GSSplatRendererMobile {
    */
   destroy() {
     this.destroyInternal();
+    if (this.dummySHTexture) {
+      this.dummySHTexture.destroy();
+      this.dummySHTexture = null;
+    }
   }
 }
 class SceneManager {
@@ -16898,6 +17051,63 @@ class App {
   getSceneAidsRenderer() {
     return this.sceneAids;
   }
+  // ============================================
+  // 渲染性能控制
+  // ============================================
+  /**
+   * 设置渲染缩放比例（影响内部分辨率）
+   * 0.5 = 半分辨率（性能提升约 4 倍），1.0 = 正常
+   * 适用于移动端提质或桌面端降负载
+   */
+  setRenderScale(scale) {
+    this.renderer.setRenderScale(scale);
+  }
+  getRenderScale() {
+    return this.renderer.getRenderScale();
+  }
+  /**
+   * 覆盖自动 DPR，传 -1 恢复自动推荐
+   */
+  setDPR(dpr) {
+    this.renderer.setDPR(dpr);
+  }
+  getDPR() {
+    return this.renderer.getDPR();
+  }
+  /**
+   * 设置桌面端亚像素剔除阈值（默认 1.0）
+   * 值越大剔除越激进，近距离性能越好，但远处细节可能丢失
+   */
+  setPixelCullThreshold(threshold) {
+    const gsRenderer = this.getGSRenderer();
+    if (gsRenderer) {
+      gsRenderer.setPixelCullThreshold(threshold);
+    }
+  }
+  /**
+   * 设置桌面端最大可见 splat 数（0 = 不限制）
+   * 限制绘制数量是应对近距离卡顿最直接的手段
+   */
+  setMaxVisibleSplats(count) {
+    const gsRenderer = this.getGSRenderer();
+    if (gsRenderer) {
+      gsRenderer.setMaxVisibleSplats(count);
+    }
+  }
+  /**
+   * 设置排序频率（1 = 每帧，2 = 每两帧，以此类推）
+   * 降低排序频率可提升帧率，代价是移动时短暂排序瑕疵
+   */
+  setSortFrequency(frequency) {
+    const gsRenderer = this.getGSRenderer();
+    if (gsRenderer) {
+      gsRenderer.setSortFrequency(frequency);
+    }
+    const mobileRenderer = this.getGSRendererMobile();
+    if (mobileRenderer) {
+      mobileRenderer.setSortFrequency(frequency);
+    }
+  }
   /**
    * 销毁应用及所有资源
    */