s3m-three 0.4.15 → 0.4.17

package/src/render/StyleMaterial.ts

@@ -61,6 +61,75 @@ export const SELECT_MODE_LABELS: Record<SelectMode, string> = {
   [SELECT_MODE.GLOW_ONLY]: '仅描边发光 (Glow)',
 };
 
+/* ------------------------------------------------------------------ 棱线画法 */
+
+/**
+ * 全局棱线的画法。
+ *
+ * - `'line'`   CPU 折边线：焊合 → 折边判定 → 屏幕空间等宽四边形（默认口径）
+ * - `'offset'` 同上，但整段沿「边法线」往外推 `edgeOffset` 米。贴在面上的线会被
+ *              面的明暗吃掉，推出去一点才看得清，代价是要多带一条 aNormal 属性
+ * - `'hull'`   背面外扩轮廓：把整块几何沿法线鼓一圈、只画背面，得到「白模 + 卡通
+ *              描边」的观感。不建任何折边几何，成本就是多画一遍网格
+ * - `'gpu'`    纯片元描边：在主材质里用屏幕导数找「法线突变」的像素，直接混成棱线色。
+ *              零几何、零额外 pass，代价是线宽约 1 个设备像素，且描不出几何外轮廓
+ */
+export type EdgeStyle = 'line' | 'offset' | 'hull' | 'gpu';
+
+/**
+ * `style.edges` 的取值。
+ *
+ * boolean 是旧口径（`true` = `'line'`），字符串 / 数组用来选画法，数组可叠加，
+ * 例如 `['line', 'hull']` = 折边线 + 外扩轮廓同时上。
+ * 注意 `'offset'` 隐含折边线：外推是折边线的修饰，不是另一种线。
+ */
+export type EdgesOption = boolean | EdgeStyle | EdgeStyle[];
+
+/** 归一化后的棱线开关 */
+export interface EdgeModes {
+  /** 整体开关：任一画法命中就是 true */
+  enabled: boolean;
+  /** 是否建 CPU 折边线 */
+  line: boolean;
+  /** 折边线是否沿边法线外推 */
+  offset: boolean;
+  /** 是否挂背面外扩轮廓 */
+  hull: boolean;
+  /** 是否在材质里做片元级描边（零几何） */
+  gpu: boolean;
+}
+
+const EDGE_MODE_OFF: EdgeModes = { enabled: false, line: false, offset: false, hull: false, gpu: false };
+
+/**
+ * 把 `EdgesOption` 归一成四个开关。
+ *
+ * 未知值（宿主 JS 里传错字符串 / 脏数组）一律当关，不抛错也不误开——样式这种东西
+ * 出错时最该做的是「保持不动」，而不是把整个图层带崩。
+ */
+export function resolveEdgeModes(value: EdgesOption | null | undefined): EdgeModes {
+  if (value == null || value === false) return { ...EDGE_MODE_OFF };
+  if (value === true) return { ...EDGE_MODE_OFF, enabled: true, line: true };
+
+  const list = Array.isArray(value) ? value : [value];
+  const modes: EdgeModes = { ...EDGE_MODE_OFF };
+  for (const item of list) {
+    if (item === 'line') modes.line = true;
+    else if (item === 'offset') {
+      modes.line = true;
+      modes.offset = true;
+    } else if (item === 'hull') modes.hull = true;
+    else if (item === 'gpu') modes.gpu = true;
+  }
+  modes.enabled = modes.line || modes.hull || modes.gpu;
+  return modes;
+}
+
+/** 两套开关是否等价（只比较有效位，用来判断要不要重建装饰） */
+export function sameEdgeModes(a: EdgeModes, b: EdgeModes): boolean {
+  return a.line === b.line && a.offset === b.offset && a.hull === b.hull && a.gpu === b.gpu;
+}
+
 /* ------------------------------------------------------------------ 样式配置 */
 
 /** 图层整体样式（宿主无关，S3MViewer 与 s3m-maplibre 的 S3MLayer 共用） */
@@ -105,14 +174,31 @@ export interface S3MStyle {
   outlineWidth?: number;
   /** 选中棱线的粗细（像素，默认 3，仅 outlineStyle: 'edges' 生效，缩放时保持恒定） */
   outlineWidthPx?: number;
-  /** 是否显示几何棱线（CPU 端生成，有开销） */
-  edges: boolean;
+  /**
+   * 是否显示几何棱线。
+   *
+   * 取值是 `boolean | EdgeStyle | EdgeStyle[]`：`true` 等价于 `'line'`（旧口径），
+   * `'hull'` 走背面外扩轮廓，`'offset'` 是折边线 + 法线外推，数组可叠加。
+   * 见 `resolveEdgeModes`。
+   */
+  edges: EdgesOption;
   /** 全局棱线粗细（像素，默认 1.2） */
   edgeWidth?: number;
   edgeColor: string;
   edgeOpacity?: number;
   /** 棱线临界角（度）：相邻面法线夹角超过该值才描边，过滤掉浅坡与曲面细分。默认 55° */
   edgeThreshold?: number;
+  /** 折边线沿边法线外推的距离（米，默认 0.15，仅 edges 含 'offset' 生效） */
+  edgeOffset?: number;
+  /** 背面外扩轮廓的厚度（米，默认 0.9，仅 edges 含 'hull' 生效） */
+  edgeHullWidth?: number;
+  /**
+   * 忽略数据自带的棱线包（primitiveType 13），一律 CPU 现算。默认 false。
+   *
+   * 数据自带的棱线是 `LineBasicMaterial`，线宽恒 1px，`edgeWidth` / 外扩 / 单体跟随
+   * 全都吃不上。想让这些能力对所有数据统一生效就打开它，代价是 CPU 要现算折边。
+   */
+  forceCpuEdges?: boolean;
   roofThreshold?: number;
   /** 是否与模型原色贴图叠加混合（0 = 纯色覆盖，1 = 叠乘原色贴图） */
   texMix?: number;
@@ -161,6 +247,9 @@ export const DEFAULT_STYLE: S3MStyle = {
   edgeColor: '#334155',
   edgeOpacity: 0.6,
   edgeThreshold: 55,
+  edgeOffset: 0.15,
+  edgeHullWidth: 0.9,
+  forceCpuEdges: false,
   roofThreshold: 0.65,
   texMix: 0,
   ambientGain: 0,
@@ -286,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 */ `
@@ -322,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;
@@ -487,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 */ `
@@ -595,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 );
@@ -796,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;
@@ -809,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，
@@ -820,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,
@@ -841,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 };
@@ -861,6 +995,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     Object.assign(shader.uniforms, uniforms, {
       uSelBatch,
       uSelWhole,
+      uFlatShading,
       uBatchTex,
       uBatchTex2,
       uBatchTexWidth,
@@ -898,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 可复用；
@@ -920,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;
 }
@@ -1029,18 +1174,34 @@ const OUTLINE_VERT = /* glsl */ `
 
 const OUTLINE_FRAG = /* glsl */ `
   uniform vec3 uColor;
+  uniform float uOpacity;
   varying float vSel;
   void main() {
     if ( vSel < 0.5 ) discard;
-    gl_FragColor = vec4( uColor, 1.0 );
+    if ( uOpacity <= 0.003 ) discard;
+    gl_FragColor = vec4( uColor, uOpacity );
   }
 `;
 
+/**
+ * 外扩轮廓的「外观」uniform。
+ *
+ * 与棱线一样，全局外扩是逐网格一份材质（要各绑各的单体状态纹理），但颜色 / 厚度 /
+ * 不透明度必须全局统一 —— 所以这些 `{ value }` 对象由调用方持有并共享给每一份材质，
+ * 改一次全场景生效。
+ */
+export interface OutlineStyleUniforms {
+  uColor: { value: THREE.Color };
+  uWidth: { value: number };
+  uOpacity: { value: number };
+}
+
 export interface OutlineMaterial extends THREE.ShaderMaterial {
   uniforms: {
     uSelBatch: { value: number };
     uSelWhole: { value: number };
     uWidth: { value: number };
+    uOpacity: { value: number };
     uElevation: { value: number };
     uBatchTex: { value: THREE.Texture };
     uBatchTex2: { value: THREE.Texture };
@@ -1055,13 +1216,34 @@ export interface OutlineMaterial extends THREE.ShaderMaterial {
   };
 }
 
-/** 选中单体的描边材质（背面外扩法） */
-export function createOutlineMaterial(shared: StyleUniforms, initialWidth = 0.9): OutlineMaterial {
+/**
+ * 描边材质（背面外扩法）。
+ *
+ * 选中侧与全局棱线共用这一份实现，差别只在 uniform：
+ *   - 选中：`uSelBatch` = 选中单体的 batchId，只扩那一栋，不透明
+ *   - 全局：`uSelWhole` = 1，整块几何都扩，走 `edgeOpacity` 混合
+ *
+ * @param styleUniforms 传入时**直接复用这些 `{ value }` 对象**，让逐网格材质共享外观
+ * @param transparent   全局外扩要能吃 `edgeOpacity`，选中侧保持不透明（默认 false）
+ */
+export function createOutlineMaterial(
+  shared: StyleUniforms,
+  initialWidth = 0.9,
+  styleUniforms?: OutlineStyleUniforms,
+  transparent = false
+): OutlineMaterial {
+  const style: OutlineStyleUniforms = styleUniforms ?? {
+    uColor: { value: shared.uSelColor.value.clone() },
+    uWidth: { value: initialWidth },
+    uOpacity: { value: 1 },
+  };
+
   const mat = new THREE.ShaderMaterial({
     uniforms: {
       uSelBatch: { value: -1 },
       uSelWhole: { value: 0 },
-      uWidth: { value: initialWidth },
+      uWidth: style.uWidth,
+      uOpacity: style.uOpacity,
       uElevation: { value: 0 },
       uBatchTex: { value: DUMMY_BATCH_TEX },
       uBatchTex2: { value: DUMMY_BATCH_TEX },
@@ -1072,13 +1254,13 @@ export function createOutlineMaterial(shared: StyleUniforms, initialWidth = 0.9)
       uPathCount: shared.uPathCount ?? { value: 1 },
       uPathTexActive: shared.uPathTexActive ?? { value: 0 },
       uPathTime: shared.uPathTime ?? { value: 0 },
-      uColor: { value: shared.uSelColor.value.clone() },
+      uColor: style.uColor,
     },
     vertexShader: OUTLINE_VERT,
     fragmentShader: OUTLINE_FRAG,
     side: THREE.BackSide,
     depthWrite: false,
-    transparent: false,
+    transparent,
     // 描边要压在建筑后面一点，避免和本体 z-fighting
     polygonOffset: true,
     polygonOffsetFactor: 1,

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;