s3m-three 0.3.13 → 0.4.15

package/src/render/StyleMaterial.ts

@@ -168,7 +168,33 @@ export const DEFAULT_STYLE: S3MStyle = {
   fadeIn: 0,
 };
 
-export interface StyledMaterial extends THREE.MeshStandardMaterial {
+/** 光照模型：pbr（默认，MeshStandardMaterial）| lambert（省 GGX 与环境球谐） */
+export type MaterialQuality = 'pbr' | 'lambert';
+
+/**
+ * 当前光照模型。模块级全局 —— 与 anisotropy / maxTextureSize 同一套设计，
+ * 同页多个图层会互相覆盖，后创建的那个决定全局。只影响**之后创建**的材质。
+ */
+let materialQuality: MaterialQuality = 'pbr';
+
+/**
+ * 切换光照模型。
+ *
+ * 'pbr'（默认）= `MeshStandardMaterial`，GGX + 环境球谐，质感最好也最贵。
+ * 'lambert' = `MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
+ * 白模 / 纯色 / 按高度着色这类不需要高光的模式，肉眼差别很小。
+ *
+ * 注意：只影响之后创建的材质 —— 已加载的瓦片要重新加载才会换。
+ */
+export function setMaterialQuality(q: MaterialQuality): void {
+  materialQuality = q === 'lambert' ? 'lambert' : 'pbr';
+}
+
+export function getMaterialQuality(): MaterialQuality {
+  return materialQuality;
+}
+
+export type StyledMaterial = (THREE.MeshStandardMaterial | THREE.MeshLambertMaterial) & {
   userData: {
     uSelBatch: { value: number };
     uSelWhole: { value: number };
@@ -785,11 +811,11 @@ export interface StyledMaterialOptions {
  */
 export function createStyledMaterial(opts: StyledMaterialOptions): StyledMaterial {
   const uniforms = opts.uniforms;
-  const mat = new THREE.MeshStandardMaterial({
+  // 两种光照模型共用的参数。注入的 chunk 只动 diffuseColor / normal / transformed，
+  // 在 Standard 与 Lambert 的 shader 里都存在同名 include，所以模板不用分支。
+  const baseParams = {
     color: opts.color ?? new THREE.Color(0xffffff),
     map: opts.map ?? null,
-    roughness: opts.roughness ?? 0.95,
-    metalness: 0,
     side: opts.side ?? THREE.DoubleSide,
     transparent: !!opts.transparent,
     opacity: opts.opacity ?? 1,
@@ -800,7 +826,16 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     // 顶点色、贴图全部在自定义 chunk 里处理，不让 three 插手
     vertexColors: false,
     alphaTest: opts.alphaTest ?? 0,
-  }) as StyledMaterial;
+  };
+  const mat = (
+    materialQuality === 'lambert'
+      ? new THREE.MeshLambertMaterial(baseParams)
+      : new THREE.MeshStandardMaterial({
+          ...baseParams,
+          roughness: opts.roughness ?? 0.95,
+          metalness: 0,
+        })
+  ) as StyledMaterial;
 
   // 选中单体编号：每个 Mesh 独立，默认 -1 表示无选中
   const uSelBatch = { value: -1 };

package/src/render/TextureFactory.ts

@@ -17,8 +17,28 @@ export { PixelFormat } from '../core/TextureFormat.js';
 /** 由 S3MLayer 在拿到 GL 上下文后注入，用于斜视角下保持纹理清晰 */
 let maxAnisotropy = 1;
 
-export function setMaxAnisotropy(n: number): void {
+/**
+ * 各向异性过滤的**上限**（默认 Infinity = 不封顶，取 GPU 报的最大值）。
+ *
+ * 各向异性对斜视角立面清晰度的提升比提高分辨率更直接，所以默认全量启用；
+ * 但它每像素要多采样，移动端 GPU 上封到 4 或 8 通常肉眼无差、成本明显下降。
+ * 由 `setMaxAnisotropy(gpuMax, cap)` 一起注入，接入方通过 `anisotropyCap` 配置。
+ */
+let anisotropyCap = Infinity;
+
+export function setMaxAnisotropy(n: number, cap = Infinity): void {
   maxAnisotropy = Math.max(1, n | 0);
+  anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
+}
+
+/**
+ * 纹理长边像素上限（默认 Infinity = 不限制）。
+ * 只作用于非图集的 RGBA / WebP 产物，见 `core/TextureDecode.ts` 的 `maxSize`。
+ */
+let maxTextureSize = Infinity;
+
+export function setMaxTextureSize(n: number): void {
+  maxTextureSize = Number.isFinite(n) && n >= 1 ? n : Infinity;
 }
 
 /**
@@ -42,23 +62,28 @@ export interface DecodedTexture {
 /**
  * 注入「离线解码」实现（S3MViewer 装配：走共享解析 Worker）。
  * 返回 null = Worker 不可用 / 崩溃，createTexture 自动退回主线程 decodeTextureData。
+ * `maxSize` 一并带过去，缩放也在 Worker 里做（同样是 CPU 活）。
  */
 let offThreadDecode:
-  | ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>)
+  | ((tex: S3MTexture, compressed: boolean, maxSize?: number) => Promise<DecodedTextureData | null>)
   | null = null;
 
 export function setTextureOffThreadDecode(
-  fn: ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>) | null
+  fn: ((tex: S3MTexture, compressed: boolean, maxSize?: number) => Promise<DecodedTextureData | null>) | null
 ): void {
   offThreadDecode = fn;
 }
 
-async function decodeTexture(tex: S3MTexture, compressed: boolean): Promise<DecodedTextureData> {
+async function decodeTexture(
+  tex: S3MTexture,
+  compressed: boolean,
+  maxSize: number
+): Promise<DecodedTextureData> {
   if (offThreadDecode) {
-    const viaWorker = await offThreadDecode(tex, compressed);
+    const viaWorker = await offThreadDecode(tex, compressed, maxSize);
     if (viaWorker) return viaWorker;
   }
-  return decodeTextureData(tex, { compressed });
+  return decodeTextureData(tex, { compressed, maxSize });
 }
 
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
@@ -68,7 +93,7 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.minFilter = THREE.LinearMipmapLinearFilter;
   tex.generateMipmaps = true;
   // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
-  tex.anisotropy = maxAnisotropy;
+  tex.anisotropy = anisotropyCap === Infinity ? maxAnisotropy : Math.min(maxAnisotropy, anisotropyCap);
   if (srgb) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
   tex.needsUpdate = true;
@@ -103,7 +128,9 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
 
   // 压缩直传只在「宿主 GL 支持 + 非图集」时开：图集要 flipY / 无 mip，压缩上传做不了翻行
   const wantCompressed = compressedTexturesSupported && !isAtlas;
-  const data = await decodeTexture(tex, wantCompressed);
+  // 尺寸上限同样跳过图集：UV 已重映射到子区域，缩放会让整体错位
+  const sizeCap = isAtlas ? Infinity : maxTextureSize;
+  const data = await decodeTexture(tex, wantCompressed, sizeCap);
 
   if (!data.rgba && !data.blocks && !data.bitmap) {
     if (data.error) {

package/src/tileset/S3MTileset.ts

@@ -261,6 +261,16 @@ export interface S3MTilesetOptions {
   maxRetries?: number;
   /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
   lodRangeScale?: number;
+  /**
+   * 本数据集**驻留三角形总数**的软上限（默认不限制）。
+   *
+   * `maxTiles` 只数瓦片个数：一块精模瓦片几十万面，64 块照样能把差设备压垮，
+   * 所以在瓦片数之外再给一条按面数的刹车。超了走同一套 make-before-break 淘汰
+   * （只踢「当前不显示」或「位置已被可见子瓦接管」的瓦片），不在画面上开洞。
+   *
+   * 不传 = 不限制，行为与旧版完全一致。运行时可用 `setMaxTriangles()` 调整。
+   */
+  maxTriangles?: number;
   /**
    * 是否请求 `.texblock` 子图集（S3MBLOCK 根图集的清晰版）。**默认关**。
    *
@@ -315,6 +325,11 @@ export class S3MTileset {
 
   maxConcurrent: number;
   maxTiles: number;
+  /**
+   * 驻留三角形总数的软上限。`Infinity` = 不限制（默认），此时 `_trimBudget` 的
+   * 判据与旧版逐字一致，不会多算一次面数。
+   */
+  maxTriangles: number;
   lodRangeScale: number;
 
   /** 数据集配置声明的高度范围（米），若配置未声明则返回 null */
@@ -369,6 +384,7 @@ export class S3MTileset {
     // 并发与总量限制：iServer 公开服务上别把人家打爆
     this.maxConcurrent = options.maxConcurrent ?? 4;
     this.maxTiles = options.maxTiles ?? 64;
+    this.maxTriangles = options.maxTriangles ?? Infinity;
     this.maxImageCache = options.maxImageCache ?? 128;
     // 硬上限 = 软上限 + 余量。淘汰只在「新瓦片已经落地并接管显示」之后做（make-before-break），
     // 所以中间态允许临时超出 maxTiles；硬上限只用来挡住失控的请求量，不用于挤掉正在显示的内容。
@@ -566,17 +582,40 @@ export class S3MTileset {
     return true;
   }
 
+  /** 当前驻留瓦片的三角形总数（只算已落地的；在途瓦片还没构建，统计不到） */
+  private _residentTriangles(): number {
+    let total = 0;
+    for (const node of this.nodes.values()) total += node.stats?.triangles ?? 0;
+    return total;
+  }
+
+  /**
+   * 运行时调整面数预算。`Infinity` = 不限制（默认）。
+   * 收紧后不会立刻掉内容，要等下一次 `_trimBudget`（下一帧 update）才生效。
+   */
+  setMaxTriangles(n: number): void {
+    this.maxTriangles = n > 0 ? n : Infinity;
+  }
+
   /**
    * 预算裁剪 —— 必须在可见性算完之后调用（make-before-break）：
    * 新瓦片已经落地、也已经决定由谁负责显示，这时候才把没人依赖的那块裁掉。
    * 只踢「当前不显示」或「位置已被可见子瓦接手」的瓦片；挑不出安全候选时允许
-   * 暂时超出 maxTiles，等下一帧再裁 —— 宁可多占一会儿内存，也不在画面上开洞。
+   * 暂时超出预算，等下一帧再裁 —— 宁可多占一会儿内存，也不在画面上开洞。
+   *
+   * 两条预算并行：瓦片数（`maxTiles`）与三角形总数（`maxTriangles`，默认不限制）。
+   * `maxTriangles` 为 Infinity 时短路，行为与只有瓦片数预算时完全一致。
    */
   private _trimBudget(): boolean {
     let removed = false;
     let guard = 0;
     // 在途的也算进"预期驻留数"：不然一批瓦片同时落地时会先把画面撑爆再疯狂裁
-    while (this.nodes.size + this.pending.size > this.maxTiles && guard++ <= this.maxTiles + 8) {
+    const overTiles = () => this.nodes.size + this.pending.size > this.maxTiles;
+    const overTriangles = () =>
+      Number.isFinite(this.maxTriangles) && this._residentTriangles() > this.maxTriangles;
+    // 面数预算生效时可能要连踢多块，迭代上限跟着驻留规模走；不生效时根本进不了循环
+    const iterationCap = this.nodes.size + this.maxTiles + 16;
+    while ((overTiles() || overTriangles()) && guard++ <= iterationCap) {
       if (!this._evictOne(this.nodes.size + this.pending.size > this.hardCap)) break;
       removed = true;
     }

package/src/worker/S3MWorkerClient.ts

@@ -97,13 +97,16 @@ export class S3MWorkerClient {
     });
   }
 
-  /** 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据 */
-  decodeTexture(tex: S3MTexture, compressed = false): Promise<DecodedTextureData> {
+  /**
+   * 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据。
+   * `maxSize` 交给 Worker 侧收口——缩放本身也是 CPU 活，放在 Worker 里主线程零成本。
+   */
+  decodeTexture(tex: S3MTexture, compressed = false, maxSize?: number): 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, compressed });
+      this._worker.postMessage({ type: 'tex', id, tex, compressed, maxSize });
     });
   }
 
@@ -147,12 +150,13 @@ export function getSharedS3MWorker(): S3MWorkerClient | null {
  */
 export async function decodeTextureWithWorker(
   tex: S3MTexture,
-  compressed: boolean
+  compressed: boolean,
+  maxSize?: number
 ): Promise<DecodedTextureData | null> {
   const client = getSharedS3MWorker();
   if (!client) return null;
   try {
-    return await client.decodeTexture(tex, compressed);
+    return await client.decodeTexture(tex, compressed, maxSize);
   } catch {
     return null;
   }

package/src/worker/s3mWorker.ts

@@ -29,7 +29,7 @@ type ParseRequest = {
   assemble?: boolean;
   batching?: boolean;
 };
-type TexRequest = { type: 'tex'; id: number; tex: S3MTexture; compressed?: boolean };
+type TexRequest = { type: 'tex'; id: number; tex: S3MTexture; compressed?: boolean; maxSize?: number };
 type Request = ParseRequest | TexRequest;
 
 type ParseResponse =
@@ -65,7 +65,7 @@ ctx.onmessage = async (e: MessageEvent<Request>) => {
         ctx.postMessage({ id, ok: true, tile } satisfies ParseResponse, collectTransferables(tile));
       }
     } else {
-      const data = await decodeTextureData(msg.tex, { compressed: msg.compressed });
+      const data = await decodeTextureData(msg.tex, { compressed: msg.compressed, maxSize: msg.maxSize });
       ctx.postMessage({ id, ok: true, data } satisfies TexResponse, texTransferList(data));
     }
   } catch (err) {