s3m-three 0.3.4 → 0.3.6

package/src/tileset/S3MTileset.ts

@@ -7,6 +7,7 @@
  *   命中阈值就请求 childTile，实现渐进式细化。
  */
 import { parseS3MB } from '../core/S3MBParser.js';
+import { getSharedS3MWorker, S3MWorkerClient, WorkerDeadError } from '../worker/S3MWorkerClient.js';
 import {
   composeLeafAtlas,
   expandTexblockRequestNames,
@@ -235,6 +236,15 @@ export interface S3MTilesetOptions {
   /** 原始图像/子图集缓存上限（LRU），默认 128 */
   maxImageCache?: number;
   buildTile?: BuildTileFn | null;
+  /**
+   * 是否用 Web Worker 解析经典 `.s3mb` 瓦片（默认开）。
+   *
+   * Worker 里跑 parseS3MB 全链路（inflate / Draco / MeshOpt 内联 wasm 解码），
+   * 主线程只做 fetch 与几何组装，消除加载阶段的解析卡顿。
+   * Worker 创建失败或崩溃时自动**永久**降级回主线程解析，行为与关闭时完全一致。
+   * S3MBLOCK 路径（图集补齐与主线程缓存强耦合）暂不进 Worker，仍主线程解析。
+   */
+  useWorker?: boolean;
   uniforms?: StyleUniforms | null;
   onTile?: (node: TileNode) => void;
   /** 超过 maxTiles 被淘汰时回调，调用方要自己把场景里的对象和拾取表清掉 */
@@ -330,6 +340,8 @@ export class S3MTileset {
   private isS3MV1 = false;
   private _buildTile: BuildTileFn | null;
   private readonly _uniforms: StyleUniforms | null;
+  /** 经典 .s3mb 的 Worker 解析客户端；undefined = 尚未尝试创建，null = 不可用/已降级 */
+  private _workerClient: S3MWorkerClient | null | undefined;  private readonly _useWorker: boolean;
   private _queue: string[] = [];
   private _active = 0;
 
@@ -346,6 +358,7 @@ export class S3MTileset {
     this._buildTile = options.buildTile ?? null;
     // 着色器共享 uniform，由 S3MLayer 持有并传进来
     this._uniforms = options.uniforms ?? null;
+    this._useWorker = options.useWorker !== false;
 
     // 并发与总量限制：iServer 公开服务上别把人家打爆
     this.maxConcurrent = options.maxConcurrent ?? 4;
@@ -677,6 +690,30 @@ export class S3MTileset {
     return this._buildTile;
   }
 
+  /**
+   * 经典 `.s3mb` 瓦片解析：优先走 Worker（把 inflate / Draco / MeshOpt 的 CPU 密集
+   * 解码搬离主线程），Worker 不可用或已崩溃时主线程兜底，两条路径输出完全一致。
+   */
+  private async _parseClassicTile(buffer: ArrayBuffer): Promise<ParsedTile> {
+    if (this._useWorker && this._workerClient === undefined) {
+      // 与纹理解码共用进程级单例，避免每个数据集各起一个 Worker
+      this._workerClient = getSharedS3MWorker();
+    }
+    if (this._workerClient) {
+      try {
+        return await this._workerClient.parseTile(buffer);
+      } catch (e) {
+        if (e instanceof WorkerDeadError) {
+          // 脚本加载失败 / 崩溃属于环境问题，永久退回主线程；瓦片本身的问题照常抛
+          this._workerClient = null;
+        } else {
+          throw e;
+        }
+      }
+    }
+    return parseS3MB(buffer);
+  }
+
   /**
    * 记住一个块文件里解析出来的全部 LOD 组。
    *
@@ -970,7 +1007,7 @@ export class S3MTileset {
           groupNames = set.names;
           tile = set.tiles[groupIndex] ?? set.tiles[0]!;
         } else {
-          tile = await parseS3MB(buffer);
+          tile = await this._parseClassicTile(buffer);
         }
       }
       if (isBlock) {
@@ -1269,6 +1306,7 @@ export class S3MTileset {
   }
 
   dispose(): void {
+    this._workerClient?.dispose();
     for (const node of this.nodes.values()) {
       node.group.traverse((o) => {
         const mesh = o as {

package/src/worker/S3MWorkerClient.ts

@@ -0,0 +1,150 @@
+/**
+ * 解析 Worker 的主线程客户端。
+ *
+ * 生命周期约定（由 S3MTileset 使用）：
+ * - `create()` 返回 null = 环境不可用（无 Worker / 脚本同步创建失败），调用方直接走主线程解析；
+ * - `parseTile()` 抛 `WorkerDeadError` = Worker 脚本加载失败或已崩溃，调用方应**永久**
+ *   退回主线程解析（不要再给这个 client 发活，也别让每块瓦片都白白失败两轮重试）；
+ * - 抛普通 Error = Worker 活着、但解析本身失败（网络字节坏了 / S3M1 容器永久错误等），
+ *   语义与主线程 `parseS3MB` 抛错完全一致，原样向上传。
+ */
+import type { ParsedTile, S3MTexture } from '../core/types.js';
+import type { DecodedTextureData } from '../core/TextureDecode.js';
+
+/** Worker 崩溃 / 不可用 —— 与「瓦片数据本身有问题」区分开，调用方据此决定降级还是重试 */
+export class WorkerDeadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkerDeadError';
+  }
+}
+
+interface ParseOkResponse {
+  id: number;
+  ok: true;
+  tile: ParsedTile;
+}
+
+interface TexOkResponse {
+  id: number;
+  ok: true;
+  data: DecodedTextureData;
+}
+
+interface ErrResponse {
+  id: number;
+  ok: false;
+  message: string;
+  permanent: boolean;
+}
+
+type Response = ParseOkResponse | TexOkResponse | ErrResponse;
+
+export class S3MWorkerClient {
+  private readonly _worker: Worker;
+  private _seq = 0;
+  private readonly _pending = new Map<number, { resolve: (v: unknown) => void; reject: (err: unknown) => void }>();
+  /** true = 已崩溃 / 已终止，后续请求直接拒绝 */
+  dead = false;
+
+  /** 创建失败返回 null（不抛），调用方据此走主线程解析 */
+  static create(): S3MWorkerClient | null {
+    if (typeof Worker === 'undefined') return null;
+    try {
+      // 路径锚定本模块的编译产物（dist/worker/s3mWorker.js）；
+      // Vite 打包时会把这个 pattern 转成独立 worker 资产，IIFE 直引场景由死锁降级兜底
+      const worker = new Worker(new URL('./s3mWorker.js', import.meta.url), { type: 'module' });
+      return new S3MWorkerClient(worker);
+    } catch {
+      return null;
+    }
+  }
+
+  private constructor(worker: Worker) {
+    this._worker = worker;
+    worker.onmessage = (e: MessageEvent<Response>) => {
+      const msg = e.data;
+      const waiter = this._pending.get(msg.id);
+      if (!waiter) return;
+      this._pending.delete(msg.id);
+      if (!msg.ok) {
+        // 还原主线程 parseS3MB 的错误形状：permanent 标记驱动瓦片级的「永久失败」分支
+        const err = new Error(msg.message);
+        (err as { permanent?: boolean }).permanent = msg.permanent;
+        waiter.reject(err);
+      } else if ('tile' in msg) {
+        waiter.resolve(msg.tile);
+      } else {
+        waiter.resolve(msg.data);
+      }
+    };
+    worker.onerror = () => this._die('s3m 解析 Worker 加载失败/崩溃');
+    worker.onmessageerror = () => this._die('s3m 解析 Worker 消息无法反序列化');
+  }
+
+  /** 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解 */
+  parseTile(buffer: ArrayBuffer): Promise<ParsedTile> {
+    if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
+    const id = ++this._seq;
+    return new Promise<ParsedTile>((resolve, reject) => {
+      this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this._worker.postMessage({ type: 'parse', id, buffer });
+    });
+  }
+
+  /** 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据 */
+  decodeTexture(tex: S3MTexture): 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 });
+    });
+  }
+
+  dispose(): void {
+    this._die('dispose');
+  }
+
+  private _die(reason: string): void {
+    if (this.dead) return;
+    this.dead = true;
+    try {
+      this._worker.terminate();
+    } catch {
+      /* 已死的 worker terminate 不会再抛 */
+    }
+    const err = new WorkerDeadError(`${reason}，退回主线程解析`);
+    for (const waiter of this._pending.values()) waiter.reject(err);
+    this._pending.clear();
+  }
+}
+
+/* ------------------------------------------------------------------ 共享单例 */
+
+/**
+ * 进程级共享的解析 Worker（解析 + 纹理解码共用一个线程，避免每个数据集 /
+ * 每个渲染层各起一个 Worker 把内存和调度打爆）。懒创建，崩溃后返回 null。
+ */
+let sharedClient: S3MWorkerClient | null | undefined;
+
+export function getSharedS3MWorker(): S3MWorkerClient | null {
+  if (sharedClient === undefined) sharedClient = S3MWorkerClient.create();
+  if (sharedClient && sharedClient.dead) return null;
+  return sharedClient;
+}
+
+/**
+ * 纹理解码的「Worker 优先」入口，供 TextureFactory.setTextureOffThreadDecode 装配。
+ * 永不 reject：Worker 不可用 / 崩溃 / 单张解码失败都返回 null，调用方主线程兜底
+ * （解码失败本身在 decodeTextureData 里也不抛错，走 crn(failed) 之类的标记）。
+ */
+export async function decodeTextureWithWorker(tex: S3MTexture): Promise<DecodedTextureData | null> {
+  const client = getSharedS3MWorker();
+  if (!client) return null;
+  try {
+    return await client.decodeTexture(tex);
+  } catch {
+    return null;
+  }
+}

package/src/worker/s3mWorker.ts

@@ -0,0 +1,58 @@
+/**
+ * S3M 解析 / 纹理解码 Worker 入口。
+ *
+ * 职责：把 CPU 密集的解码搬离主线程——
+ *   - parse：`.s3mb`（含 S3M 1.x / Draco / MeshOpt 内联 wasm 解码）整块解析；
+ *   - tex：  纹理解码（DXT 解块 / CRN wasm 转码 / WEBP createImageBitmap），
+ *            与主线程共用 core/TextureDecode.ts 的同一份实现。
+ * 抓取（fetch）仍由 S3MTileset 在主线程做——重试、退避、content-type 检查这些
+ * 语义都留在原处不动，Worker 只收字节、吐纯数据结果。
+ *
+ * 协议：
+ *   { type:'parse', id, buffer } → { id, ok:true, tile } | { id, ok:false, message, permanent }
+ *   { type:'tex',  id, tex }     → { id, ok:true, data } | { id, ok:false, message }
+ *
+ * 线程安全：两个入口都无模块级可变状态；每次调用用独立的 reader / 解码器实例。
+ */
+import { parseS3MB } from '../core/S3MBParser.js';
+import { decodeTextureData } from '../core/TextureDecode.js';
+import type { ParsedTile, S3MTexture } from '../core/types.js';
+import { collectTransferables } from './transferables.js';
+
+type ParseRequest = { type: 'parse'; id: number; buffer: ArrayBuffer };
+type TexRequest = { type: 'tex'; id: number; tex: S3MTexture };
+type Request = ParseRequest | TexRequest;
+
+type ParseResponse =
+  | { id: number; ok: true; tile: ParsedTile }
+  | { id: number; ok: false; message: string; permanent: boolean };
+
+type TexResponse = { id: number; ok: true; data: Awaited<ReturnType<typeof decodeTextureData>> };
+
+const ctx = self as unknown as Worker;
+
+/** 纹理解码响应的传输清单：RGBA 像素 buffer + WEBP 的 ImageBitmap 都走零拷贝 */
+function texTransferList(data: Awaited<ReturnType<typeof decodeTextureData>>): ArrayBuffer[] {
+  const list = collectTransferables(data);
+  if (data.bitmap) list.push(data.bitmap as unknown as ArrayBuffer);
+  return list;
+}
+
+ctx.onmessage = async (e: MessageEvent<Request>) => {
+  const msg = e.data;
+  const { id } = msg;
+  try {
+    if (msg.type === 'parse') {
+      const tile = await parseS3MB(msg.buffer);
+      // 响应整体过线（零拷贝）；请求 buffer 是主线程 structured clone 过来的副本，无需回传
+      ctx.postMessage({ id, ok: true, tile } satisfies ParseResponse, collectTransferables(tile));
+    } else {
+      const data = await decodeTextureData(msg.tex);
+      ctx.postMessage({ id, ok: true, data } satisfies TexResponse, texTransferList(data));
+    }
+  } catch (err) {
+    const permanent = (err as { permanent?: boolean } | null)?.permanent === true;
+    const message = String((err as Error | null)?.message ?? err);
+    ctx.postMessage({ id, ok: false, message, permanent });
+  }
+};

package/src/worker/transferables.ts

@@ -0,0 +1,58 @@
+/**
+ * 传输清单收集：递归扫出对象图里所有可 Transfer 的 ArrayBuffer（去重）。
+ *
+ * 用于 Worker 往返的零拷贝：postMessage 的 transferList 传这个清单后，
+ * 线程间共享同一块内存（structured clone 只拷贝「壳」，不拷字节）。
+ *
+ * 安全性约定：**要么全转，要么不转** —— 同一块 ArrayBuffer 上可能挂着多个视图
+ * （positions / normals 常是同一块顶点缓冲的 subarray），transferList 里出现它一次
+ * 之后所有视图共享的底层数据整体过线，视图本身仍然有效；但如果只转一半视图、
+ * 另一半留在原地，留在原地的会因 detach 变成空数据。所以只允许「把整个对象图
+ * 的 buffer 全部收集」或「完全不收集」两种用法，不支持挑着转。
+ */
+
+/** 递归深度上限。ParsedTile 的层级是固定的（tile → geoPackage → geode → package），远用不到 12 层 */
+const MAX_DEPTH = 12;
+
+export function collectTransferables(root: unknown): ArrayBuffer[] {
+  const buffers = new Set<ArrayBuffer>();
+  const seen = new Set<object>();
+
+  const walk = (value: unknown, depth: number): void => {
+    if (value == null || depth > MAX_DEPTH) return;
+    if (ArrayBuffer.isView(value)) {
+      const b = (value as ArrayBufferView).buffer;
+      if (b instanceof ArrayBuffer) buffers.add(b);
+      return;
+    }
+    if (value instanceof ArrayBuffer) {
+      buffers.add(value);
+      return;
+    }
+    if (typeof value !== 'object') return;
+    const obj = value as object;
+    if (seen.has(obj)) return;
+    seen.add(obj);
+    if (Array.isArray(obj)) {
+      for (const item of obj) walk(item, depth + 1);
+      return;
+    }
+    if (obj instanceof Map) {
+      for (const [k, v] of obj) {
+        walk(k, depth + 1);
+        walk(v, depth + 1);
+      }
+      return;
+    }
+    if (obj instanceof Set) {
+      for (const item of obj) walk(item, depth + 1);
+      return;
+    }
+    for (const key of Object.keys(obj)) {
+      walk((obj as Record<string, unknown>)[key], depth + 1);
+    }
+  };
+
+  walk(root, 0);
+  return [...buffers];
+}