s3m-three 0.3.6 → 0.3.7

package/docs/API.md

@@ -165,6 +165,8 @@ new S3MViewer(options?: S3MViewerOptions)
 | `maxConcurrent` | `number` | `4` | 每个数据集并发请求数 |
 | `useWorker` | `boolean` | `true` | 用 Web Worker 解析经典 `.s3mb` 瓦片（inflate / Draco / MeshOpt 全在 Worker 跑，主线程只做 fetch 与几何组装）；Worker 不可用或崩溃时自动永久降级主线程。S3MBLOCK 路径仍主线程解析 |
 | （随 `useWorker`）纹理解码 | `boolean` | `true` | DXT / CRN / WEBP 纹理解码与 `.s3mb` 解析共用同一个 Worker（`core/TextureDecode.ts` 三方共用同一份实现，WEBP 走可 transfer 的 ImageBitmap）；失败自动回主线程，产物逐字节一致 |
+| （随 `useWorker`）几何组装 | `boolean` | `true` | 顶点解交错 / 法线计算 / 同材质合批合并（`core/TileGeometry.ts`）随解析在 Worker 完成，主线程只做 three 对象包装；Worker 不可用时主线程跑同一份实现，产物一致 |
+| （随 `useWorker`）DXT 压缩直传 | 自动 | 自动 | 宿主 GL 同时支持 `WEBGL_compressed_texture_s3tc`(+srgb) 时，dxt1/dxt5（含 CRN 转码产物）不解码直接 `CompressedTexture` 上传，显存与上传带宽降为 1/4~1/8；块长与 4×4 对齐公式不符、flipY 图集、移动端无扩展时自动回退 RGBA 解码 |
 | `lodRangeScale` | `number` | `1.0` | LOD 切换距离缩放系数，> 1 更倾向保留粗模，< 1 提前细化 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 业务属性查询配置，配了才能 `colorByField()`，见[按业务字段着色](#按业务字段着色) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {

package/src/core/TextureDecode.ts

@@ -26,10 +26,25 @@ export interface DecodedTextureData {
   /** WEBP 路径的解码结果（ImageBitmap 可 transfer，主线程直接 new THREE.Texture 包） */
   bitmap: ImageBitmap | null;
   hasAlpha: boolean;
+  /**
+   * 压缩直传模式（decodeTextureData 的 compressed 选项）：不解码，原样返回 DXT 块，
+   * 主线程用 CompressedTexture 硬件解压上传。与 rgba 互斥。
+   */
+  blocks?: Uint8Array;
+  blockFormat?: 'dxt1' | 'dxt5';
   /** CRN 转码失败时的原始错误（渲染层负责打 warn） */
   error?: string;
 }
 
+export interface DecodeOptions {
+  /**
+   * 压缩直传：dxt1/dxt5（含 CRN 转码产物）不解码，原样返回 DXT 块。
+   * 仅在宿主支持 WEBGL_compressed_texture_s3tc(+srgb) 时开启；
+   * flipY 纹理走不了压缩上传（WebGL 对压缩纹理忽略 UNPACK_FLIP_Y），自动回退解码。
+   */
+  compressed?: boolean;
+}
+
 /** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
 function flipRows(rgba: Uint8Array, width: number, height: number): void {
   const row = width * 4;
@@ -92,8 +107,23 @@ function rawRGBA(tex: S3MTexture): { rgba: Uint8Array; hasAlpha: boolean } {
   return { rgba: out, hasAlpha: hasAlphaChannel(pixelFormat) };
 }
 
+/**
+ * DXT 块数据的期望字节数：4×4 对齐块 × 每块字节（DXT1=8，DXT5=16）。
+ * S3M 纹理宽高不总是 4 的倍数，驱动按声明尺寸算期望大小——对不上就是
+ * GL_INVALID_VALUE: glCompressedTexSubImage2D: The <imageSize> does not match。
+ * 压缩直传前必须用这个函数把关，不匹配就回退 RGBA 解码。
+ */
+export function expectedDxtByteLength(width: number, height: number, format: 'dxt1' | 'dxt5'): number {
+  const bw = (width + 3) >> 2;
+  const bh = (height + 3) >> 2;
+  return bw * bh * (format === 'dxt1' ? 8 : 16);
+}
+
 /** 主线程 / Worker 共用的解码入口。不抛错：失败与不支持都体现在返回值里 */
-export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTextureData> {
+export async function decodeTextureData(
+  tex: S3MTexture,
+  options: DecodeOptions = {}
+): Promise<DecodedTextureData> {
   const empty: DecodedTextureData = {
     kind: 'unsupported(0/0)',
     width: 0,
@@ -106,13 +136,35 @@ export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTexture
 
   const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
 
+  // 压缩直传的公共前提：不是 GL 翻行图集（压缩上传无法 flipY）
+  const canCompress = options.compressed === true && !tex.flipY;
+
+  /** 块数据字节数与 4×4 对齐公式一致才允许直传，否则回退解码 */
+  const compressible = (data: Uint8Array, w: number, h: number, format: 'dxt1' | 'dxt5'): boolean =>
+    data.byteLength === expectedDxtByteLength(w, h, format);
+
   if (kind === 'crn') {
     try {
       const crn = await transcodeCRN(tex.data);
+      const pf = crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5;
+      const fmt = crn.dxtFormat === 1 ? 'dxt1' : 'dxt5';
+      if (canCompress && compressible(crn.data, crn.width, crn.height, fmt)) {
+        // CRN→DXT 的转码免不了（wasm），但后续的 DXT→RGBA 解块省掉，块数据直传 GPU
+        return {
+          kind: `crn->dxt${crn.dxtFormat}(c)`,
+          width: crn.width,
+          height: crn.height,
+          rgba: null,
+          bitmap: null,
+          hasAlpha: pf === PixelFormat.DXT5,
+          blocks: crn.data,
+          blockFormat: fmt,
+        };
+      }
       const decoded = decodeDXT({
         width: crn.width,
         height: crn.height,
-        pixelFormat: crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5,
+        pixelFormat: pf,
         data: crn.data,
       });
       return {
@@ -138,7 +190,21 @@ export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTexture
   }
 
   if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
-    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
+    const pf = dxtPixelFormatOf(kind);
+    // dxt3/dxt4 少见，不进直传白名单；块长与 4×4 对齐公式不符的也回退解码
+    if (canCompress && (kind === 'dxt1' || kind === 'dxt5') && compressible(tex.data, tex.width, tex.height, kind)) {
+      return {
+        kind: `${kind}(c)`,
+        width: tex.width,
+        height: tex.height,
+        rgba: null,
+        bitmap: null,
+        hasAlpha: kind === 'dxt5',
+        blocks: tex.data,
+        blockFormat: kind,
+      };
+    }
+    const decoded = decodeDXT({ ...tex, pixelFormat: pf });
     return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };
   }