@d5techs/3dgs-lib 1.4.84 → 1.4.86

package/dist/3dgs-lib.cjs

@@ -38,8 +38,7 @@ function isMobileDevice() {
   return isMobileUA || isIPadAsMac || hasTouch && isSmallScreen;
 }
 function getRecommendedDPR() {
-  const isMobile = isMobileDevice();
-  const maxDpr = isMobile ? 2 : 2;
+  const maxDpr = isMobileDevice() ? 2 : 2;
   return Math.min(window.devicePixelRatio || 1, maxDpr);
 }
 function isWebGPUSupported() {
@@ -144,6 +143,140 @@ function transformBoundingBox(bbox, modelMatrix) {
     [maxX, maxY, maxZ]
   );
 }
+class DebugOverlay {
+  constructor(maxEntries = 50) {
+    __publicField(this, "container");
+    __publicField(this, "logList");
+    __publicField(this, "maxEntries");
+    this.maxEntries = maxEntries;
+    this.container = document.createElement("div");
+    Object.assign(this.container.style, {
+      position: "fixed",
+      top: "0",
+      left: "0",
+      right: "0",
+      maxHeight: "40vh",
+      overflowY: "auto",
+      background: "rgba(0,0,0,0.85)",
+      color: "#0f0",
+      fontFamily: "monospace",
+      fontSize: "11px",
+      lineHeight: "1.4",
+      padding: "6px 8px",
+      zIndex: "99999",
+      pointerEvents: "auto",
+      whiteSpace: "pre-wrap",
+      wordBreak: "break-all"
+    });
+    const header = document.createElement("div");
+    Object.assign(header.style, {
+      display: "flex",
+      justifyContent: "space-between",
+      marginBottom: "4px",
+      borderBottom: "1px solid #333",
+      paddingBottom: "4px"
+    });
+    header.innerHTML = '<span style="color:#ff0;font-weight:bold">GPU Debug</span>';
+    const closeBtn = document.createElement("span");
+    closeBtn.textContent = "[X]";
+    closeBtn.style.color = "#f66";
+    closeBtn.style.cursor = "pointer";
+    closeBtn.onclick = () => this.hide();
+    header.appendChild(closeBtn);
+    this.logList = document.createElement("div");
+    this.container.appendChild(header);
+    this.container.appendChild(this.logList);
+    document.body.appendChild(this.container);
+  }
+  log(msg, level = "info") {
+    const colors = { info: "#0f0", warn: "#ff0", error: "#f44" };
+    const prefix = { info: "I", warn: "W", error: "E" };
+    const ts = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+    const entry = document.createElement("div");
+    entry.style.color = colors[level];
+    entry.textContent = `[${ts}][${prefix[level]}] ${msg}`;
+    this.logList.appendChild(entry);
+    while (this.logList.childElementCount > this.maxEntries) {
+      this.logList.removeChild(this.logList.firstChild);
+    }
+    this.container.scrollTop = this.container.scrollHeight;
+  }
+  info(msg) {
+    this.log(msg, "info");
+  }
+  warn(msg) {
+    this.log(msg, "warn");
+  }
+  error(msg) {
+    this.log(msg, "error");
+  }
+  hide() {
+    this.container.style.display = "none";
+  }
+  show() {
+    this.container.style.display = "block";
+  }
+  /**
+   * 绑定 WebGPU device 的全局错误捕获
+   */
+  attachDevice(device) {
+    device.onuncapturederror = (event) => {
+      this.error(`GPU Uncaptured: ${event.error.message}`);
+    };
+    this.info(
+      `Device attached. maxBuf=${(device.limits.maxBufferSize / 1048576).toFixed(0)}MB, maxStorage=${(device.limits.maxStorageBufferBindingSize / 1048576).toFixed(0)}MB`
+    );
+  }
+  /**
+   * 检查 shader 编译结果
+   */
+  async checkShader(module2, label) {
+    try {
+      const info = await module2.getCompilationInfo();
+      let hasError = false;
+      for (const msg of info.messages) {
+        const text = `Shader[${label}] ${msg.type}: L${msg.lineNum}:${msg.linePos} ${msg.message}`;
+        if (msg.type === "error") {
+          this.error(text);
+          hasError = true;
+        } else if (msg.type === "warning") {
+          this.warn(text);
+        }
+      }
+      if (!hasError) {
+        this.info(`Shader[${label}] compiled OK`);
+      }
+      return !hasError;
+    } catch (e) {
+      this.error(`Shader[${label}] getCompilationInfo failed: ${e}`);
+      return false;
+    }
+  }
+  /**
+   * 包裹一个异步操作，捕获 validation/oom 错误
+   */
+  async wrapGPU(device, label, fn) {
+    device.pushErrorScope("validation");
+    device.pushErrorScope("out-of-memory");
+    const result = fn();
+    const oomErr = await device.popErrorScope();
+    const valErr = await device.popErrorScope();
+    if (oomErr) this.error(`[${label}] OOM: ${oomErr.message}`);
+    if (valErr) this.error(`[${label}] Validation: ${valErr.message}`);
+    if (!oomErr && !valErr) this.info(`[${label}] OK`);
+    return result;
+  }
+}
+let _instance = null;
+function getDebugOverlay() {
+  return _instance;
+}
+function createDebugOverlay() {
+  if (!_instance) {
+    _instance = new DebugOverlay();
+  }
+  return _instance;
+}
 async function loadTextureFromURL(device, url) {
   try {
     const response = await fetch(url);
@@ -363,7 +496,16 @@ class Renderer {
       }
     });
     this._device.lost.then((info) => {
+      const overlay2 = getDebugOverlay();
+      overlay2 == null ? void 0 : overlay2.error(`GPU device lost: ${info.reason} - ${info.message}`);
     });
+    const overlay = getDebugOverlay();
+    if (overlay) {
+      overlay.attachDevice(this._device);
+      overlay.info(
+        `GPU: vendor=${this._gpuVendor || "unknown"}, arch=${this._gpuArchitecture || "unknown"}, apple=${this._isAppleGPU}, format=${navigator.gpu.getPreferredCanvasFormat()}`
+      );
+    }
     this._context = this.canvas.getContext("webgpu");
     if (!this._context) {
       throw new Error("无法获取 WebGPU 上下文");
@@ -651,6 +793,7 @@ const _OrbitControls = class _OrbitControls {
     // 键盘移动
     __publicField(this, "moveSpeed", 0.015);
     __publicField(this, "pressedKeys", /* @__PURE__ */ new Set());
+    __publicField(this, "_wasKeyboardMoving", false);
     // 触摸手势状态
     __publicField(this, "touchMode", "none");
     __publicField(this, "lastTouchDistance", 0);
@@ -687,6 +830,9 @@ const _OrbitControls = class _OrbitControls {
     this.setupEventListeners();
     this.applySpherical();
   }
+  get isInteracting() {
+    return this.isDragging;
+  }
   setupEventListeners() {
     this.canvas.addEventListener("mousedown", this.boundOnMouseDown);
     this.canvas.addEventListener("mousemove", this.boundOnMouseMove);
@@ -824,7 +970,14 @@ const _OrbitControls = class _OrbitControls {
     this.pressedKeys.delete(e.key.toLowerCase());
   }
   applyKeyboardMovement() {
-    if (this.pressedKeys.size === 0) return;
+    if (this.pressedKeys.size === 0) {
+      if (this._wasKeyboardMoving) {
+        this._wasKeyboardMoving = false;
+        this.recenterOrbitTarget();
+      }
+      return;
+    }
+    this._wasKeyboardMoving = true;
     const m = this.camera.viewMatrix;
     const right = [m[0], m[4], m[8]];
     const forward = [-m[2], -m[6], -m[10]];
@@ -984,9 +1137,15 @@ const _OrbitControls = class _OrbitControls {
   onTouchEnd(e) {
     if (e.touches.length === 0) {
       this.isDragging = false;
+      if (this.touchMode === "zoom-pan") {
+        this.recenterOrbitTarget();
+      }
       this.touchMode = "none";
       this.lastTouchDistance = 0;
     } else if (e.touches.length === 1) {
+      if (this.touchMode === "zoom-pan") {
+        this.recenterOrbitTarget();
+      }
       this.touchMode = "rotate";
       this.lastX = e.touches[0].clientX;
       this.lastY = e.touches[0].clientY;
@@ -1003,6 +1162,34 @@ const _OrbitControls = class _OrbitControls {
       y: (touches[0].clientY + touches[1].clientY) / 2
     };
   }
+  /**
+   * 将 orbit 目标重新锚定到屏幕中心的模型表面点，
+   * 保持相机世界坐标不变，仅重算 distance/theta/phi。
+   * 用于 WASD 移动或触摸缩放结束后修复旋转中心偏移。
+   */
+  recenterOrbitTarget() {
+    if (!this.pickWorldPosition) return;
+    const rect = this.canvas.getBoundingClientRect();
+    const hit = this.pickWorldPosition(
+      rect.left + rect.width / 2,
+      rect.top + rect.height / 2
+    );
+    if (!hit) return;
+    const dx = this.camera.position[0] - hit[0];
+    const dy = this.camera.position[1] - hit[1];
+    const dz = this.camera.position[2] - hit[2];
+    const newDist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (newDist < this.minDistance) return;
+    this.camera.target[0] = hit[0];
+    this.camera.target[1] = hit[1];
+    this.camera.target[2] = hit[2];
+    this.distance = newDist;
+    this.theta = Math.atan2(dx, dz);
+    this.phi = Math.acos(Math.min(1, Math.max(-1, dy / newDist)));
+    this.deltaPanX = 0;
+    this.deltaPanY = 0;
+    this.deltaPanZ = 0;
+  }
   /**
    * 将球坐标写入相机位置（内部方法，不处理阻尼）
    */
@@ -5231,9 +5418,10 @@ function compactDataToGPUBuffer(data, includeFullSH = false) {
     }
     return buffer;
   } else {
-    const buffer = new Float32Array(count * 64);
+    const COMPACT_FLOATS = 16;
+    const buffer = new Float32Array(count * COMPACT_FLOATS);
     for (let i = 0; i < count; i++) {
-      const offset = i * 64;
+      const offset = i * COMPACT_FLOATS;
       buffer[offset + 0] = data.positions[i * 3 + 0];
       buffer[offset + 1] = data.positions[i * 3 + 1];
       buffer[offset + 2] = data.positions[i * 3 + 2];
@@ -5254,9 +5442,56 @@ function compactDataToGPUBuffer(data, includeFullSH = false) {
     return buffer;
   }
 }
+const _f16Scratch = new Float32Array(1);
+const _f16ScratchU32 = new Uint32Array(_f16Scratch.buffer);
+function f32ToF16Bits(val) {
+  _f16Scratch[0] = val;
+  const bits2 = _f16ScratchU32[0];
+  const sign = bits2 >>> 31 & 1;
+  let exp = bits2 >>> 23 & 255;
+  let frac = bits2 & 8388607;
+  if (exp === 255) {
+    return sign << 15 | 31744 | (frac ? 512 : 0);
+  }
+  exp = exp - 127 + 15;
+  if (exp >= 31) {
+    return sign << 15 | 31744;
+  }
+  if (exp <= 0) {
+    if (exp < -10) return sign << 15;
+    frac = (frac | 8388608) >> 1 - exp;
+    return sign << 15 | frac >> 13;
+  }
+  return sign << 15 | exp << 10 | frac >> 13;
+}
+function compactDataToGPUBufferHalf(data) {
+  const count = data.count;
+  const U32_PER_SPLAT = 8;
+  const buffer = new Uint32Array(count * U32_PER_SPLAT);
+  const pos = data.positions;
+  const scl = data.scales;
+  const rot = data.rotations;
+  const col = data.colors;
+  const opa = data.opacities;
+  for (let i = 0; i < count; i++) {
+    const o = i * U32_PER_SPLAT;
+    const i3 = i * 3;
+    const i4 = i * 4;
+    buffer[o] = f32ToF16Bits(pos[i3 + 1]) << 16 | f32ToF16Bits(pos[i3]);
+    buffer[o + 1] = f32ToF16Bits(pos[i3 + 2]);
+    buffer[o + 2] = f32ToF16Bits(scl[i3 + 1]) << 16 | f32ToF16Bits(scl[i3]);
+    buffer[o + 3] = f32ToF16Bits(opa[i]) << 16 | f32ToF16Bits(scl[i3 + 2]);
+    buffer[o + 4] = f32ToF16Bits(rot[i4 + 1]) << 16 | f32ToF16Bits(rot[i4]);
+    buffer[o + 5] = f32ToF16Bits(rot[i4 + 3]) << 16 | f32ToF16Bits(rot[i4 + 2]);
+    buffer[o + 6] = f32ToF16Bits(col[i3 + 1]) << 16 | f32ToF16Bits(col[i3]);
+    buffer[o + 7] = f32ToF16Bits(col[i3 + 2]);
+  }
+  return buffer;
+}
 const PLYLoaderMobile = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   compactDataToGPUBuffer,
+  compactDataToGPUBufferHalf,
   loadPLYMobile,
   parsePLYBuffer,
   transformSHCoeffsYZSwap
@@ -7316,16 +7551,38 @@ const RADIX_BITS = 8;
 const RADIX_SIZE = 256;
 const ELEMENTS_PER_THREAD = 4;
 const BLOCK_SIZE = WORKGROUP_SIZE$1 * ELEMENTS_PER_THREAD;
-function generateCullingShaderCode$1() {
-  return (
-    /* wgsl */
-    `
-/**
- * Project & Cull Shader
- * 基于 rfs-gsplat-render 实现
- */
-
-struct Splat {
+function generateCullingShaderCode$1(compact = false, half = false, sortBits = 32) {
+  let splatBinding;
+  let splatAccessCode;
+  if (half) {
+    splatBinding = `@group(0) @binding(0) var<storage, read> splatDataU32: array<u32>;`;
+    splatAccessCode = `
+const HALF_U32S: u32 = 8u;
+fn getSplatMean(idx: u32) -> vec3<f32> {
+  let b = idx * HALF_U32S;
+  let xy = unpack2x16float(splatDataU32[b]);
+  let zp = unpack2x16float(splatDataU32[b + 1u]);
+  return vec3<f32>(xy.x, xy.y, zp.x);
+}
+fn getSplatScale(idx: u32) -> vec3<f32> {
+  let b = idx * HALF_U32S;
+  let xy = unpack2x16float(splatDataU32[b + 2u]);
+  return vec3<f32>(xy.x, xy.y, unpack2x16float(splatDataU32[b + 3u]).x);
+}
+fn getSplatOpacity(idx: u32) -> f32 {
+  let b = idx * HALF_U32S;
+  return unpack2x16float(splatDataU32[b + 3u]).y;
+}`;
+  } else {
+    const splatStruct = compact ? `struct Splat {
+  mean:     vec3<f32>,
+  _pad0:    f32,
+  scale:    vec3<f32>,
+  _pad1:    f32,
+  rotation: vec4<f32>,
+  colorDC:  vec3<f32>,
+  opacity:  f32,
+}` : `struct Splat {
   mean:     vec3<f32>,
   _pad0:    f32,
   scale:    vec3<f32>,
@@ -7337,7 +7594,24 @@ struct Splat {
   sh2:      array<f32, 15>,
   sh3:      array<f32, 21>,
   _pad2:    array<f32, 3>,
-}
+}`;
+    splatBinding = `${splatStruct}
+@group(0) @binding(0) var<storage, read> splats: array<Splat>;`;
+    splatAccessCode = `
+fn getSplatMean(idx: u32) -> vec3<f32> { return splats[idx].mean; }
+fn getSplatScale(idx: u32) -> vec3<f32> { return splats[idx].scale; }
+fn getSplatOpacity(idx: u32) -> f32 { return splats[idx].opacity; }`;
+  }
+  return (
+    /* wgsl */
+    `
+/**
+ * Project & Cull Shader
+ * 基于 rfs-gsplat-render 实现
+ */
+
+${splatBinding}
+${splatAccessCode}
 
 struct CameraUniforms {
   view: mat4x4<f32>,
@@ -7357,10 +7631,9 @@ struct CullingParams {
   pixelThreshold: f32,
   maxVisibleCount: u32,
   depthRangeLimit: f32,
-  _pad_cull: f32,
+  lodSkipRate: f32,
 }
 
-@group(0) @binding(0) var<storage, read> splats: array<Splat>;
 @group(0) @binding(1) var<uniform> camera: CameraUniforms;
 @group(0) @binding(2) var<uniform> params: CullingParams;
 @group(0) @binding(3) var<storage, read_write> depthKeys: array<u32>;
@@ -7378,16 +7651,12 @@ fn getModelMaxScale(model: mat4x4<f32>) -> f32 {
   return max(max(sx, sy), sz);
 }
 
-// IEEE 754 位操作编码浮点数为可排序的 u32
-// 参考 rfs-gsplat-render 的 encode_min_max_fp32 实现
 fn encodeDepthKey(val: f32) -> u32 {
   var bits = bitcast<u32>(val);
   bits ^= bitcast<u32>(bitcast<i32>(bits) >> 31) | 0x80000000u;
-  return bits;
+  return bits >> ${sortBits === 16 ? "16u" : "0u"};
 }
 
-// 视锥剔除检查
-// 基于 rfs-gsplat-render 的 is_in_frustum 实现
 fn isInFrustum(clipPos: vec4<f32>, frustumDilation: f32) -> bool {
   let clip = (1.0 + frustumDilation) * clipPos.w;
   
@@ -7406,43 +7675,47 @@ fn isInFrustum(clipPos: vec4<f32>, frustumDilation: f32) -> bool {
 fn projectAndCull(@builtin(global_invocation_id) gid: vec3<u32>) {
   let i = gid.x;
   if i >= params.splatCount { return; }
+
+  // LOD 抽稀放最前面：跳过的 splat 不做任何数据加载和矩阵运算
+  // 哈希仅依赖 splat index → 被跳过的集合永远不变 → 零闪烁
+  if params.lodSkipRate > 0.0 {
+    let hash = ((i * 2654435761u) >> 16u) & 0xFFFFu;
+    if f32(hash) < params.lodSkipRate * 65535.0 {
+      return;
+    }
+  }
   
-  let splat = splats[i];
+  let splatMean = getSplatMean(i);
+  let splatScale = getSplatScale(i);
+  let splatOpacity = getSplatOpacity(i);
   
-  // 透明度剔除
-  if splat.opacity < 0.004 { return; }
+  if splatOpacity < 0.004 { return; }
   
-  // 变换: Local -> World -> View -> Clip
-  let worldPos = camera.model * vec4<f32>(splat.mean, 1.0);
+  let worldPos = camera.model * vec4<f32>(splatMean, 1.0);
   let viewPos = camera.view * worldPos;
   let clipPos = camera.proj * viewPos;
   
-  // 视锥剔除
   if !isInFrustum(clipPos, params.frustumDilation) { return; }
   
-  // 亚像素剔除：Gaussian 可见范围小于阈值的 splat 跳过渲染和排序
-  // scale 是 σ（标准差），Gaussian 可见范围约 3σ（覆盖 99.7%）
-  if params.pixelThreshold > 0.0 {
-    let splatSigma = maxScale(splat.scale) * getModelMaxScale(camera.model);
-    let focalY = abs(camera.proj[1][1]) * params.screenHeight * 0.5;
-    let projectedExtent = splatSigma * 3.0 * focalY / max(abs(viewPos.z), 0.001);
-    if projectedExtent < params.pixelThreshold { return; }
-  }
+  let splatSigma = maxScale(splatScale) * getModelMaxScale(camera.model);
+  let focalY = abs(camera.proj[1][1]) * params.screenHeight * 0.5;
+  let projectedExtent = splatSigma * 3.0 * focalY / max(abs(viewPos.z), 0.001);
+
+  // 剔除投影尺寸过大的 splat（远离模型时去除周围遮挡物）
+  if projectedExtent > params.screenHeight * 0.5 { return; }
+
+  // 剔除投影尺寸过小的 splat
+  if params.pixelThreshold > 0.0 && projectedExtent < params.pixelThreshold { return; }
   
-  // 深度范围限制：只渲染距相机一定深度范围内的 splat
   if params.depthRangeLimit > 0.0 {
     if abs(viewPos.z) > params.depthRangeLimit { return; }
   }
 
-  // 深度编码 (viewPos.z 是负数)
   let depth = viewPos.z;
   let sortableDepth = encodeDepthKey(depth);
   
-  // 原子增加可见计数并获取索引
-  // indirectBuffer[1] 是 instance_count
   let visibleIdx = atomicAdd(&indirectBuffer[1], 1u);
   
-  // 写入可见点列表
   depthKeys[visibleIdx] = sortableDepth;
   visibleIndices[visibleIdx] = i;
 }
@@ -7757,7 +8030,7 @@ fn downsweep(
   );
 }
 class GSSplatSorter {
-  constructor(device, splatCount, splatBuffer, cameraBuffer, _options = {}) {
+  constructor(device, splatCount, splatBuffer, cameraBuffer, _options = {}, compact = false, half = false, sortBits = 32) {
     __publicField(this, "device");
     __publicField(this, "splatCount");
     // Culling Buffers
@@ -7787,11 +8060,12 @@ class GSSplatSorter {
     __publicField(this, "upsweepBindGroupLayout");
     __publicField(this, "spineBindGroupLayout");
     __publicField(this, "downsweepBindGroupLayout");
-    // Bind groups for each pass (4 passes)
+    // Bind groups for each pass
     __publicField(this, "upsweepBindGroups", []);
     __publicField(this, "spineBindGroups", []);
     __publicField(this, "downsweepBindGroups", []);
     __publicField(this, "numPartitions");
+    __publicField(this, "numSortPasses");
     // 屏幕信息和剔除选项
     __publicField(this, "screenWidth", 1920);
     __publicField(this, "screenHeight", 1080);
@@ -7804,14 +8078,19 @@ class GSSplatSorter {
     this.device = device;
     this.splatCount = splatCount;
     this.numPartitions = Math.ceil(splatCount / BLOCK_SIZE);
+    this.numSortPasses = sortBits / RADIX_BITS;
+    const dbg = getDebugOverlay();
+    dbg == null ? void 0 : dbg.info(`Sorter init: ${splatCount} splats, compact=${compact}, half=${half}, sortBits=${sortBits}`);
     const cullingModule = device.createShaderModule({
-      code: generateCullingShaderCode$1(),
+      code: generateCullingShaderCode$1(compact, half, sortBits),
       label: "culling-shader"
     });
+    dbg == null ? void 0 : dbg.checkShader(cullingModule, "culling");
     const radixSortModule = device.createShaderModule({
       code: generateRadixSortShaderCode(),
       label: "radix-sort-shader"
     });
+    dbg == null ? void 0 : dbg.checkShader(radixSortModule, "radix-sort");
     this.cullingParamsBuffer = device.createBuffer({
       size: 48,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
@@ -7829,12 +8108,11 @@ class GSSplatSorter {
     });
     this.indirectBuffer = device.createBuffer({
       size: 16,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
       label: "indirect-buffer"
     });
     this.globalHistogramBuffer = device.createBuffer({
-      size: RADIX_SIZE * 4 * 4,
-      // 4 passes * 256 bins * 4 bytes
+      size: RADIX_SIZE * this.numSortPasses * 4,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
       label: "global-histogram"
     });
@@ -7853,7 +8131,7 @@ class GSSplatSorter {
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
       label: "values-temp"
     });
-    for (let i = 0; i < 4; i++) {
+    for (let i = 0; i < this.numSortPasses; i++) {
       const paramsBuffer = device.createBuffer({
         size: 16,
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
@@ -7965,16 +8243,12 @@ class GSSplatSorter {
   }
   /**
    * 创建 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
    */
   createRadixSortBindGroups() {
-    for (let passIdx = 0; passIdx < 4; passIdx++) {
+    const lastPassIdx = this.numSortPasses - 1;
+    for (let passIdx = 0; passIdx < this.numSortPasses; passIdx++) {
       const isEvenPass = passIdx % 2 === 0;
       const keysIn = isEvenPass ? this.depthKeysBuffer : this.keysTempBuffer;
       const valuesIn = isEvenPass ? this.visibleIndicesBuffer : this.valuesTempBuffer;
@@ -7982,10 +8256,10 @@ class GSSplatSorter {
       let valuesOut;
       if (isEvenPass) {
         keysOut = this.keysTempBuffer;
-        valuesOut = this.valuesTempBuffer;
+        valuesOut = passIdx === lastPassIdx ? this.sortedIndicesBuffer : this.valuesTempBuffer;
       } else {
         keysOut = this.depthKeysBuffer;
-        valuesOut = passIdx === 3 ? this.sortedIndicesBuffer : this.visibleIndicesBuffer;
+        valuesOut = passIdx === lastPassIdx ? this.sortedIndicesBuffer : this.visibleIndicesBuffer;
       }
       this.upsweepBindGroups[passIdx] = this.device.createBindGroup({
         layout: this.upsweepBindGroupLayout,
@@ -8053,16 +8327,15 @@ class GSSplatSorter {
     view.setFloat32(24, this.cullingOptions.pixelThreshold, true);
     view.setUint32(28, this.cullingOptions.maxVisibleCount ?? 0, true);
     view.setFloat32(32, this.cullingOptions.depthRangeLimit ?? 0, true);
+    view.setFloat32(36, this.cullingOptions.lodSkipRate ?? 0, true);
     this.device.queue.writeBuffer(this.cullingParamsBuffer, 0, cullingParamsData);
+    this.device.queue.writeBuffer(
+      this.indirectBuffer,
+      0,
+      new Uint32Array([4, 0, 0, 0])
+    );
     const encoder = this.device.createCommandEncoder({ label: "splat-sort-encoder" });
     encoder.clearBuffer(this.globalHistogramBuffer);
-    {
-      const pass = encoder.beginComputePass({ label: "init-indirect" });
-      pass.setPipeline(this.initIndirectPipeline);
-      pass.setBindGroup(0, this.cullingBindGroup);
-      pass.dispatchWorkgroups(1);
-      pass.end();
-    }
     {
       const pass = encoder.beginComputePass({ label: "project-cull" });
       pass.setPipeline(this.projectCullPipeline);
@@ -8070,7 +8343,7 @@ class GSSplatSorter {
       pass.dispatchWorkgroups(Math.ceil(this.splatCount / WORKGROUP_SIZE$1));
       pass.end();
     }
-    for (let passIdx = 0; passIdx < 4; passIdx++) {
+    for (let passIdx = 0; passIdx < this.numSortPasses; passIdx++) {
       {
         const pass = encoder.beginComputePass({ label: `upsweep-p${passIdx}` });
         pass.setPipeline(this.upsweepPipeline);
@@ -8114,6 +8387,24 @@ class GSSplatSorter {
   getDrawIndirectBuffer() {
     return this.indirectBuffer;
   }
+  /**
+   * 异步读回 drawIndirect buffer 内容（调试用）
+   * 返回 [vertexCount, instanceCount, firstVertex, firstInstance]
+   */
+  async readbackIndirect() {
+    const staging = this.device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+    });
+    const encoder = this.device.createCommandEncoder();
+    encoder.copyBufferToBuffer(this.indirectBuffer, 0, staging, 0, 16);
+    this.device.queue.submit([encoder.finish()]);
+    await staging.mapAsync(GPUMapMode.READ);
+    const result = new Uint32Array(staging.getMappedRange().slice(0));
+    staging.unmap();
+    staging.destroy();
+    return result;
+  }
   /**
    * 获取 splat 总数量
    */
@@ -8361,10 +8652,6 @@ fn computeExtentBasisAA(cov2dIn: vec3<f32>, opacity: f32, viewportSize: vec2<f32
   // 使用基于视口的最大限制 (匹配 PlayCanvas)
   let vmin = min(1024.0, min(viewportSize.x, viewportSize.y));
   
-  // 计算轴长度: l = 2 * sqrt(2 * lambda) ≈ 2.83 * sqrt(lambda)
-  // 这与 GAUSSIAN_K=4 配套使用：
-  // 在 UV=1 边界，对应 2*sqrt(2) 个标准差的位置
-  // exp(-4 * 1) = exp(-4) ≈ 0.018，Normalized 后精确为 0
   let l1 = min(2.0 * sqrt(2.0 * lambda1), vmin);
   let l2 = min(2.0 * sqrt(2.0 * lambda2), vmin);
   
@@ -8381,7 +8668,6 @@ fn computeExtentBasisAA(cov2dIn: vec3<f32>, opacity: f32, viewportSize: vec2<f32
   let eigenvector1 = diagVec;
   let eigenvector2 = vec2<f32>(diagVec.y, -diagVec.x);
   
-  // 计算基向量 (不应用额外的 splat_scale，因为我们使用默认值 1.0)
   result.basis = vec4<f32>(eigenvector1 * l1, eigenvector2 * l2);
   result.adjustedOpacity = alpha;
   return result;
@@ -8775,7 +9061,79 @@ fn fs_depth_normal(input: VertexOutput) -> FragOutput {
 }
 `
 );
+const SPLAT_BYTE_SIZE = 256;
 const SPLAT_FLOAT_COUNT = 64;
+const COMPACT_SPLAT_BYTE_SIZE = 64;
+const COMPACT_SPLAT_FLOAT_COUNT = 16;
+const HALF_SPLAT_BYTE_SIZE = 32;
+const HALF_SPLAT_U32_COUNT = 8;
+function transformShaderForCompact(code) {
+  code = code.replace(
+    /struct Splat \{[\s\S]*?\n\}/,
+    `struct Splat {
+  mean: vec3<f32>, _pad0: f32,
+  scale: vec3<f32>, _pad1: f32,
+  rotation: vec4<f32>,
+  colorDC: vec3<f32>,
+  opacity: f32,
+}`
+  );
+  code = code.replace(
+    /fn evalSH\(splat: Splat, dir: vec3<f32>\) -> vec3<f32> \{[\s\S]*?\n\}/,
+    `fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(0.0);
+}`
+  );
+  return code;
+}
+function transformShaderForHalf(code) {
+  code = code.replace(
+    /struct Splat \{[\s\S]*?\n\}/,
+    `struct Splat {
+  mean: vec3<f32>, _pad0: f32,
+  scale: vec3<f32>, _pad1: f32,
+  rotation: vec4<f32>,
+  colorDC: vec3<f32>,
+  opacity: f32,
+}`
+  );
+  code = code.replace(
+    /@group\(0\)\s*@binding\((\d+)\)\s*var<storage,\s*read>\s*splats\s*:\s*array<Splat>/,
+    `@group(0) @binding($1) var<storage, read> splatDataU32: array<u32>`
+  );
+  const unpackFunctions = `
+const HALF_U32S: u32 = 8u;
+fn unpackSplatFromHalf(idx: u32) -> Splat {
+  let b = idx * HALF_U32S;
+  let mean_xy = unpack2x16float(splatDataU32[b]);
+  let mean_zp = unpack2x16float(splatDataU32[b + 1u]);
+  let sc_xy = unpack2x16float(splatDataU32[b + 2u]);
+  let sc_z_op = unpack2x16float(splatDataU32[b + 3u]);
+  let r_xy = unpack2x16float(splatDataU32[b + 4u]);
+  let r_zw = unpack2x16float(splatDataU32[b + 5u]);
+  let c_rg = unpack2x16float(splatDataU32[b + 6u]);
+  let c_bp = unpack2x16float(splatDataU32[b + 7u]);
+  var s: Splat;
+  s.mean = vec3<f32>(mean_xy.x, mean_xy.y, mean_zp.x);
+  s._pad0 = 0.0;
+  s.scale = vec3<f32>(sc_xy.x, sc_xy.y, sc_z_op.x);
+  s._pad1 = 0.0;
+  s.rotation = vec4<f32>(r_xy.x, r_xy.y, r_zw.x, r_zw.y);
+  s.colorDC = vec3<f32>(c_rg.x, c_rg.y, c_bp.x);
+  s.opacity = sc_z_op.y;
+  return s;
+}
+`;
+  code = code.replace(/(@vertex|@compute)/, unpackFunctions + "$1");
+  code = code.replace(/splats\[([^\]]+)\]/g, "unpackSplatFromHalf($1)");
+  code = code.replace(
+    /fn evalSH\(splat: Splat, dir: vec3<f32>\) -> vec3<f32> \{[\s\S]*?\n\}/,
+    `fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(0.0);
+}`
+  );
+  return code;
+}
 const _GSSplatRenderer = class _GSSplatRenderer {
   constructor(renderer, camera) {
     __publicField(this, "renderer");
@@ -8789,6 +9147,12 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     __publicField(this, "sorter", null);
     __publicField(this, "shMode", SHMode.L3);
     __publicField(this, "boundingBox", null);
+    /** 紧凑布局模式：64B/splat，无 SH，适合移动端 */
+    __publicField(this, "compactLayout", false);
+    /** 半精度模式：32B/splat，所有数据用 f16 打包 */
+    __publicField(this, "halfPrecision", false);
+    /** 排序位宽：16-bit 排序减少一半 radix sort pass */
+    __publicField(this, "sortBits", 32);
     // 预分配 uniform 上传缓冲区，避免每帧 GC（56 floats = 224 bytes）
     __publicField(this, "uniformData", new Float32Array(56));
     __publicField(this, "cpuPositions", null);
@@ -8802,6 +9166,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     __publicField(this, "pixelCullThreshold", 1);
     __publicField(this, "maxVisibleSplats", 0);
     __publicField(this, "depthRangeLimit", 0);
+    __publicField(this, "lodSkipRate", 0);
     // 排序优化：相机变化检测 + 频率控制
     __publicField(this, "lastSortViewMatrix", new Float32Array(16));
     __publicField(this, "lastSortProjMatrix", new Float32Array(16));
@@ -8814,6 +9179,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     __publicField(this, "sortStateInitialized", false);
     __publicField(this, "sortFrequency", 1);
     __publicField(this, "frameCounter", 0);
+    __publicField(this, "debugFrameLogged", false);
     // 编辑器状态
     __publicField(this, "editorStateBuffer", null);
     __publicField(this, "editorPipeline", null);
@@ -8838,15 +9204,56 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     this.createUniformBuffer();
     this.updateModelMatrix();
   }
+  /**
+   * 启用/禁用紧凑布局模式（64B/splat，无 SH）。
+   * 必须在 setCompactData / setData 之前调用。
+   */
+  setCompactLayout(compact) {
+    if (this.compactLayout === compact) return;
+    this.compactLayout = compact;
+    if (compact) {
+      this.shMode = SHMode.L0;
+    }
+    this.createPipeline();
+  }
+  /**
+   * 设置排序位宽。16-bit 模式排序 pass 从 4 降到 2，排序速度翻倍。
+   * 必须在 setData / setCompactData 之前调用。
+   */
+  setSortBits(bits2) {
+    this.sortBits = bits2;
+  }
+  /**
+   * 启用/禁用半精度模式（32B/splat，所有数据 f16 打包）。
+   * 自动启用 compactLayout。必须在 setCompactData 之前调用。
+   */
+  setHalfPrecision(half) {
+    if (this.halfPrecision === half) return;
+    this.halfPrecision = half;
+    if (half) {
+      this.compactLayout = true;
+      this.shMode = SHMode.L0;
+    }
+    this.createPipeline();
+  }
   createPipeline() {
     const device = this.renderer.device;
-    const shaderCode = gsOptimizedShader.replace(
+    const dbg = getDebugOverlay();
+    let shaderCode = gsOptimizedShader.replace(
       "const SH_LEVEL: u32 = 3u; // @SH_LEVEL_INJECT@",
       `const SH_LEVEL: u32 = ${this.shMode}u;`
     );
+    if (this.halfPrecision) {
+      shaderCode = transformShaderForHalf(shaderCode);
+    } else if (this.compactLayout) {
+      shaderCode = transformShaderForCompact(shaderCode);
+    }
+    dbg == null ? void 0 : dbg.info(`createPipeline: SH=${this.shMode}, compact=${this.compactLayout}, half=${this.halfPrecision}`);
     const shaderModule = device.createShaderModule({
-      code: shaderCode
+      code: shaderCode,
+      label: "gs-main-shader"
     });
+    dbg == null ? void 0 : dbg.checkShader(shaderModule, "gs-main");
     this.bindGroupLayout = device.createBindGroupLayout({
       entries: [
         {
@@ -8923,8 +9330,12 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   // A采用"zero add one-minus-src-alpha"的混合模式计算Transmittance
   createDepthNormalPipeline() {
     const device = this.renderer.device;
+    let dnShader = gsDepthNormalShader;
+    if (this.compactLayout) {
+      dnShader = transformShaderForCompact(dnShader);
+    }
     const shaderModule = device.createShaderModule({
-      code: gsDepthNormalShader
+      code: dnShader
     });
     const pipelineLayout = device.createPipelineLayout({
       bindGroupLayouts: [this.bindGroupLayout]
@@ -9103,6 +9514,17 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   getDepthRangeLimit() {
     return this.depthRangeLimit;
   }
+  /**
+   * 设置 LOD 抽稀率（0~1）
+   * 远处 splat 按此比例随机跳过（确定性哈希，无闪烁）
+   * 0 = 不抽稀
+   */
+  setLodSkipRate(rate) {
+    this.lodSkipRate = Math.max(0, Math.min(1, rate));
+  }
+  getLodSkipRate() {
+    return this.lodSkipRate;
+  }
   /**
    * 设置排序频率
    * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推
@@ -9145,6 +9567,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   }
   setData(splats) {
     const device = this.renderer.device;
+    const dbg = getDebugOverlay();
     if (this.splatBuffer) {
       this.splatBuffer.destroy();
     }
@@ -9159,12 +9582,24 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       this.boundingBox = null;
       return;
     }
+    const floatsPerSplat = this.compactLayout ? COMPACT_SPLAT_FLOAT_COUNT : SPLAT_FLOAT_COUNT;
+    const bytesPerSplat = floatsPerSplat * 4;
+    const maxStorageSize = device.limits.maxStorageBufferBindingSize;
+    const maxSplatsForGPU = Math.floor(maxStorageSize / bytesPerSplat);
+    if (this.splatCount > maxSplatsForGPU) {
+      dbg == null ? void 0 : dbg.warn(
+        `setData: truncating ${this.splatCount} -> ${maxSplatsForGPU} splats (maxStorageBufferBindingSize=${(maxStorageSize / 1048576).toFixed(0)}MB)`
+      );
+      this.splatCount = maxSplatsForGPU;
+      splats = splats.slice(0, this.splatCount);
+    }
+    dbg == null ? void 0 : dbg.info(`setData: ${this.splatCount} splats, compact=${this.compactLayout}`);
     this.boundingBox = this.computeBoundingBox(splats);
     const positions = new Float32Array(this.splatCount * 3);
-    const data = new Float32Array(this.splatCount * SPLAT_FLOAT_COUNT);
+    const data = new Float32Array(this.splatCount * floatsPerSplat);
     for (let i = 0; i < this.splatCount; i++) {
       const splat = splats[i];
-      const offset = i * SPLAT_FLOAT_COUNT;
+      const offset = i * floatsPerSplat;
       positions[i * 3 + 0] = splat.mean[0];
       positions[i * 3 + 1] = splat.mean[1];
       positions[i * 3 + 2] = splat.mean[2];
@@ -9184,31 +9619,39 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       data[offset + 13] = splat.colorDC[1];
       data[offset + 14] = splat.colorDC[2];
       data[offset + 15] = splat.opacity;
-      const shRest = splat.shRest;
-      for (let j = 0; j < 9; j++) {
-        data[offset + 16 + j] = shRest ? shRest[j] : 0;
-      }
-      for (let j = 0; j < 15; j++) {
-        data[offset + 25 + j] = shRest ? shRest[9 + j] : 0;
-      }
-      for (let j = 0; j < 21; j++) {
-        data[offset + 40 + j] = shRest ? shRest[24 + j] : 0;
+      if (!this.compactLayout) {
+        const shRest = splat.shRest;
+        for (let j = 0; j < 9; j++) {
+          data[offset + 16 + j] = shRest ? shRest[j] : 0;
+        }
+        for (let j = 0; j < 15; j++) {
+          data[offset + 25 + j] = shRest ? shRest[9 + j] : 0;
+        }
+        for (let j = 0; j < 21; j++) {
+          data[offset + 40 + j] = shRest ? shRest[24 + j] : 0;
+        }
+        data[offset + 61] = 0;
+        data[offset + 62] = 0;
+        data[offset + 63] = 0;
       }
-      data[offset + 61] = 0;
-      data[offset + 62] = 0;
-      data[offset + 63] = 0;
     }
+    dbg == null ? void 0 : dbg.info(`splatBuffer: ${(data.byteLength / 1048576).toFixed(1)}MB (${floatsPerSplat} floats/splat)`);
     this.splatBuffer = device.createBuffer({
       size: data.byteLength,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
     });
     device.queue.writeBuffer(this.splatBuffer, 0, data);
     this.cpuPositions = positions;
+    dbg == null ? void 0 : dbg.info(`Creating sorter: compact=${this.compactLayout}, sortBits=${this.sortBits}`);
     this.sorter = new GSSplatSorter(
       device,
       this.splatCount,
       this.splatBuffer,
-      this.uniformBuffer
+      this.uniformBuffer,
+      {},
+      this.compactLayout,
+      false,
+      this.sortBits
     );
     this.sorter.setScreenSize(this.renderer.width, this.renderer.height);
     this.sorter.setCullingOptions({
@@ -9224,10 +9667,12 @@ const _GSSplatRenderer = class _GSSplatRenderer {
         { binding: 2, resource: { buffer: this.sorter.getIndicesBuffer() } }
       ]
     });
+    dbg == null ? void 0 : dbg.info(`setData complete, bindGroup created`);
     if (this.editorEnabled) this.rebuildEditorBindGroup();
   }
   setCompactData(compactData) {
     const device = this.renderer.device;
+    const dbg = getDebugOverlay();
     if (this.splatBuffer) {
       this.splatBuffer.destroy();
     }
@@ -9242,20 +9687,98 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       this.boundingBox = null;
       return;
     }
+    const bytesPerSplat = this.halfPrecision ? HALF_SPLAT_BYTE_SIZE : this.compactLayout ? COMPACT_SPLAT_BYTE_SIZE : SPLAT_BYTE_SIZE;
+    const maxStorageSize = device.limits.maxStorageBufferBindingSize;
+    const maxSplatsForGPU = Math.floor(maxStorageSize / bytesPerSplat);
+    dbg == null ? void 0 : dbg.info(
+      `GPU limits: maxStorageBinding=${(maxStorageSize / 1048576).toFixed(0)}MB, maxBuf=${(device.limits.maxBufferSize / 1048576).toFixed(0)}MB, maxSplats=${maxSplatsForGPU} (at ${bytesPerSplat}B/splat), half=${this.halfPrecision}`
+    );
+    if (this.splatCount > maxSplatsForGPU) {
+      dbg == null ? void 0 : dbg.warn(
+        `Splat count ${this.splatCount} exceeds GPU maxStorageBufferBindingSize (${(maxStorageSize / 1048576).toFixed(0)}MB = ${maxSplatsForGPU} splats). Truncating to ${maxSplatsForGPU}.`
+      );
+      this.splatCount = maxSplatsForGPU;
+    }
     this.boundingBox = this.computeBoundingBoxFromCompact(compactData);
-    this.cpuPositions = new Float32Array(compactData.positions);
-    const includeSH = compactData.shCoeffs !== void 0;
-    const gpuData = compactDataToGPUBuffer(compactData, includeSH);
+    let trimmedData;
+    if (this.halfPrecision && this.lodSkipRate > 0) {
+      const skipRate = this.lodSkipRate;
+      const threshold = skipRate * 65535;
+      const kept = [];
+      for (let i = 0; i < this.splatCount; i++) {
+        const hash = (i * 2654435761 | 0) >>> 16 & 65535;
+        if (hash >= threshold) kept.push(i);
+      }
+      const n = kept.length;
+      const pos = new Float32Array(n * 3);
+      const scl = new Float32Array(n * 3);
+      const rot = new Float32Array(n * 4);
+      const col = new Float32Array(n * 3);
+      const opa = new Float32Array(n);
+      for (let k = 0; k < n; k++) {
+        const i = kept[k];
+        pos[k * 3] = compactData.positions[i * 3];
+        pos[k * 3 + 1] = compactData.positions[i * 3 + 1];
+        pos[k * 3 + 2] = compactData.positions[i * 3 + 2];
+        scl[k * 3] = compactData.scales[i * 3];
+        scl[k * 3 + 1] = compactData.scales[i * 3 + 1];
+        scl[k * 3 + 2] = compactData.scales[i * 3 + 2];
+        rot[k * 4] = compactData.rotations[i * 4];
+        rot[k * 4 + 1] = compactData.rotations[i * 4 + 1];
+        rot[k * 4 + 2] = compactData.rotations[i * 4 + 2];
+        rot[k * 4 + 3] = compactData.rotations[i * 4 + 3];
+        col[k * 3] = compactData.colors[i * 3];
+        col[k * 3 + 1] = compactData.colors[i * 3 + 1];
+        col[k * 3 + 2] = compactData.colors[i * 3 + 2];
+        opa[k] = compactData.opacities[i];
+      }
+      trimmedData = { count: n, positions: pos, scales: scl, rotations: rot, colors: col, opacities: opa };
+      this.splatCount = n;
+      dbg == null ? void 0 : dbg.info(`CPU LOD filter: ${compactData.count} → ${n} splats (skip ${(skipRate * 100).toFixed(0)}%)`);
+    } else {
+      const includeSH = !this.compactLayout && compactData.shCoeffs !== void 0;
+      trimmedData = this.splatCount < compactData.count ? {
+        count: this.splatCount,
+        positions: compactData.positions.slice(0, this.splatCount * 3),
+        scales: compactData.scales.slice(0, this.splatCount * 3),
+        rotations: compactData.rotations.slice(0, this.splatCount * 4),
+        colors: compactData.colors.slice(0, this.splatCount * 3),
+        opacities: compactData.opacities.slice(0, this.splatCount),
+        shCoeffs: includeSH && compactData.shCoeffs ? compactData.shCoeffs.slice(0, this.splatCount * compactData.shCoeffs.length / compactData.count) : void 0
+      } : compactData;
+    }
+    dbg == null ? void 0 : dbg.info(`setCompactData: ${this.splatCount} splats, compact=${this.compactLayout}, half=${this.halfPrecision}`);
+    this.cpuPositions = new Float32Array(trimmedData.positions);
+    let gpuBuf;
+    if (this.halfPrecision) {
+      const halfData = compactDataToGPUBufferHalf(trimmedData);
+      gpuBuf = halfData.buffer;
+      dbg == null ? void 0 : dbg.info(
+        `gpuData(half): ${(halfData.byteLength / 1048576).toFixed(1)}MB, u32s=${halfData.length}, u32/splat=${HALF_SPLAT_U32_COUNT}`
+      );
+    } else {
+      const includeSH = !this.compactLayout && compactData.shCoeffs !== void 0;
+      const f32Data = compactDataToGPUBuffer(trimmedData, includeSH);
+      gpuBuf = f32Data.buffer;
+      dbg == null ? void 0 : dbg.info(
+        `gpuData: ${(f32Data.byteLength / 1048576).toFixed(1)}MB, includeSH=${includeSH}, floats=${f32Data.length}, floats/splat=${f32Data.length / this.splatCount}`
+      );
+    }
     this.splatBuffer = device.createBuffer({
-      size: gpuData.byteLength,
+      size: gpuBuf.byteLength,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
     });
-    device.queue.writeBuffer(this.splatBuffer, 0, gpuData.buffer);
+    device.queue.writeBuffer(this.splatBuffer, 0, gpuBuf);
+    dbg == null ? void 0 : dbg.info(`Creating sorter: compact=${this.compactLayout}, half=${this.halfPrecision}, sortBits=${this.sortBits}`);
     this.sorter = new GSSplatSorter(
       device,
       this.splatCount,
       this.splatBuffer,
-      this.uniformBuffer
+      this.uniformBuffer,
+      {},
+      this.compactLayout,
+      this.halfPrecision,
+      this.sortBits
     );
     this.sorter.setScreenSize(this.renderer.width, this.renderer.height);
     this.sorter.setCullingOptions({
@@ -9271,6 +9794,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
         { binding: 2, resource: { buffer: this.sorter.getIndicesBuffer() } }
       ]
     });
+    dbg == null ? void 0 : dbg.info(`setCompactData complete, bindGroup created`);
     if (this.editorEnabled) this.rebuildEditorBindGroup();
     this.sortStateInitialized = false;
   }
@@ -9294,7 +9818,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     this.renderer.device.queue.writeBuffer(this.uniformBuffer, 0, ud);
     const changed = this.needsSort();
     this.frameCounter++;
-    const shouldSort = changed || this.sortFrequency > 1 && this.frameCounter % this.sortFrequency === 0;
+    const shouldSort = !this.sortStateInitialized || changed;
     if (shouldSort) {
       this.sorter.setScreenSize(this.renderer.width, this.renderer.height);
       this.sorter.setCullingOptions({
@@ -9302,9 +9826,24 @@ const _GSSplatRenderer = class _GSSplatRenderer {
         farPlane: this.camera.far,
         pixelThreshold: this.pixelCullThreshold,
         maxVisibleCount: this.maxVisibleSplats,
-        depthRangeLimit: this.depthRangeLimit
+        depthRangeLimit: this.depthRangeLimit,
+        lodSkipRate: this.lodSkipRate
       });
-      this.sorter.sort();
+      if (!this.debugFrameLogged) {
+        const dbg = getDebugOverlay();
+        const dev = this.renderer.device;
+        dev.pushErrorScope("validation");
+        dev.pushErrorScope("out-of-memory");
+        this.sorter.sort();
+        dev.popErrorScope().then((err2) => {
+          if (err2) dbg == null ? void 0 : dbg.error(`Sort OOM: ${err2.message}`);
+        });
+        dev.popErrorScope().then((err2) => {
+          if (err2) dbg == null ? void 0 : dbg.error(`Sort Validation: ${err2.message}`);
+        });
+      } else {
+        this.sorter.sort();
+      }
     }
     if (this.editorEnabled && this.editorPipeline && this.editorBindGroup) {
       pass.setPipeline(this.editorPipeline);
@@ -9314,6 +9853,28 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       pass.setBindGroup(0, this.bindGroup);
     }
     pass.drawIndirect(this.sorter.getDrawIndirectBuffer(), 0);
+    if (!this.debugFrameLogged) {
+      this.debugFrameLogged = true;
+      const dbg = getDebugOverlay();
+      dbg == null ? void 0 : dbg.info(
+        `First render: splats=${this.splatCount}, canvas=${this.renderer.width}x${this.renderer.height}, editor=${this.editorEnabled}, depthWrite=${this.depthWriteEnabled}`
+      );
+      if (dbg && this.sorter) {
+        const pos2 = this.camera.position;
+        dbg.info(`Camera pos: [${pos2[0].toFixed(2)}, ${pos2[1].toFixed(2)}, ${pos2[2].toFixed(2)}]`);
+        dbg.info(
+          `Culling cfg: pixelThresh=${this.pixelCullThreshold.toFixed(2)}, maxVisible=${this.maxVisibleSplats}, depthRange=${this.depthRangeLimit.toFixed(2)}, near=${this.camera.near}, far=${this.camera.far}`
+        );
+        this.sorter.readbackIndirect().then((data) => {
+          dbg.info(
+            `DrawIndirect: vtx=${data[0]}, inst=${data[1]}, firstVtx=${data[2]}, firstInst=${data[3]}`
+          );
+          if (data[0] === 0 && data[1] === 0) {
+            dbg.error("ALL splats culled! visible=0");
+          }
+        });
+      }
+    }
   }
   getSplatCount() {
     return this.splatCount;
@@ -9631,10 +10192,13 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   }
   createEditorPipeline() {
     const device = this.renderer.device;
-    const editorShaderCode = this.buildEditorShader().replace(
+    let editorShaderCode = this.buildEditorShader().replace(
       "const SH_LEVEL: u32 = 3u; // @SH_LEVEL_INJECT@",
       `const SH_LEVEL: u32 = ${this.shMode}u;`
     );
+    if (this.compactLayout) {
+      editorShaderCode = transformShaderForCompact(editorShaderCode);
+    }
     const shaderModule = device.createShaderModule({ code: editorShaderCode });
     this.editorBindGroupLayout = device.createBindGroupLayout({
       entries: [
@@ -18727,6 +19291,10 @@ class App {
     __publicField(this, "animationId", 0);
     // 是否使用移动端渲染器
     __publicField(this, "useMobileRenderer", false);
+    // 移动端优化开关（默认关闭，由外部显式启用）
+    __publicField(this, "mobileOptimizationsEnabled", false);
+    // 移动端可见 splat 硬上限（保证稳定帧率）
+    __publicField(this, "mobileMaxVisibleCap", 0);
     // 最近加载的 CompactSplatData（用于编辑器导出）
     __publicField(this, "lastCompactData", null);
     // 自适应性能控制
@@ -18736,6 +19304,17 @@ class App {
     });
     __publicField(this, "lastAppliedRenderScale", 1);
     __publicField(this, "baseRenderScale", 1);
+    // 动态分辨率：移动时降分辨率，静止后恢复
+    __publicField(this, "dynamicResolutionEnabled", false);
+    __publicField(this, "dynResLastViewMatrix", new Float32Array(16));
+    __publicField(this, "dynResStillFrames", 0);
+    __publicField(this, "dynResCurrentScale", 1);
+    __publicField(this, "DYNRES_MOVE_SCALE", 0.6);
+    // 移动时 DPR*0.6（2.0*0.6=1.2）
+    __publicField(this, "DYNRES_STILL_SCALE", 1);
+    // 静止时 DPR*1.0
+    __publicField(this, "DYNRES_STILL_THRESHOLD", 2);
+    // 静止 2 帧即恢复
     // 绑定的事件处理函数
     __publicField(this, "boundOnResize");
     /** 额外渲染回调（在 gizmo 之前、场景辅助之后执行） */
@@ -18789,16 +19368,46 @@ class App {
       nearDepthRangeRatio: 2
     };
     console.log(
-      `[3DGS] Apple GPU detected (${this.renderer.gpuVendor}/${this.renderer.gpuArchitecture}), applying TBDR optimizations: SH→L1, depthWrite off, aggressive culling`
+      `[3DGS] Apple GPU detected (${this.renderer.gpuVendor}/${this.renderer.gpuArchitecture}), applying TBDR optimizations: depthWrite off, aggressive culling`
     );
   }
   /**
-   * 创建桌面端 GSSplatRenderer 并自动应用平台优化
+   * 启用/禁用移动端性能优化（默认关闭）
+   * 开启后，加载模型时将自动应用：f16 半精度、16-bit 排序、像素剔除、动态分辨率等。
+   * 应在 init() 之后、加载模型之前调用。
+   */
+  enableMobileOptimizations(enabled = true) {
+    var _a2;
+    this.mobileOptimizationsEnabled = enabled;
+    if (enabled) {
+      this.dynamicResolutionEnabled = true;
+      createDebugOverlay();
+      (_a2 = getDebugOverlay()) == null ? void 0 : _a2.info(
+        `Mobile optimizations enabled. DPR=${window.devicePixelRatio}, canvas=${this.canvas.width}x${this.canvas.height}`
+      );
+      console.log(`[3DGS] Mobile optimizations: f16, sortBits=16, pixelThreshold=1.5, dynamicRes=ON`);
+    } else {
+      this.dynamicResolutionEnabled = false;
+    }
+  }
+  isMobileOptimized() {
+    return this.mobileOptimizationsEnabled;
+  }
+  /**
+   * 创建 GSSplatRenderer 并自动应用平台优化
+   * @param forMobile 移动端模式：半精度（32B/splat）+ SH L0，内存降为 1/8
    */
-  createDesktopGSRenderer() {
+  createGSRendererUnified(forMobile = false) {
     const renderer = new GSSplatRenderer(this.renderer, this.camera);
-    if (this.renderer.isAppleGPU) {
+    if (forMobile) {
+      renderer.setHalfPrecision(true);
+      renderer.setSortBits(16);
+      renderer.setPixelCullThreshold(1.5);
+      renderer.setSortFrequency(2);
+    } else if (this.renderer.isAppleGPU) {
       renderer.setSHMode(SHMode.L1);
+    }
+    if (this.renderer.isAppleGPU) {
       renderer.setDepthWriteEnabled(false);
     }
     return renderer;
@@ -18845,7 +19454,7 @@ class App {
    */
   async addPLY(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
-      const isMobile = isMobileDevice();
+      const useMobileOpt = this.mobileOptimizationsEnabled;
       let buffer;
       if (typeof urlOrBuffer === "string") {
         buffer = await this.fetchWithProgress(
@@ -18868,40 +19477,26 @@ class App {
           onProgress(50 + parseProgress, "parse");
         }
       };
-      let gsRenderer;
-      if (isMobile) {
-        gsRenderer = new GSSplatRendererMobile(this.renderer, this.camera);
-        this.useMobileRenderer = true;
-        const compactData = await this.parsePLYBuffer(buffer, {
-          maxSplats: Infinity,
-          loadSH: false,
-          onProgress: parseProgressCallback,
-          coordinateSystem
-        });
-        if (onProgress) onProgress(90, "upload");
-        gsRenderer.setCompactData(compactData);
-        if (onProgress) onProgress(100, "upload");
-        this.lastCompactData = compactData;
-        this.sceneManager.setGSRenderer(gsRenderer);
-        this.hotspotManager.setGSRenderer(gsRenderer);
-        return compactData.count;
-      } else {
-        gsRenderer = this.createDesktopGSRenderer();
-        this.useMobileRenderer = false;
-        const compactData = await this.parsePLYBuffer(buffer, {
-          maxSplats: Infinity,
-          loadSH: true,
-          onProgress: parseProgressCallback,
-          coordinateSystem
-        });
-        if (onProgress) onProgress(90, "upload");
-        gsRenderer.setCompactData(compactData);
-        if (onProgress) onProgress(100, "upload");
-        this.lastCompactData = compactData;
-        this.sceneManager.setGSRenderer(gsRenderer);
-        this.hotspotManager.setGSRenderer(gsRenderer);
-        return compactData.count;
+      if (useMobileOpt) {
+        console.log(
+          "[3DGS] Mobile optimizations active, using SH L0"
+        );
       }
+      const gsRenderer = this.createGSRendererUnified(useMobileOpt);
+      this.useMobileRenderer = false;
+      const compactData = await this.parsePLYBuffer(buffer, {
+        maxSplats: Infinity,
+        loadSH: !useMobileOpt,
+        onProgress: parseProgressCallback,
+        coordinateSystem
+      });
+      if (onProgress) onProgress(90, "upload");
+      gsRenderer.setCompactData(compactData);
+      if (onProgress) onProgress(100, "upload");
+      this.lastCompactData = compactData;
+      this.sceneManager.setGSRenderer(gsRenderer);
+      this.hotspotManager.setGSRenderer(gsRenderer);
+      return compactData.count;
     } catch (error) {
       throw error;
     }
@@ -18912,7 +19507,7 @@ class App {
    */
   async addSplat(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
-      const isMobile = isMobileDevice();
+      const useMobileOpt = this.mobileOptimizationsEnabled;
       let buffer;
       if (typeof urlOrBuffer === "string") {
         buffer = await this.fetchWithProgress(
@@ -18943,23 +19538,9 @@ class App {
       }
       if (onProgress) onProgress(90, "parse");
       if (onProgress) onProgress(90, "upload");
-      let gsRenderer;
-      if (isMobile) {
-        const mobileRenderer = new GSSplatRendererMobile(
-          this.renderer,
-          this.camera
-        );
-        this.useMobileRenderer = true;
-        const compactData = App.splatCpuToCompactData(splats);
-        mobileRenderer.setCompactData(compactData);
-        this.lastCompactData = compactData;
-        gsRenderer = mobileRenderer;
-      } else {
-        const desktopRenderer = this.createDesktopGSRenderer();
-        this.useMobileRenderer = false;
-        desktopRenderer.setData(splats);
-        gsRenderer = desktopRenderer;
-      }
+      const gsRenderer = this.createGSRendererUnified(useMobileOpt);
+      this.useMobileRenderer = false;
+      gsRenderer.setData(splats);
       this.sceneManager.setGSRenderer(gsRenderer);
       this.hotspotManager.setGSRenderer(gsRenderer);
       if (onProgress) onProgress(100, "upload");
@@ -19004,7 +19585,7 @@ class App {
    */
   async addSOG(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
-      const isMobile = isMobileDevice();
+      const useMobileOpt = this.mobileOptimizationsEnabled;
       let buffer;
       if (typeof urlOrBuffer === "string") {
         buffer = await this.fetchWithProgress(
@@ -19046,14 +19627,8 @@ class App {
         }
       }
       if (onProgress) onProgress(90, "upload");
-      let gsRenderer;
-      if (isMobile) {
-        gsRenderer = new GSSplatRendererMobile(this.renderer, this.camera);
-        this.useMobileRenderer = true;
-      } else {
-        gsRenderer = this.createDesktopGSRenderer();
-        this.useMobileRenderer = false;
-      }
+      const gsRenderer = this.createGSRendererUnified(useMobileOpt);
+      this.useMobileRenderer = false;
       gsRenderer.setCompactData(compactData);
       this.lastCompactData = compactData;
       this.sceneManager.setGSRenderer(gsRenderer);
@@ -19104,6 +19679,21 @@ class App {
     this.render();
     this.animationId = requestAnimationFrame(this.animate.bind(this));
   }
+  updateDynamicResolution() {
+    if (!this.dynamicResolutionEnabled) return;
+    const interacting = this.controls.isInteracting;
+    if (interacting) {
+      if (this.dynResCurrentScale !== this.DYNRES_MOVE_SCALE) {
+        this.dynResCurrentScale = this.DYNRES_MOVE_SCALE;
+        this.renderer.setRenderScale(this.DYNRES_MOVE_SCALE);
+      }
+    } else {
+      if (this.dynResCurrentScale !== this.DYNRES_STILL_SCALE) {
+        this.dynResCurrentScale = this.DYNRES_STILL_SCALE;
+        this.renderer.setRenderScale(this.DYNRES_STILL_SCALE);
+      }
+    }
+  }
   updateAdaptivePerformance() {
     if (!this.adaptivePerformanceEnabled) return;
     const gsRenderer = this.getGSRenderer();
@@ -19147,7 +19737,11 @@ class App {
       gsRenderer.setMaxVisibleSplats(0);
     } else {
       const ratio = cfg.nearVisibleRatio + (1 - cfg.nearVisibleRatio) * t;
-      gsRenderer.setMaxVisibleSplats(Math.round(splatCount * ratio));
+      let maxVisible = Math.round(splatCount * ratio);
+      if (this.mobileMaxVisibleCap > 0) {
+        maxVisible = Math.min(maxVisible, this.mobileMaxVisibleCap);
+      }
+      gsRenderer.setMaxVisibleSplats(maxVisible);
     }
     if (cfg.enableDepthRangeLimit) {
       if (t >= 0.99) {
@@ -19157,16 +19751,13 @@ class App {
         gsRenderer.setDepthRangeLimit(depthRange);
       }
     }
-    if (t < 0.3) {
-      gsRenderer.setSortFrequency(2);
-    } else {
-      gsRenderer.setSortFrequency(1);
-    }
+    gsRenderer.setSortFrequency(1);
   }
   render() {
     var _a2, _b2;
     this.camera.setAspect(this.renderer.getAspectRatio());
     this.controls.update();
+    this.updateDynamicResolution();
     this.updateAdaptivePerformance();
     this.hotspotManager.updateBillboards();
     if ((_a2 = this.skyboxRenderer) == null ? void 0 : _a2.isActive) {
@@ -19742,10 +20333,6 @@ class App {
     if (gsRenderer) {
       gsRenderer.setSortFrequency(frequency);
     }
-    const mobileRenderer = this.getGSRendererMobile();
-    if (mobileRenderer) {
-      mobileRenderer.setSortFrequency(frequency);
-    }
   }
   /**
    * 是否检测到 Apple GPU（M1/M2/M3 等）