s3m-three 0.3.6 → 0.3.8

package/src/render/StyleMaterial.ts

@@ -115,8 +115,23 @@ export interface S3MStyle {
   roofThreshold?: number;
   /** 是否与模型原色贴图叠加混合（0 = 纯色覆盖，1 = 叠乘原色贴图） */
   texMix?: number;
+  /**
+   * 基础漫反射底色增益 / 直通自发光微调（0~1，默认 0.0，建议开启 TOP_SIDE 时可设 0.15~0.3）。
+   * 绕过光照夹角直接补偿表面暗部底色，让 TOP_SIDE / 自定义等模式下的背光阴影面保持通透、不至于过黑。
+   */
+  ambientGain?: number;
   /** 半透明时是否保持深度写入（默认 true，保持写入可彻底遮挡背面与内部棱线，避免背面透出） */
   depthWrite?: boolean;
+  /**
+   * 新瓦片首次出现时的淡入时长（毫秒，0 = 关闭）。
+   *
+   * 只影响「刚加载进来」的瓦片，已经显示的不会被重播。LOD 细化换瓦片时也会淡入，
+   * 视觉上比「啪」一下换掉柔和得多。
+   *
+   * 注意代价：淡入期间该瓦片会进透明渲染队列（混合 + 前后排序），首次加载
+   * 几百块瓦片同时淡入时会有一小段额外开销，所以默认关闭、按需开启。
+   */
+  fadeIn?: number;
 }
 
 export const DEFAULT_STYLE: S3MStyle = {
@@ -147,7 +162,9 @@ export const DEFAULT_STYLE: S3MStyle = {
   edgeThreshold: 55,
   roofThreshold: 0.65,
   texMix: 0,
+  ambientGain: 0,
   depthWrite: true,
+  fadeIn: 0,
 };
 
 export interface StyledMaterial extends THREE.MeshStandardMaterial {
@@ -157,6 +174,8 @@ export interface StyledMaterial extends THREE.MeshStandardMaterial {
     uBatchTex: { value: THREE.Texture };
     uBatchTexWidth: { value: number };
     uBatchTexActive: { value: number };
+    /** 单块瓦片的淡入系数（1 = 完全显示） */
+    uTileFade: { value: number };
     isStyled: true;
     [key: string]: unknown;
   };
@@ -205,9 +224,25 @@ export function createSharedUniforms(): StyleUniforms {
     uRoofThreshold: { value: 0.65 },
     /** 与模型原色贴图混合强度：0 = 纯色覆盖，1 = 叠乘原色贴图 */
     uTexMix: { value: 0 },
+    /** 基础底色增益 / 暗部补偿（0~1，默认 0.0） */
+    uAmbientGain: { value: 0 },
+    /**
+     * 图层整体透明度：在片元里乘进 diffuseColor.a。
+     *
+     * 为什么不做成 `material.opacity`：那是逐材质写入，几百块瓦片就是 O(meshes)，
+     * 而且跨 0.999 改 `material.transparent` 会换 program（`opaque` 参与缓存键）。
+     * 放到共享 uniform 里，透明度动画就退化成一次 float 赋值。
+     */
+    uOpacity: { value: 1 },
+    /** 棱线淡入淡出乘子：setEdges 过渡期间 0→1，新插入的瓦片自动继承 */
+    uEdgeFade: { value: 1 },
+    /**
+     * 整体压暗乘子：`mode` 这类不可插值的切换用它做 fade-through
+     * （压暗 → 换模式 → 亮回来），比硬切自然得多。
+     */
+    uFade: { value: 1 },
   };
 }
-
 const VERT_PARS = /* glsl */ `
   attribute float aBatchId;
   attribute vec3 aColor;
@@ -391,6 +426,10 @@ const FRAG_PARS = /* glsl */ `
   uniform float uSelWhole;
   uniform float uRoofThreshold;
   uniform float uTexMix;
+  uniform float uAmbientGain;
+  uniform float uOpacity;
+  uniform float uTileFade;
+  uniform float uFade;
   varying float vBatchId;
   varying vec3 vVertColor;
   varying float vWorldZ;
@@ -430,6 +469,8 @@ const FRAG_PARS = /* glsl */ `
 const FRAG_COLOR = /* glsl */ `
   float s3mH = clamp( ( vWorldZ - uHeightMin ) / max( uHeightMax - uHeightMin, 0.001 ), 0.0, 1.0 );
   vec3 s3mBase = diffuseColor.rgb;   // 已含 diffuse × map
+  // 图层整体透明度（共享 uniform）+ 单瓦片淡入系数（逐材质），逐帧改都不产生重编译
+  diffuseColor.a *= uOpacity * uTileFade;
   // 所有按单体取值（配色 / 状态纹理 / 选中判定）都走取整后的 id，避免插值噪声
   float s3mBid = s3mBatchId();
 
@@ -531,6 +572,10 @@ const FRAG_COLOR = /* glsl */ `
   } else {
     diffuseColor.rgb *= mix( 1.0, uDimFactor, uDim );
   }
+
+  // 压暗乘子放在最后：mode 分支会整体覆写 diffuseColor.rgb，
+  // 放在前面会被覆盖掉。setMode 的 fade-through 就靠它。
+  diffuseColor.rgb *= uFade;
 `;
 
 const FRAG_EMISSIVE = /* glsl */ `
@@ -539,6 +584,10 @@ const FRAG_EMISSIVE = /* glsl */ `
   if ( uSelMode != 3 ) {
     totalEmissiveRadiance += uSelColor * s3mSelE * uSelMix * ( uSelEmissive * 0.4 );
   }
+  // 直通自发光微调 / 环境光底色提升：补偿背光阴影面（尤其 TOP_SIDE 立面），避免光照阴影面过暗
+  if ( uAmbientGain > 0.001 ) {
+    totalEmissiveRadiance += diffuseColor.rgb * uAmbientGain;
+  }
 `;
 
 const FRAG_BAKE = /* glsl */ `
@@ -596,6 +645,8 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   const uBatchTex = { value: DUMMY_BATCH_TEX };
   const uBatchTexWidth = { value: 1.0 };
   const uBatchTexActive = { value: 0 };
+  /** 单块瓦片的淡入系数：逐材质独享（每块网格一份材质），默认 1 = 完全显示 */
+  const uTileFade = { value: 1 };
 
   // 图集材质：只有几何确实带了 aAtlasRect 才开这个宏，否则缺属性会采到 (0,0) 的默认值
   const atlas = !!opts.atlas && !!opts.map;
@@ -613,6 +664,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
       uBatchTex,
       uBatchTexWidth,
       uBatchTexActive,
+      uTileFade,
       uSecMap: { value: secMap },
       uAtlasDim,
       uAtlasDim1,
@@ -656,6 +708,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   mat.userData.uBatchTex = uBatchTex;
   mat.userData.uBatchTexWidth = uBatchTexWidth;
   mat.userData.uBatchTexActive = uBatchTexActive;
+  mat.userData.uTileFade = uTileFade;
   mat.userData.isStyled = true;
   return mat;
 }

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);
@@ -1164,7 +1178,9 @@ export class S3MTileset {
       if (inRange) node.lastSeen = this._frame;
 
       const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
-      const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold : metric > threshold);
+      // 加入 8% 迟滞区间（Hysteresis Band），防止相机在 LOD 临界距离处发生父子瓦片逐帧来回横跳闪烁
+      const hFactor = node.needRefine ? (byDistance ? 1.08 : 0.92) : 1.0;
+      const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
       node.needRefine = needRefine;
 
       const dbgSeen = ((globalThis as { __S3M_LOD_SEEN?: Set<string> }).__S3M_LOD_SEEN ??= new Set<string>());

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) {