s3m-three 0.3.6 → 0.3.7

package/src/render/S3MViewer.ts

@@ -23,7 +23,7 @@
 import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
-import { setMaxAnisotropy, setTextureOffThreadDecode } from './TextureFactory.js';
+import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode } from './TextureFactory.js';
 import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import {
   STYLE,
@@ -438,8 +438,7 @@ export class S3MViewer {
    * MapLibre 宿主由 S3MLayer 在 onAdd 里调用；纯 three 宿主直接传自己的 canvas / gl。
    */
   /** 创建并配置一个绑定到给定 gl 上下文的 three renderer（mount 与上下文恢复共用） */
-  private _createRenderer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): THREE.WebGLRenderer {
-    const r = new THREE.WebGLRenderer({
+  private _createRenderer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): THREE.WebGLRenderer {    const r = new THREE.WebGLRenderer({
       canvas,
       context: gl as WebGLRenderingContext,
       antialias: true,
@@ -452,11 +451,19 @@ export class S3MViewer {
     return r;
   }
 
+  /** 按 GL 能力开/关 DXT 压缩直传：两个 s3tc 扩展都要在（srgb 缺了贴图会发白失配） */
+  private _syncTextureCapabilities(gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    const s3tc = !!gl.getExtension('WEBGL_compressed_texture_s3tc');
+    const s3tcSrgb = !!gl.getExtension('WEBGL_compressed_texture_s3tc_srgb');
+    setCompressedTexturesSupported(s3tc && s3tcSrgb);
+  }
+
   mount(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
     this.canvas = canvas;
 
     this.renderer = this._createRenderer(canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    this._syncTextureCapabilities(gl);
 
     this.scene = new THREE.Scene();
     this.scene.add(this.groundManager.group);
@@ -498,6 +505,7 @@ export class S3MViewer {
     }
     this.renderer = this._createRenderer(this.canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    this._syncTextureCapabilities(gl);
     this.picker?.dispose();
     this.picker = new Picker(this.renderer);
     // 共享 uniform / 材质引用不变，three 重新编译着色器时会自然接管；

package/src/render/TextureFactory.ts

@@ -21,6 +21,18 @@ export function setMaxAnisotropy(n: number): void {
   maxAnisotropy = Math.max(1, n | 0);
 }
 
+/**
+ * DXT 压缩直传开关（S3MViewer 在 mount / 上下文恢复时按 GL 能力注入）：
+ * 需要 WEBGL_compressed_texture_s3tc 与 s3tc_srgb 两个扩展同时可用 ——
+ * 纹理是 SRGBColorSpace，缺 srgb 变体会出现贴图发白的颜色失配。
+ * 移动端大多没有 s3tc，自动回退 Worker 解码成 RGBA 上传，行为同旧版。
+ */
+let compressedTexturesSupported = false;
+
+export function setCompressedTexturesSupported(v: boolean): void {
+  compressedTexturesSupported = v;
+}
+
 export interface DecodedTexture {
   texture: THREE.Texture | null;
   /** 实际走的解码路径，`unsupported(26)` 这类值会进 stats.skipped */
@@ -31,20 +43,22 @@ export interface DecodedTexture {
  * 注入「离线解码」实现（S3MViewer 装配：走共享解析 Worker）。
  * 返回 null = Worker 不可用 / 崩溃，createTexture 自动退回主线程 decodeTextureData。
  */
-let offThreadDecode: ((tex: S3MTexture) => Promise<DecodedTextureData | null>) | null = null;
+let offThreadDecode:
+  | ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>)
+  | null = null;
 
 export function setTextureOffThreadDecode(
-  fn: ((tex: S3MTexture) => Promise<DecodedTextureData | null>) | null
+  fn: ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>) | null
 ): void {
   offThreadDecode = fn;
 }
 
-async function decodeTexture(tex: S3MTexture): Promise<DecodedTextureData> {
+async function decodeTexture(tex: S3MTexture, compressed: boolean): Promise<DecodedTextureData> {
   if (offThreadDecode) {
-    const viaWorker = await offThreadDecode(tex);
+    const viaWorker = await offThreadDecode(tex, compressed);
     if (viaWorker) return viaWorker;
   }
-  return decodeTextureData(tex);
+  return decodeTextureData(tex, { compressed });
 }
 
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
@@ -87,9 +101,11 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   // 关 GPU mip，层级由 StyleMaterial.s3mAtlasUnit 的内联金字塔自己算。
   const isAtlas = tex.packed === true || tex.flipY === true || tex.composed === true;
 
-  const data = await decodeTexture(tex);
+  // 压缩直传只在「宿主 GL 支持 + 非图集」时开：图集要 flipY / 无 mip，压缩上传做不了翻行
+  const wantCompressed = compressedTexturesSupported && !isAtlas;
+  const data = await decodeTexture(tex, wantCompressed);
 
-  if (!data.rgba && !data.bitmap) {
+  if (!data.rgba && !data.blocks && !data.bitmap) {
     if (data.error) {
       // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
       console.warn('[s3m] CRN 转码失败：', data.error);
@@ -100,12 +116,30 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   let texture: THREE.Texture;
   if (data.bitmap) {
     texture = new THREE.Texture(data.bitmap);
+  } else if (data.blocks && data.blockFormat) {
+    // DXT 块直传：GPU 硬件解压，省 4~8 倍上传带宽与显存。压缩纹理不能 generateMipmaps
+    // （WebGL 限制），远处靠 LinearFilter 兜底；s3mHasAlpha 走 alphaTest 的 DXT1 1bit
+    // alpha 历史上没开过，DXT5 的 hasAlpha 由 decodeTextureData 判定
+    const format =
+      data.blockFormat === 'dxt1' ? THREE.RGB_S3TC_DXT1_Format : THREE.RGBA_S3TC_DXT5_Format;
+    texture = new THREE.CompressedTexture(
+      [{ data: data.blocks, width: data.width, height: data.height }],
+      data.width,
+      data.height,
+      format,
+      THREE.UnsignedByteType
+    );
   } else {
     const dt = new THREE.DataTexture(data.rgba!, data.width, data.height, THREE.RGBAFormat, THREE.UnsignedByteType);
     if (data.hasAlpha) dt.userData.s3mHasAlpha = true;
     texture = dt;
   }
   texture.needsUpdate = true;
+  const configured = isAtlas ? configureAtlas(texture) : configure(texture);
+  if (data.blocks) {
+    configured.generateMipmaps = false;
+    configured.minFilter = THREE.LinearFilter;
+  }
   // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
-  return { texture: isAtlas ? configureAtlas(texture) : configure(texture), decoded: data.kind };
+  return { texture: configured, decoded: data.kind };
 }

package/src/tileset/S3MTileset.ts

@@ -27,6 +27,7 @@ import type {
   TexblockRequestPlan,
 } from '../core/S3MBlockParser.js';
 import type { Anchor, ParsedTile, Stats, StyleUniforms } from '../core/types.js';
+import type { TileGeometryData } from '../core/TileGeometry.js';
 import type { Group, Texture } from 'three';
 
 function dirOf(url: string): string {
@@ -226,7 +227,12 @@ export interface TileNode {
 /** 瓦片构建器可注入，用于测试 / 服务端渲染（此时不需要 three） */
 export type BuildTileFn = (
   tile: ParsedTile,
-  options: { textureCache: Map<string, Texture>; uniforms: StyleUniforms | null }
+  options: {
+    textureCache: Map<string, Texture>;
+    uniforms: StyleUniforms | null;
+    /** Worker 侧已完成的纯数据几何组装（经典 .s3mb 路径），构建器直接包装成 three 对象 */
+    assembled?: TileGeometryData;
+  }
 ) => Promise<{ group: Group; stats: Partial<Stats> }>;
 
 export interface S3MTilesetOptions {
@@ -691,17 +697,18 @@ export class S3MTileset {
   }
 
   /**
-   * 经典 `.s3mb` 瓦片解析：优先走 Worker（把 inflate / Draco / MeshOpt 的 CPU 密集
-   * 解码搬离主线程），Worker 不可用或已崩溃时主线程兜底，两条路径输出完全一致。
+   * 经典 `.s3mb` 瓦片解析：优先走 Worker（inflate / Draco / MeshOpt / 几何组装
+   * 全在 Worker 做，一次往返带回 tile + 纯数据几何），Worker 不可用或已崩溃时
+   * 主线程兜底，两条路径输出完全一致。
    */
-  private async _parseClassicTile(buffer: ArrayBuffer): Promise<ParsedTile> {
+  private async _parseClassicTile(buffer: ArrayBuffer): Promise<{ tile: ParsedTile; geometry?: TileGeometryData }> {
     if (this._useWorker && this._workerClient === undefined) {
       // 与纹理解码共用进程级单例，避免每个数据集各起一个 Worker
       this._workerClient = getSharedS3MWorker();
     }
     if (this._workerClient) {
       try {
-        return await this._workerClient.parseTile(buffer);
+        return await this._workerClient.parseTile(buffer, true);
       } catch (e) {
         if (e instanceof WorkerDeadError) {
           // 脚本加载失败 / 崩溃属于环境问题，永久退回主线程；瓦片本身的问题照常抛
@@ -711,7 +718,7 @@ export class S3MTileset {
         }
       }
     }
-    return parseS3MB(buffer);
+    return { tile: await parseS3MB(buffer) };
   }
 
   /**
@@ -985,6 +992,7 @@ export class S3MTileset {
       const isBlock = /\.s3mblock($|\?)/i.test(baseUrl);
 
       let tile: ParsedTile;
+      let assembled: TileGeometryData | undefined;
       let groupNames: string[] = [];
       const cachedSet = this._groupCache.get(baseUrl);
       if (cachedSet) {
@@ -1007,7 +1015,9 @@ export class S3MTileset {
           groupNames = set.names;
           tile = set.tiles[groupIndex] ?? set.tiles[0]!;
         } else {
-          tile = await this._parseClassicTile(buffer);
+          const parsed = await this._parseClassicTile(buffer);
+          tile = parsed.tile;
+          assembled = parsed.geometry;
         }
       }
       if (isBlock) {
@@ -1017,7 +1027,11 @@ export class S3MTileset {
       }
 
       const build = await this._builder();
-      const buildRes = await build(tile, { textureCache: this.textureCache, uniforms: this._uniforms });
+      const buildRes = await build(tile, {
+        textureCache: this.textureCache,
+        uniforms: this._uniforms,
+        assembled,
+      });
       const { group, stats } = buildRes;
       const texKeys = (buildRes as any).textureKeys ?? (group.userData?.textureKeys as string[] | undefined) ?? Object.keys(tile.textures ?? {});
       this.registerTileTextures(url, texKeys);

package/src/worker/S3MWorkerClient.ts

@@ -10,6 +10,7 @@
  */
 import type { ParsedTile, S3MTexture } from '../core/types.js';
 import type { DecodedTextureData } from '../core/TextureDecode.js';
+import type { TileGeometryData } from '../core/TileGeometry.js';
 
 /** Worker 崩溃 / 不可用 —— 与「瓦片数据本身有问题」区分开，调用方据此决定降级还是重试 */
 export class WorkerDeadError extends Error {
@@ -23,6 +24,7 @@ interface ParseOkResponse {
   id: number;
   ok: true;
   tile: ParsedTile;
+  geometry?: TileGeometryData;
 }
 
 interface TexOkResponse {
@@ -73,7 +75,7 @@ export class S3MWorkerClient {
         (err as { permanent?: boolean }).permanent = msg.permanent;
         waiter.reject(err);
       } else if ('tile' in msg) {
-        waiter.resolve(msg.tile);
+        waiter.resolve({ tile: msg.tile, geometry: msg.geometry });
       } else {
         waiter.resolve(msg.data);
       }
@@ -82,23 +84,26 @@ export class S3MWorkerClient {
     worker.onmessageerror = () => this._die('s3m 解析 Worker 消息无法反序列化');
   }
 
-  /** 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解 */
-  parseTile(buffer: ArrayBuffer): Promise<ParsedTile> {
+  /**
+   * 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解。
+   * assemble = true 时顺带在 Worker 里做纯数据几何组装，返回 { tile, geometry } 一次带回。
+   */
+  parseTile(buffer: ArrayBuffer, assemble = false, batching = true): Promise<{ tile: ParsedTile; geometry?: TileGeometryData }> {
     if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
     const id = ++this._seq;
-    return new Promise<ParsedTile>((resolve, reject) => {
+    return new Promise<{ tile: ParsedTile; geometry?: TileGeometryData }>((resolve, reject) => {
       this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this._worker.postMessage({ type: 'parse', id, buffer });
+      this._worker.postMessage({ type: 'parse', id, buffer, assemble, batching });
     });
   }
 
   /** 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据 */
-  decodeTexture(tex: S3MTexture): Promise<DecodedTextureData> {
+  decodeTexture(tex: S3MTexture, compressed = false): Promise<DecodedTextureData> {
     if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
     const id = ++this._seq;
     return new Promise<DecodedTextureData>((resolve, reject) => {
       this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this._worker.postMessage({ type: 'tex', id, tex });
+      this._worker.postMessage({ type: 'tex', id, tex, compressed });
     });
   }
 
@@ -138,12 +143,16 @@ export function getSharedS3MWorker(): S3MWorkerClient | null {
  * 纹理解码的「Worker 优先」入口，供 TextureFactory.setTextureOffThreadDecode 装配。
  * 永不 reject：Worker 不可用 / 崩溃 / 单张解码失败都返回 null，调用方主线程兜底
  * （解码失败本身在 decodeTextureData 里也不抛错，走 crn(failed) 之类的标记）。
+ * compressed 由 TextureFactory 按宿主 GL 能力传入，Worker 端据此跳过 DXT 解码。
  */
-export async function decodeTextureWithWorker(tex: S3MTexture): Promise<DecodedTextureData | null> {
+export async function decodeTextureWithWorker(
+  tex: S3MTexture,
+  compressed: boolean
+): Promise<DecodedTextureData | null> {
   const client = getSharedS3MWorker();
   if (!client) return null;
   try {
-    return await client.decodeTexture(tex);
+    return await client.decodeTexture(tex, compressed);
   } catch {
     return null;
   }

package/src/worker/s3mWorker.ts

@@ -16,15 +16,24 @@
  */
 import { parseS3MB } from '../core/S3MBParser.js';
 import { decodeTextureData } from '../core/TextureDecode.js';
+import { assembleTileGeometry } from '../core/TileGeometry.js';
 import type { ParsedTile, S3MTexture } from '../core/types.js';
+import type { TileGeometryData } from '../core/TileGeometry.js';
 import { collectTransferables } from './transferables.js';
 
-type ParseRequest = { type: 'parse'; id: number; buffer: ArrayBuffer };
-type TexRequest = { type: 'tex'; id: number; tex: S3MTexture };
+type ParseRequest = {
+  type: 'parse';
+  id: number;
+  buffer: ArrayBuffer;
+  /** 解析后顺带做纯数据几何组装（解交错 / 法线 / 合批），一次往返带回 */
+  assemble?: boolean;
+  batching?: boolean;
+};
+type TexRequest = { type: 'tex'; id: number; tex: S3MTexture; compressed?: boolean };
 type Request = ParseRequest | TexRequest;
 
 type ParseResponse =
-  | { id: number; ok: true; tile: ParsedTile }
+  | { id: number; ok: true; tile: ParsedTile; geometry?: TileGeometryData }
   | { id: number; ok: false; message: string; permanent: boolean };
 
 type TexResponse = { id: number; ok: true; data: Awaited<ReturnType<typeof decodeTextureData>> };
@@ -44,10 +53,19 @@ ctx.onmessage = async (e: MessageEvent<Request>) => {
   try {
     if (msg.type === 'parse') {
       const tile = await parseS3MB(msg.buffer);
-      // 响应整体过线（零拷贝）；请求 buffer 是主线程 structured clone 过来的副本，无需回传
-      ctx.postMessage({ id, ok: true, tile } satisfies ParseResponse, collectTransferables(tile));
+      if (msg.assemble) {
+        // 解析 + 组装一起做，避免 tile 回主线程后再整块克隆回来一次
+        const geometry = assembleTileGeometry(tile, { batching: msg.batching });
+        ctx.postMessage(
+          { id, ok: true, tile, geometry } satisfies ParseResponse,
+          [...collectTransferables(tile), ...collectTransferables(geometry)]
+        );
+      } else {
+        // 响应整体过线（零拷贝）；请求 buffer 是主线程 structured clone 过来的副本，无需回传
+        ctx.postMessage({ id, ok: true, tile } satisfies ParseResponse, collectTransferables(tile));
+      }
     } else {
-      const data = await decodeTextureData(msg.tex);
+      const data = await decodeTextureData(msg.tex, { compressed: msg.compressed });
       ctx.postMessage({ id, ok: true, data } satisfies TexResponse, texTransferList(data));
     }
   } catch (err) {