s3m-three 0.4.16 → 0.4.17

package/src/render/S3MViewer.ts

@@ -24,7 +24,7 @@ import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
 import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap } from './TextureFactory.js';
-import { setMaterialQuality } from './StyleMaterial.js';
+import { getMaterialQuality, setMaterialQuality } from './StyleMaterial.js';
 import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import {
   STYLE,
@@ -32,6 +32,7 @@ import {
   SELECT_MODE,
   DEFAULT_STYLE,
   createSharedUniforms,
+  createStyledMaterial,
   createOutlineMaterial,
   resolveEdgeModes,
   sameEdgeModes,
@@ -40,11 +41,13 @@ import type {
   OutlineMaterial,
   OutlineStyleUniforms,
   StyledMaterial,
+  StyledMaterialOptions,
   StyleMode,
   SelectMode,
   S3MStyle,
   EdgeModes,
   EdgesOption,
+  MaterialQuality,
 } from './StyleMaterial.js';
 import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import { Picker } from './Picker.js';
@@ -1864,8 +1867,11 @@ export class S3MViewer {
           mat.transparent = o < 0.999;
           const keepDepth = this.style.depthWrite !== false;
           mat.depthWrite = mat.transparent ? keepDepth : (this.style.depthWrite !== false);
-          mat.flatShading = this.style.shading !== 'smooth';
-          mat.needsUpdate = true;
+          // shading 走共享 uniform（uFlatShading），不写 mat.flatShading / needsUpdate——
+          // transparent / depthWrite 也不是 program 决定项，整套样式继承零重编译
+          if (mat.userData.uFlatShading) {
+            mat.userData.uFlatShading.value = this.style.shading !== 'smooth' ? 1 : 0;
+          }
           this._featureStyleManager.applyOverridesToMesh(mesh);
           this._startTileFade(mesh, mat);
         }
@@ -2369,26 +2375,74 @@ export class S3MViewer {
 
   /** 平面/平滑着色：FLAT_SHADED 是编译期宏，改它必须重编译 */
   private _applyShading(): void {
-    const flat = this.style.shading !== 'smooth';
+    // shading 现在是共享 uniform（uFlatShading）驱动的运行期分支，不再是
+    // flatShading define：翻一个 float 就完成切换，零重编译、零卡顿。
+    const target = this.style.shading !== 'smooth' ? 1 : 0;
     for (const p of this._pickables.values()) {
       const m = styledMaterialOf(p.mesh);
-      if (!m || m.flatShading === flat) continue;
-      m.flatShading = flat;
-      m.needsUpdate = true;
+      const u = m?.userData.uFlatShading;
+      if (!u || u.value === target) continue;
+      u.value = target;
     }
     this._requestRepaint();
   }
 
   /**
-   * 预热另一种 `shading` 变体，让首次切换不再同步编译着色器。
+   * 运行时切换材质质感（`'pbr'` | `'lambert'`）。
    *
-   * 做法是「把材质翻到另一种变体 → 编译 → 翻回来」：three 的 program 缓存按
-   * cacheKey（含 flatShading / defines）分桶，编译一次就留在缓存里，之后
-   * `_applyShading()` 切过去只是取缓存。
+   * 档位是模块级设置（影响之后新建的材质）；已加载瓦片的材质在这里**原位重建**：
+   * 不重拉瓦片、不重建几何，按创建时记录的参数（`userData.s3mOpts`）换一个
+   * 新材质实例，并保留逐材质状态（选中编号、瓦片淡入、批量状态纹理）。
+   * 切换后 program 需要重新编译一次（lambert / pbr 是不同着色器），这是唯一开销。
+   */
+  setMaterialQuality(q: MaterialQuality): void {
+    setMaterialQuality(q);
+    this._rebuildStyledMaterials();
+    this._requestRepaint();
+  }
+
+  /** 当前材质质感档位 */
+  get materialQuality(): MaterialQuality {
+    return getMaterialQuality();
+  }
+
+  /** 按创建参数原位重建所有 styled 材质（materialQuality 切换用） */
+  private _rebuildStyledMaterials(): void {
+    // 逐材质 own uniform 的状态要在重建时搬过去，否则选中高亮 / 瓦片淡入会闪没
+    const PRESERVED = [
+      'uSelBatch',
+      'uSelWhole',
+      'uBatchTex',
+      'uBatchTex2',
+      'uBatchTexWidth',
+      'uBatchTexActive',
+      'uTileFade',
+    ] as const;
+    for (const p of this._pickables.values()) {
+      const mesh = p.mesh;
+      const raw = mesh.material;
+      if (Array.isArray(raw)) continue; // styled 材质恒为单材质；数组材质（点云等）不归这里管
+      const old = raw as StyledMaterial | undefined;
+      if (!old?.userData?.isStyled || !old.userData?.s3mOpts) continue;
+      const opts = old.userData.s3mOpts as StyledMaterialOptions;
+      const fresh = createStyledMaterial({ ...opts, uniforms: this.uniforms });
+      for (const key of PRESERVED) {
+        const src = old.userData[key] as { value: unknown } | undefined;
+        const dst = fresh.userData[key] as { value: unknown } | undefined;
+        if (src && dst) dst.value = src.value;
+      }
+      mesh.material = fresh;
+      old.dispose();
+    }
+  }
+
+  /**
+   * 预热着色 program，避免首帧同步编译。
    *
-   * 翻转期间材质是「错误变体」，所以用 `_prewarming` 让 renderFrame 跳过渲染——
-   * 少画一两帧看不出来，把平滑的楼画成平面的就很明显。
-   * 优先用 `compileAsync`（KHR_parallel_shader_compile），没有就退回同步 `compile`。
+   * shading 改为 `uFlatShading` 共享 uniform 驱动后（见 `_applyShading`），
+   * flat / smooth 共用同一个 program，不再存在「另一种变体」，也不需要
+   * 「翻变体 → 编译 → 翻回来」的那套流程与 `_prewarming` 跳帧。这里只把当前
+   * 唯一的 program 编一次（优先 `compileAsync`，KHR_parallel_shader_compile）。
    */
   async prewarmShading(): Promise<void> {
     if (this._shadingPrewarmed || this._prewarming) return;
@@ -2397,23 +2451,17 @@ export class S3MViewer {
     const camera = this.camera;
     if (!r || !scene || !camera) return;
 
-    const mats: StyledMaterial[] = [];
-    const seen = new Set<THREE.Material>();
+    // 场上还没有材质就没必要预热：program 会在首个材质出现时编译
+    let hasMaterial = false;
     for (const p of this._pickables.values()) {
-      const m = styledMaterialOf(p.mesh);
-      if (!m || seen.has(m)) continue;
-      seen.add(m);
-      mats.push(m);
+      if (styledMaterialOf(p.mesh)) {
+        hasMaterial = true;
+        break;
+      }
     }
-    if (mats.length === 0) return;
+    if (!hasMaterial) return;
 
     this._shadingPrewarmed = true;
-    this._prewarming = true;
-    // 当前是 smooth（flatShading = false）就预热 flat，反之预热 smooth
-    const target = this.style.shading === 'smooth';
-    const saved = mats.map((m) => m.flatShading);
-    for (const m of mats) m.flatShading = target;
-
     try {
       const anyR = r as unknown as {
         compileAsync?: (s: THREE.Object3D, c: THREE.Camera) => Promise<unknown>;
@@ -2421,15 +2469,9 @@ export class S3MViewer {
       if (typeof anyR.compileAsync === 'function') await anyR.compileAsync(scene, camera);
       else r.compile(scene, camera);
     } catch {
-      // 预热失败不影响主流程：最坏情况退回「首次切换时编译一次」
-    } finally {
-      for (let i = 0; i < mats.length; i++) {
-        mats[i].flatShading = saved[i];
-        mats[i].needsUpdate = true;
-      }
-      this._prewarming = false;
-      this._requestRepaint();
+      // 预热失败不影响主流程：最坏情况退回「首次渲染时编译一次」
     }
+    this._requestRepaint();
   }
 
   /**
@@ -3989,6 +4031,10 @@ export class S3MViewer {
       vertices: 0,
       triangles: 0,
       datasets: this.datasets.size,
+      drawCalls: 0,
+      programs: 0,
+      textures: 0,
+      geometries: 0,
     };
     for (const entry of this.datasets.values()) {
       const s = entry.tileset?.stats;
@@ -4000,6 +4046,15 @@ export class S3MViewer {
       total.vertices += s.vertices;
       total.triangles += s.triangles;
     }
+    // GPU 侧预算观测：draw call / program / 显存驻留。没有渲染器（未 mount /
+    // 纯解析场景）时保持 0，不抛错。
+    const info = this.renderer?.info;
+    if (info) {
+      total.drawCalls = info.render.calls;
+      total.programs = info.programs?.length ?? 0;
+      total.textures = info.memory.textures;
+      total.geometries = info.memory.geometries;
+    }
     return total;
   }
 

package/src/render/StyleMaterial.ts

@@ -375,6 +375,12 @@ export function createSharedUniforms(): StyleUniforms {
      * （压暗 → 换模式 → 亮回来），比硬切自然得多。
      */
     uFade: { value: 1 },
+    /**
+     * 平面 / 平滑着色开关：0 = 平滑（插值法线），1 = 平面（屏幕导数法线）。
+     * 走 uniform 而不是 three 的 `flatShading` define，所以切换 shading 不会触发
+     * 着色器重编译（旧实现靠 prewarm 把卡顿藏起来，现在连卡顿都没有）。
+     */
+    uFlatShading: { value: 1 },
   };
 }
 const VERT_PARS = /* glsl */ `
@@ -411,6 +417,8 @@ const VERT_PARS = /* glsl */ `
   varying float vWorldZ;
   varying vec3 vWorldNormal;
   varying vec3 vWorldPos;
+  // 视图空间位置：平面着色用它算屏幕导数法线，符号与 three 的 vViewPosition 一致
+  varying vec3 vS3MViewPos;
 
   // 跨 chunk 共享的顶点姿态变量（在 beginnormal_vertex 建立，begin_vertex / worldpos 使用）
   vec3 s3mCustomOffset;
@@ -576,6 +584,9 @@ const VERT_WORLD = /* glsl */ `
     mat3 s3mNormMat = mat3( modelMatrix );
   #endif
   vWorldNormal = normalize( s3mNormMat * ( s3mRot * normal ) );
+  // 视图空间位置直接拷 three 的 vViewPosition（此处已在 project_vertex 之后，
+  // 含实例化 / 形变的最终值）：平面着色的导数法线与 FLAT_SHADED 分支逐点一致
+  vS3MViewPos = vViewPosition;
 `;
 
 const FRAG_PARS = /* glsl */ `
@@ -684,6 +695,8 @@ const FRAG_PARS = /* glsl */ `
   varying float vWorldZ;
   varying vec3 vWorldNormal;
   varying vec3 vWorldPos;
+  varying vec3 vS3MViewPos;
+  uniform float uFlatShading;
 
   vec4 s3mSampleBatchRow0( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
     vec4 vA = texture2D( texA, uv );
@@ -885,6 +898,12 @@ export interface StyledMaterialOptions {
   transparent?: boolean;
   opacity?: number;
   roughness?: number;
+  /**
+   * @deprecated 旧版用 three 的 `flatShading` define 表达，切换必重编译；现在
+   * shading 走共享 uniform `uFlatShading`（见 `createSharedUniforms`），运行期
+   * 二选一。此参数仅作为 uniform 的**初始值**被兼容（false = smooth），
+   * 运行期切换请走 viewer 的 `setStyle({ shading })`。
+   */
   flatShading?: boolean;
   /** >0 时开启 alphaTest：镂空贴图（S3MBLOCK 图集）的透明片元直接丢弃，避免渲染成黑面 */
   alphaTest?: number;
@@ -898,6 +917,27 @@ export interface StyledMaterialOptions {
  * 创建一个带样式的 PBR 材质。
  * 每个 Mesh 独享一个材质实例，但 uniform 对象是全局共享的。
  */
+/**
+ * 片元法线覆盖：平面着色时用屏幕导数算真实几何法线。
+ *
+ * 注入在 `<normal_fragment_begin>` 之后——此时 three 已按平滑路径算好 `normal`
+ * （来自插值 vNormal）；uFlatShading > 0.5 时用视图空间位置的导数叉积覆盖它，
+ * 数学上与 three 的 FLAT_SHADED 分支逐点一致（vS3MViewPos 符号对齐 vViewPosition）。
+ * 因为是运行期分支而非编译期 define，切 shading 不再触发重编译。
+ */
+const FRAG_NORMAL = /* glsl */ `
+  if ( uFlatShading > 0.5 ) {
+    vec3 s3mFlatN = normalize( cross( dFdx( vS3MViewPos ), dFdy( vS3MViewPos ) ) );
+    #ifdef USE_DOUBLE_SIDED
+      s3mFlatN = s3mFlatN * ( float( gl_FrontFacing ) * 2.0 - 1.0 );
+    #endif
+    #ifdef USE_FLIP_SIDED
+      s3mFlatN = - s3mFlatN;
+    #endif
+    normal = s3mFlatN;
+  }
+`;
+
 export function createStyledMaterial(opts: StyledMaterialOptions): StyledMaterial {
   const uniforms = opts.uniforms;
   // 两种光照模型共用的参数。注入的 chunk 只动 diffuseColor / normal / transformed，
@@ -909,9 +949,10 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     transparent: !!opts.transparent,
     opacity: opts.opacity ?? 1,
     depthWrite: opts.transparent ? false : true,
-    // 白模 / OSGB 的法线多是共享顶点平均出来的，平滑插值会让墙面出现斑驳，
-    // 默认走平面着色（片元里用导数算法线），墙面才干净。
-    flatShading: opts.flatShading !== false,
+    // 白模 / OSGB 的法线多是共享顶点平均出来的，平滑插值会让墙面出现斑驳。
+    // 平面 / 平滑不再走 three 的 flatShading define（那是编译期变体，切换必重编译），
+    // 改由共享 uniform uFlatShading 在片元里二选一：材质恒为平滑，program 因此稳定。
+    flatShading: false,
     // 顶点色、贴图全部在自定义 chunk 里处理，不让 three 插手
     vertexColors: false,
     alphaTest: opts.alphaTest ?? 0,
@@ -930,6 +971,10 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   const uSelBatch = { value: -1 };
   // 没有单体化信息的几何（batchId = -1）只能整块选中
   const uSelWhole = { value: 0 };
+  // shading 开关：跟随共享 uniforms（改一次全场景生效）；测试里可能不传
+  // uniforms，这里兜底一份独立对象，与旧代码容忍 uniforms === undefined 的口径一致。
+  // 兼容旧参数：显式传 flatShading: false（旧语义 = smooth）映射为初始值 0
+  const uFlatShading = uniforms?.uFlatShading ?? { value: opts.flatShading === false ? 0 : 1 };
   const uBatchTex = { value: DUMMY_BATCH_TEX };
   const uBatchTex2 = { value: DUMMY_BATCH_TEX };
   const uBatchTexWidth = { value: 1.0 };
@@ -950,6 +995,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     Object.assign(shader.uniforms, uniforms, {
       uSelBatch,
       uSelWhole,
+      uFlatShading,
       uBatchTex,
       uBatchTex2,
       uBatchTexWidth,
@@ -987,6 +1033,12 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     } else if (secMap) {
       shader.fragmentShader = shader.fragmentShader.replace('#include <map_fragment>', `#include <map_fragment>\n${FRAG_BAKE}`);
     }
+
+    // 平面 / 平滑着色：运行期分支（见 FRAG_NORMAL），不再依赖 flatShading define
+    shader.fragmentShader = shader.fragmentShader.replace(
+      '#include <normal_fragment_begin>',
+      `#include <normal_fragment_begin>\n${FRAG_NORMAL}`
+    );
   };
 
   // 不同材质共用同一段注入代码，必须让 three 认为它们的 program 可复用；
@@ -1009,6 +1061,10 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   mat.userData.uBatchTexWidth = uBatchTexWidth;
   mat.userData.uBatchTexActive = uBatchTexActive;
   mat.userData.uTileFade = uTileFade;
+  // 平面 / 平滑着色开关：S3MViewer._applyShading 翻它，不触发重编译
+  mat.userData.uFlatShading = uFlatShading;
+  // 记录创建参数：materialQuality 运行时切换时按原参数重建材质（换类不换外观）
+  mat.userData.s3mOpts = opts;
   mat.userData.isStyled = true;
   return mat;
 }

package/src/tileset/S3MTileset.ts

@@ -321,7 +321,21 @@ export class S3MTileset {
   readonly atlasUpgraded = new Set<string>();
   /** 拿到高清版但判定不通过 → 原因。用于排查「为什么这块还是糊的」 */
   readonly atlasUpgradeSkipped = new Map<string, string>();
-  readonly stats: Stats = { tiles: 0, loading: 0, failed: 0, meshes: 0, vertices: 0, triangles: 0, datasets: 1 };
+  // drawCalls / programs / textures / geometries 是 viewer 级 GPU 观测，
+  // 瓦片侧不产生，恒为 0；聚合时由 S3MViewer.stats 用 renderer.info 覆盖
+  readonly stats: Stats = {
+    tiles: 0,
+    loading: 0,
+    failed: 0,
+    meshes: 0,
+    vertices: 0,
+    triangles: 0,
+    datasets: 1,
+    drawCalls: 0,
+    programs: 0,
+    textures: 0,
+    geometries: 0,
+  };
 
   maxConcurrent: number;
   maxTiles: number;