s3m-three 0.3.11 → 0.3.13

package/src/render/Picker.ts

@@ -25,13 +25,26 @@ const PICK_VERT = /* glsl */ `
   #endif
   uniform float uObjectId;
   uniform sampler2D uBatchTex;
+  uniform sampler2D uBatchTex2;
+  uniform float uBatchMix;
   uniform float uBatchTexWidth;
   uniform int uBatchTexActive;
+  uniform sampler2D uPathTex;
+  uniform float uPathCount;
+  uniform float uPathTime;
+  uniform int uPathTexActive;
   uniform float uSelBatch;
   uniform float uSelWhole;
   uniform float uSelElevation;
   varying float vBatch;
 
+  /** 交叉淡化期间也要读「屏幕上正在显示的那份」，否则过渡中点到的是旧位置 */
+  vec4 s3mPickSample( vec2 uv ) {
+    vec4 a = texture2D( uBatchTex, uv );
+    if ( uBatchMix <= 0.0001 ) return a;
+    return mix( a, texture2D( uBatchTex2, uv ), uBatchMix );
+  }
+
   void main() {
     float s3mBatch;
     #ifdef USE_INSTANCING
@@ -43,22 +56,82 @@ const PICK_VERT = /* glsl */ `
       vBatch = aBatchId;
     #endif
 
-    // 单体状态（平移 / 隐藏）必须和主着色器用同一份数据、同一套算法：
-    // 平移只发生在顶点着色器里，拾取这一趟如果还按原始坐标画，移位的楼就点不中。
+    // 单体状态必须和主着色器用同一份数据、同一套算法：位移 / 旋转 / 隐藏 / GPU 路径
+    // 全都只发生在顶点着色器里，拾取这一趟如果还按原始坐标画，动过的楼就点不中。
+    // 状态纹理共 6 行，行序与 StyleMaterial 的 VERT_SETUP 严格一一对应。
     vec3 p = position;
+    mat3 rot = mat3( 1.0 );
+    vec3 pivot = vec3( 0.0 );
+    vec3 offset = vec3( 0.0 );
+    bool hidden = false;
+
     if ( uBatchTexActive > 0 && s3mBatch >= 0.0 ) {
-      vec4 state = texture2D( uBatchTex, vec2( ( s3mBatch + 0.5 ) / uBatchTexWidth, 0.25 ) );
+      float u = ( s3mBatch + 0.5 ) / uBatchTexWidth;
+      // Row 0：rgb = 配色，a = 抬高 / < -0.5 表示隐藏
+      vec4 state = s3mPickSample( vec2( u, 0.08333333 ) );
       if ( state.a < -0.5 ) {
-        p = vec3( 0.0 );
+        hidden = true;
       } else {
-        vec4 offset = texture2D( uBatchTex, vec2( ( s3mBatch + 0.5 ) / uBatchTexWidth, 0.75 ) );
-        p += offset.xyz;
-        if ( offset.z == 0.0 && state.a > 0.0 ) {
-          p.z += state.a;
+        // Row 1：平移（z 已包含抬高）
+        vec4 r1 = s3mPickSample( vec2( u, 0.25 ) );
+        offset = r1.xyz;
+        if ( offset.z == 0.0 && state.a > 0.0 ) offset.z = state.a;
+
+        // Row 2/3/4：3x3 姿态矩阵（列优先）+ 轴心
+        vec4 r2 = s3mPickSample( vec2( u, 0.41666667 ) );
+        vec4 r3 = s3mPickSample( vec2( u, 0.58333333 ) );
+        vec4 r4 = s3mPickSample( vec2( u, 0.75 ) );
+        rot = mat3(
+          vec3( r2.x, r3.x, r4.x ),
+          vec3( r2.y, r3.y, r4.y ),
+          vec3( r2.z, r3.z, r4.z )
+        );
+        pivot = vec3( r2.w, r3.w, r4.w );
+
+        // Row 5：GPU 路径动画，与主着色器逐行对齐（含 loop / pingpong / clamp 与自动朝向）
+        if ( uPathTexActive > 0 && uPathCount > 0.0 ) {
+          vec4 r5 = s3mPickSample( vec2( u, 0.91666667 ) );
+          float pathId = r5.x;
+          float speed = r5.y;
+          float phase = r5.z;
+          float mode = r5.w;
+          if ( pathId >= 0.0 && mode > 0.5 ) {
+            float t = phase + uPathTime * speed;
+            bool autoHeading = true;
+            if ( mode >= 4.0 ) {
+              autoHeading = false;
+              mode -= 3.0;
+            }
+            if ( mode < 1.5 ) {
+              t = fract( t );
+            } else if ( mode < 2.5 ) {
+              t = clamp( t, 0.0, 1.0 );
+            } else {
+              t = mod( t, 2.0 );
+              t = ( t > 1.0 ) ? ( 2.0 - t ) : t;
+            }
+            vec4 pathSample = texture2D(
+              uPathTex,
+              vec2( ( t * 255.0 + 0.5 ) / 256.0, ( pathId + 0.5 ) / uPathCount )
+            );
+            if ( autoHeading ) {
+              float c = cos( pathSample.w );
+              float s = sin( pathSample.w );
+              // 列优先：(c, s) 是第 0 列 → 绕 Z 转 +yaw，与 StyleMaterial / EdgeLines 逐位一致
+              rot = mat3( c, s, 0.0, -s, c, 0.0, 0.0, 0.0, 1.0 ) * rot;
+            }
+            offset += pathSample.xyz;
+          }
         }
       }
     }
 
+    if ( hidden ) {
+      p = vec3( 0.0 );
+    } else {
+      p = rot * ( p - pivot ) + pivot + offset;
+    }
+
     // 选中单体自身的拔高（selectElevation）
     float sel = max( step( 0.0, uSelBatch ) * step( abs( s3mBatch - uSelBatch ), 0.5 ), uSelWhole );
     p.z += sel * uSelElevation;
@@ -114,13 +187,28 @@ const DUMMY_STATE_TEX = (() => {
   return tex;
 })();
 
+/** 没有 GPU 路径库时用的占位（1x1 全 0，采样出来 pathId = 0 但 uPathTexActive = 0 会跳过） */
+const DUMMY_PATH_TEX = (() => {
+  const tex = new THREE.DataTexture(new Float32Array([0, 0, 0, 0]), 1, 1, THREE.RGBAFormat, THREE.FloatType);
+  tex.minFilter = THREE.NearestFilter;
+  tex.magFilter = THREE.NearestFilter;
+  tex.needsUpdate = true;
+  return tex;
+})();
+
 function createPickMaterial(objectId: number): THREE.ShaderMaterial {
   return new THREE.ShaderMaterial({
     uniforms: {
       uObjectId: { value: objectId },
       uBatchTex: { value: DUMMY_STATE_TEX },
+      uBatchTex2: { value: DUMMY_STATE_TEX },
+      uBatchMix: { value: 0 },
       uBatchTexWidth: { value: 1 },
       uBatchTexActive: { value: 0 },
+      uPathTex: { value: DUMMY_PATH_TEX },
+      uPathCount: { value: 1 },
+      uPathTime: { value: 0 },
+      uPathTexActive: { value: 0 },
       uSelBatch: { value: -1 },
       uSelWhole: { value: 0 },
       uSelElevation: { value: 0 },
@@ -214,29 +302,40 @@ export class Picker {
       if (!ud.pickMaterial) ud.pickMaterial = createPickMaterial(ud.pickId);
       if ((mesh as THREE.InstancedMesh).isInstancedMesh) instancedPickIds.add(ud.pickId);
 
-      // 把当前的「单体状态纹理」抄给拾取材质：抬高量是逐单体写在里面的，
-      // 抄的是同一个纹理对象，主材质那边更新后这里自动跟着变。
+      // 把当前的「单体状态纹理」抄给拾取材质：抬高 / 平移 / 姿态 / GPU 路径都是逐单体
+      // 写在里面的，抄的是同一个纹理与同一批 uniform 对象，主材质那边更新后这里自动跟着变。
       const prev = mesh.material;
       const pm = ud.pickMaterial as THREE.ShaderMaterial;
       const src = (Array.isArray(prev) ? prev[0] : prev) as THREE.Material & {
         userData?: Record<string, THREE.IUniform>;
+        uniforms?: Record<string, THREE.IUniform>;
       };
       const batchTex = src?.userData?.uBatchTex;
       if (batchTex) {
         pm.uniforms.uBatchTex.value = batchTex.value;
+        pm.uniforms.uBatchTex2.value = src?.userData?.uBatchTex2?.value ?? batchTex.value;
         pm.uniforms.uBatchTexWidth.value = (src?.userData?.uBatchTexWidth?.value as number) ?? 1;
         pm.uniforms.uBatchTexActive.value = (src?.userData?.uBatchTexActive?.value as number) ?? 0;
       } else {
         pm.uniforms.uBatchTex.value = DUMMY_STATE_TEX;
+        pm.uniforms.uBatchTex2.value = DUMMY_STATE_TEX;
         pm.uniforms.uBatchTexWidth.value = 1;
         pm.uniforms.uBatchTexActive.value = 0;
       }
+      // 交叉淡化与 GPU 路径的 uniform 是共享对象（挂在材质 userData 上），
+      // 抄引用即可，不需要每帧同步数值
+      pm.uniforms.uBatchMix.value = (src?.userData?.uBatchMix?.value as number) ?? 0;
+      pm.uniforms.uPathTex.value = src?.userData?.uPathTex?.value ?? DUMMY_PATH_TEX;
+      pm.uniforms.uPathCount.value = (src?.userData?.uPathCount?.value as number) ?? 1;
+      pm.uniforms.uPathTime.value = (src?.userData?.uPathTime?.value as number) ?? 0;
+      pm.uniforms.uPathTexActive.value = (src?.userData?.uPathTexActive?.value as number) ?? 0;
       // 选中那栋自身的拔高也要算，否则选中后再点它会点空
       pm.uniforms.uSelBatch.value = (src?.userData?.uSelBatch?.value as number) ?? -1;
       pm.uniforms.uSelWhole.value = (src?.userData?.uSelWhole?.value as number) ?? 0;
-      // uSelElevation 是共享 uniform，挂在材质 uniforms 上而不是 userData
       pm.uniforms.uSelElevation.value =
-        ((src as THREE.ShaderMaterial | undefined)?.uniforms?.uSelElevation?.value as number) ?? 0;
+        (src?.userData?.uSelElevation?.value as number) ??
+        (src?.uniforms?.uSelElevation?.value as number) ??
+        0;
 
       swapped.push([mesh, prev]);
       mesh.material = pm;

package/src/render/S3MViewer.ts

@@ -234,6 +234,13 @@ export interface S3MViewerOptions {
   onReady?: (entry: S3MDatasetEntry) => void;
   onPick?: (result: PickResult | null) => void;
   onError?: (error: unknown) => void;
+  /**
+   * 首次出现瓦片后自动预热另一种 `shading` 变体（默认开）。
+   *
+   * `flat` / `smooth` 是编译期变体，不预热的话第一次 `setStyle({ shading })` 会同步
+   * 编译着色器、卡一帧。预热在首帧之后异步做，期间跳一两帧渲染，肉眼不可见。
+   */
+  prewarmShading?: boolean;
 }
 
 /* ------------------------------------------------------------------ 内部类型 */
@@ -281,6 +288,21 @@ function isPointCloudObject(o: THREE.Object3D): o is THREE.Points {
   return (o as unknown as THREE.Points).isPoints === true;
 }
 
+/**
+ * 全局透明度钳到 [0, 1]，**允许到 0**。
+ *
+ * 以前这里有个 0.05 下限，本意是「别让整层彻底看不见、又还在挡东西」。但那个问题
+ * 真正的来源不是透明度，而是「透明物体仍然写深度」：全透明还写深度就会在底图上挖洞。
+ * 现在到 0 时 `renderFrame()` 直接跳过绘制（不写颜色也不写深度），语义就干净了。
+ */
+function clampOpacity(v: number | null | undefined): number {
+  const n = v ?? 1;
+  return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+
+/** 低于这个透明度就当作完全不可见：跳过绘制，避免全透明物体写深度 */
+const OPACITY_EPS = 1e-3;
+
 /* ------------------------------------------------------------------ 可动画的样式键 */
 
 /**
@@ -410,10 +432,18 @@ export class S3MViewer {
   private _tileFadeSeq = 0;
   /** setMode 编排的代次，用来作废被新调用顶掉的旧编排 */
   private _modeGen = 0;
+  /** `shading` 另一种变体是否已预热（每个 viewer 只做一次） */
+  private _shadingPrewarmed = false;
+  /** 是否允许自动预热（选项 `prewarmShading`，默认开） */
+  private _prewarmShadingEnabled = true;
+  /** 预热进行中：期间跳过渲染，避免把「翻转后的变体」画到屏幕上 */
+  private _prewarming = false;
   /** 路径运动的规格表：通道 key → 路径 + 偏移 */
   private readonly _pathSpecs = new Map<string, { path: Path; offset: [number, number, number] }>();
   /** 路径采样临时对象，避免每帧 new */
   private readonly _pathScratch = new Float32Array(3);
+  /** 求切线用的第二个采样点（包围盒换算 GPU 路径朝向时用） */
+  private readonly _pathScratch2 = new Float32Array(3);
   /** 预制棱线缓存（Crease Cache）：从外部 source-creases 载入的全局统一 LineSegments，性能最高、视觉最干净 */
   private _creaseLines: THREE.LineSegments | null = null;
   /** 数据自带的棱线对象（LineSegments），改棱线颜色时只刷这些，不再全场景 traverse */
@@ -491,6 +521,7 @@ export class S3MViewer {
     this.onReady = options.onReady ?? (() => {});
     this.onPick = options.onPick ?? (() => {});
     this.onError = options.onError ?? ((e) => console.warn('[s3m]', e));
+    this._prewarmShadingEnabled = options.prewarmShading !== false;
 
     this.groundManager = new GroundManager(options.ground);
     if (!this.scene) {
@@ -621,7 +652,7 @@ export class S3MViewer {
     }
     try {
       // 旧上下文已失效，dispose 可能抛错，忽略即可
-      this.renderer?.dispose();
+      this.renderer?.dispose?.();
     } catch {
       /* noop */
     }
@@ -660,7 +691,7 @@ export class S3MViewer {
     this._pathSpecs.clear();
     this._heightMin = Infinity;
     this._heightMax = -Infinity;
-    this.renderer?.dispose();
+    this.renderer?.dispose?.();
     this.renderer = null;
     this.canvas = null;
   }
@@ -1141,6 +1172,52 @@ export class S3MViewer {
     this._pathSpecs.delete(key);
   }
 
+  /**
+   * 换算 GPU 路径单体在**当前时间**的位置与朝向。
+   *
+   * 位移发生在顶点着色器里，JS 侧要拿到「屏幕上现在在哪」只能按同一套公式在 CPU 复算：
+   * `t = phase + uPathTime * speed`，再按 loop 模式夹到 0~1，最后查弧长表。
+   * 与 StyleMaterial 的 row5 分支逐行对应，改那边时这里必须同步。
+   */
+  private _gpuPathPoseAt(smid: number): { pos: [number, number, number]; yaw: number } | null {
+    const gp = this._featureStyleManager.getFeatureStyle(smid)?.gpuPath;
+    if (!gp) return null;
+    const path = this.gpuPathManager.getPath(gp.pathId);
+    if (!path || path.length <= 0) return null;
+
+    const time = this.uniforms.uPathTime?.value ?? 0;
+    let t = (gp.phase ?? 0) + time * (gp.speed ?? 0);
+    const loop = gp.loop;
+    if (loop === 'clamp' || loop === false) {
+      t = Math.min(1, Math.max(0, t));
+    } else if (loop === 'pingpong') {
+      t = t % 2;
+      if (t < 0) t += 2;
+      t = t > 1 ? 2 - t : t;
+    } else {
+      t = t - Math.floor(t);
+    }
+
+    path.sampleAt(t, this._pathScratch);
+    const pos: [number, number, number] = [this._pathScratch[0], this._pathScratch[1], this._pathScratch[2]];
+
+    let yaw = 0;
+    if (gp.autoHeading !== false) {
+      const d = 1e-3;
+      path.sampleAt(Math.min(1, t + d), this._pathScratch2);
+      let dx = this._pathScratch2[0] - pos[0];
+      let dy = this._pathScratch2[1] - pos[1];
+      if (dx * dx + dy * dy < 1e-8) {
+        // 已经在终点：退回用「后一点减前一点」求切线
+        path.sampleAt(Math.max(0, t - d), this._pathScratch2);
+        dx = pos[0] - this._pathScratch2[0];
+        dy = pos[1] - this._pathScratch2[1];
+      }
+      if (dx * dx + dy * dy >= 1e-8) yaw = Math.atan2(dy, dx);
+    }
+    return { pos, yaw };
+  }
+
   /**
    * 注册 GPU 路径到路径库
    * @param points 折线点数组或 Path 实例
@@ -1679,7 +1756,7 @@ export class S3MViewer {
       } else {
         const mat = styledMaterialOf(mesh);
         if (mat) {
-          const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
+          const o = clampOpacity(this.style.opacity);
           // 不写 mat.opacity：全局透明度走共享 uOpacity，材质自身 opacity 保留模型自带 alpha
           mat.transparent = o < 0.999;
           const keepDepth = this.style.depthWrite !== false;
@@ -2110,7 +2187,7 @@ export class S3MViewer {
       u.uAmbientGain.value = s.ambientGain;
     }
     if (u.uOpacity && s.opacity != null) {
-      u.uOpacity.value = Math.min(1, Math.max(0.05, s.opacity));
+      u.uOpacity.value = clampOpacity(s.opacity);
     }
     if (this.outlineMaterial) {
       if (this.outlineMaterial.uniforms.uElevation && s.selectElevation != null) {
@@ -2135,7 +2212,7 @@ export class S3MViewer {
    * 现在逐帧只写一个 float（`uOpacity`），混合开关只在**真正跨过阈值**时切一次。
    */
   private _applyOpacity(): void {
-    const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
+    const o = clampOpacity(this.style.opacity);
     if (this.uniforms.uOpacity) this.uniforms.uOpacity.value = o;
 
     const transparent = o < 0.999;
@@ -2185,6 +2262,59 @@ export class S3MViewer {
     this._requestRepaint();
   }
 
+  /**
+   * 预热另一种 `shading` 变体，让首次切换不再同步编译着色器。
+   *
+   * 做法是「把材质翻到另一种变体 → 编译 → 翻回来」：three 的 program 缓存按
+   * cacheKey（含 flatShading / defines）分桶，编译一次就留在缓存里，之后
+   * `_applyShading()` 切过去只是取缓存。
+   *
+   * 翻转期间材质是「错误变体」，所以用 `_prewarming` 让 renderFrame 跳过渲染——
+   * 少画一两帧看不出来，把平滑的楼画成平面的就很明显。
+   * 优先用 `compileAsync`（KHR_parallel_shader_compile），没有就退回同步 `compile`。
+   */
+  async prewarmShading(): Promise<void> {
+    if (this._shadingPrewarmed || this._prewarming) return;
+    const r = this.renderer;
+    const scene = this.scene;
+    const camera = this.camera;
+    if (!r || !scene || !camera) return;
+
+    const mats: THREE.MeshStandardMaterial[] = [];
+    const seen = new Set<THREE.Material>();
+    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 (mats.length === 0) 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>;
+      };
+      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();
+    }
+  }
+
   /**
    * 高度范围增量维护。
    *
@@ -2381,7 +2511,7 @@ export class S3MViewer {
     const mat = new THREE.LineBasicMaterial({
       color: new THREE.Color(s.edgeColor),
       transparent: true,
-      opacity: Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) * Math.min(1, Math.max(0.05, s.opacity ?? 1)),
+      opacity: Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) * clampOpacity(s.opacity),
       depthWrite: false,
     });
     const lines = new THREE.LineSegments(geo, mat);
@@ -2416,7 +2546,7 @@ export class S3MViewer {
     const fade = this.uniforms.uEdgeFade?.value ?? 1;
     const opacity =
       Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) *
-      Math.min(1, Math.max(0.05, s.opacity ?? 1)) *
+      clampOpacity(s.opacity) *
       fade;
     const u = this.edgeMaterial.uniforms;
     u.uColor.value.set(s.edgeColor);
@@ -2438,7 +2568,7 @@ export class S3MViewer {
     const baseOpacity = this.style.edgeOpacity ?? 0.6;
     mat.opacity =
       baseOpacity *
-      Math.min(1, Math.max(0.05, this.style.opacity ?? 1)) *
+      clampOpacity(this.style.opacity) *
       (this.uniforms.uEdgeFade?.value ?? 1);
     mat.transparent = true;
     mat.polygonOffset = true;
@@ -2997,10 +3127,27 @@ export class S3MViewer {
           rotPiv = off.pivot ? new THREE.Vector3(off.pivot[0], off.pivot[1], off.pivot[2]) : new THREE.Vector3(0, 0, 0);
         }
 
+        // GPU 路径：位移发生在顶点着色器里，包围盒要按同一套公式在 CPU 复算，
+        // 否则「运动中的车」的包围盒会停在路径原点（相机 fitBounds / 属性过滤都会错）。
+        const gpuPose = smid != null ? this._gpuPathPoseAt(smid) : null;
+        let headM3: THREE.Matrix3 | null = null;
+        if (gpuPose && gpuPose.yaw !== 0) {
+          const c = Math.cos(gpuPose.yaw);
+          const s = Math.sin(gpuPose.yaw);
+          // 与着色器的 mat3( c, s, 0, -s, c, 0, 0, 0, 1 ) 等价：GLSL 是列优先，
+          // three 的 Matrix3.set 是行优先，所以这里写成 (c, -s; s, c) 才是同一个矩阵。
+          headM3 = new THREE.Matrix3().set(c, -s, 0, s, c, 0, 0, 0, 1);
+        }
+
         for (const c of corners) {
           if (rotM3 && rotPiv) c.sub(rotPiv).applyMatrix3(rotM3).add(rotPiv);
+          if (headM3) {
+            const piv = rotPiv ?? new THREE.Vector3(0, 0, 0);
+            c.sub(piv).applyMatrix3(headM3).add(piv);
+          }
           if (trans) c.add(new THREE.Vector3(trans[0], trans[1], trans[2]));
           else if (elev) c.z += elev;
+          if (gpuPose) c.add(new THREE.Vector3(gpuPose.pos[0], gpuPose.pos[1], gpuPose.pos[2]));
 
           c.applyMatrix4(mesh.matrixWorld);
           const s = this.sceneAnchor.meterInMercator;
@@ -3243,7 +3390,7 @@ export class S3MViewer {
     const u = this.selectionEdgeMaterial.uniforms;
     u.uColor.value.set(s.outlineColor ?? s.selectColor);
     u.uWidth.value = Math.max(0.1, s.outlineWidthPx ?? 3);
-    u.uOpacity.value = Math.min(1, Math.max(0.05, s.opacity ?? 1));
+    u.uOpacity.value = clampOpacity(s.opacity);
     // 只加全局 selectElevation：单体自己的拔高已经写在状态纹理第 2 行 z 里，
     // 顶点着色器采样时带出来了，这里再加一次就会双重拔高
     if (u.uElevation) u.uElevation.value = s.selectElevation ?? 0;
@@ -3340,6 +3487,10 @@ export class S3MViewer {
     const gl = this.renderer.getContext() as WebGLRenderingContext | null;
     if (gl && typeof gl.isContextLost === 'function' && gl.isContextLost()) return false;
 
+    // shading 预热期间材质是「另一种变体」，这一帧先不画：少画一两帧看不出来，
+    // 把平滑的楼画成平面的一眼就能看出来。
+    if (this._prewarming) return true;
+
     // 先推进动画，再刷脏标记，最后渲染 —— 保证本帧画出来的是最新值
     const animating = this.animator.tick();
 
@@ -3407,7 +3558,11 @@ export class S3MViewer {
 
     this.renderer.setViewport(0, 0, canvas.width, canvas.height);
     this.renderer.resetState();
-    this.renderer.render(this.scene, this.camera);
+    // 完全透明时什么都不画：透明物体照样写深度，画了会在底图上挖出一个洞。
+    // 这里跳过的是「本层的绘制」，宿主自己的清屏 / 底图照旧。
+    if ((this.uniforms.uOpacity?.value ?? 1) > OPACITY_EPS) {
+      this.renderer.render(this.scene, this.camera);
+    }
 
     this._frame++;
     const now = performance.now();
@@ -3419,13 +3574,19 @@ export class S3MViewer {
 
     // 动态着色 / 动画进行中 / 瓦片加载中 / 瓦片层级或可见性改变，都需要宿主继续驱动下一帧。
     // 动画结束那一帧必须精确回到 false，否则 MapLibre 会永远重绘（耗电、发热）。
-    return (
+    const needsNextFrame =
       animating ||
       this.style.mode === STYLE.DYNAMIC ||
       gpuPathActive ||
       this.stats.loading > 0 ||
-      tilesetChanged
-    );
+      tilesetChanged;
+
+    // 首帧画完、场上有材质了，再把另一种 shading 变体编出来（异步，不挡当前帧）
+    if (this._prewarmShadingEnabled && !this._shadingPrewarmed && this._pickables.size > 0) {
+      void this.prewarmShading();
+    }
+
+    return needsNextFrame;
   }
 
   /* ---------------------------------------------------------------- 只读属性 */

package/src/render/StyleMaterial.ts

@@ -402,9 +402,12 @@ const VERT_SETUP = /* glsl */ `
           if ( autoHeading ) {
             float c = cos( pathYaw );
             float s = sin( pathYaw );
+
+            // GLSL 的 mat3 是列优先：下面两行是「第 0 列 = (c, s)」，等价于绕 Z 转 +yaw，
+            // 把模型 +X 朝向对到切线方向（yaw = atan2(dy, dx)）。写成 (c,-s; s,c) 会左右镜像。
             mat3 rotHeading = mat3(
-              c, -s, 0.0,
-              s,  c, 0.0,
+              c,  s, 0.0,
+              -s, c, 0.0,
               0.0, 0.0, 1.0
             );
             s3mRot = rotHeading * s3mRot;
@@ -869,6 +872,14 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
 
   mat.userData.uSelBatch = uSelBatch;
   mat.userData.uSelWhole = uSelWhole;
+  // 拾取材质要读这些共享 uniform 的当前值：挂引用而不是拷数值，主材质更新后拾取自动跟上
+  // （单测里可能不传共享 uniforms，这里按可选处理）
+  mat.userData.uSelElevation = uniforms?.uSelElevation;
+  mat.userData.uBatchMix = uniforms?.uBatchMix;
+  mat.userData.uPathTex = uniforms?.uPathTex;
+  mat.userData.uPathCount = uniforms?.uPathCount;
+  mat.userData.uPathTime = uniforms?.uPathTime;
+  mat.userData.uPathTexActive = uniforms?.uPathTexActive;
   mat.userData.uBatchTex = uBatchTex;
   mat.userData.uBatchTex2 = uBatchTex2;
   mat.userData.uBatchTexWidth = uBatchTexWidth;
@@ -959,9 +970,12 @@ const OUTLINE_VERT = /* glsl */ `
             if ( autoHeading ) {
               float c = cos( pathYaw );
               float s = sin( pathYaw );
+
+              // GLSL 的 mat3 是列优先：下面两行是「第 0 列 = (c, s)」，等价于绕 Z 转 +yaw，
+              // 把模型 +X 朝向对到切线方向（yaw = atan2(dy, dx)）。写成 (c,-s; s,c) 会左右镜像。
               mat3 rotHeading = mat3(
-                c, -s, 0.0,
-                s,  c, 0.0,
+                c,  s, 0.0,
+                -s, c, 0.0,
                 0.0, 0.0, 1.0
               );
               s3mRot = rotHeading * s3mRot;