s3m-three 0.3.10 → 0.3.12

package/dist/render/S3MViewer.js

@@ -49,6 +49,19 @@ function styledMaterialOf(mesh) {
 function isPointCloudObject(o) {
     return o.isPoints === true;
 }
+/**
+ * 全局透明度钳到 [0, 1]，**允许到 0**。
+ *
+ * 以前这里有个 0.05 下限，本意是「别让整层彻底看不见、又还在挡东西」。但那个问题
+ * 真正的来源不是透明度，而是「透明物体仍然写深度」：全透明还写深度就会在底图上挖洞。
+ * 现在到 0 时 `renderFrame()` 直接跳过绘制（不写颜色也不写深度），语义就干净了。
+ */
+function clampOpacity(v) {
+    const n = v ?? 1;
+    return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+/** 低于这个透明度就当作完全不可见：跳过绘制，避免全透明物体写深度 */
+const OPACITY_EPS = 1e-3;
 /* ------------------------------------------------------------------ 可动画的样式键 */
 /**
  * 能逐帧插值的标量样式键。
@@ -147,10 +160,18 @@ export class S3MViewer {
     _tileFadeSeq = 0;
     /** setMode 编排的代次，用来作废被新调用顶掉的旧编排 */
     _modeGen = 0;
+    /** `shading` 另一种变体是否已预热（每个 viewer 只做一次） */
+    _shadingPrewarmed = false;
+    /** 是否允许自动预热（选项 `prewarmShading`，默认开） */
+    _prewarmShadingEnabled = true;
+    /** 预热进行中：期间跳过渲染，避免把「翻转后的变体」画到屏幕上 */
+    _prewarming = false;
     /** 路径运动的规格表：通道 key → 路径 + 偏移 */
     _pathSpecs = new Map();
     /** 路径采样临时对象，避免每帧 new */
     _pathScratch = new Float32Array(3);
+    /** 求切线用的第二个采样点（包围盒换算 GPU 路径朝向时用） */
+    _pathScratch2 = new Float32Array(3);
     /** 预制棱线缓存（Crease Cache）：从外部 source-creases 载入的全局统一 LineSegments，性能最高、视觉最干净 */
     _creaseLines = null;
     /** 数据自带的棱线对象（LineSegments），改棱线颜色时只刷这些，不再全场景 traverse */
@@ -220,6 +241,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) {
             this.scene = new THREE.Scene();
@@ -264,6 +286,8 @@ export class S3MViewer {
         // `style: { edges: true }` 形同虚设、_edgesEnabled 永远是 false。
         // 这里按 style 实际值调一次 setEdges，让开关真正生效（与 setEdges 后来的手工调用一致）。
         this.setEdges(!!this.style.edges);
+        // 初始化图层整体不透明度：确保共享 uniform uOpacity、材质混合开关与棱线外观与初始 style.opacity 严格一致
+        this._applyOpacity();
         this._fps.last = performance.now();
         this._datasetQueue = this._normalizeDatasets(options);
         if (options.attributes)
@@ -329,7 +353,7 @@ export class S3MViewer {
         }
         try {
             // 旧上下文已失效，dispose 可能抛错，忽略即可
-            this.renderer?.dispose();
+            this.renderer?.dispose?.();
         }
         catch {
             /* noop */
@@ -369,7 +393,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;
     }
@@ -774,6 +798,54 @@ export class S3MViewer {
         this.animator.unregister(key);
         this._pathSpecs.delete(key);
     }
+    /**
+     * 换算 GPU 路径单体在**当前时间**的位置与朝向。
+     *
+     * 位移发生在顶点着色器里，JS 侧要拿到「屏幕上现在在哪」只能按同一套公式在 CPU 复算：
+     * `t = phase + uPathTime * speed`，再按 loop 模式夹到 0~1，最后查弧长表。
+     * 与 StyleMaterial 的 row5 分支逐行对应，改那边时这里必须同步。
+     */
+    _gpuPathPoseAt(smid) {
+        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 = [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 实例
@@ -1262,10 +1334,11 @@ 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;
-                    mat.depthWrite = 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;
                     this._featureStyleManager.applyOverridesToMesh(mesh);
@@ -1318,8 +1391,7 @@ export class S3MViewer {
                 // 淡入期间强制开了 transparent + depthWrite，结束时不能自己拍板关掉——
                 // 图层可能本来就半透明、单体也可能还有淡化。交给淡化流程重新裁决一次。
                 this._featureStyleManager.applyOverridesToMesh(mesh);
-                if (!mat.transparent)
-                    mat.depthWrite = true;
+                mat.depthWrite = this.style.depthWrite !== false;
                 this._requestRepaint();
             },
         });
@@ -1689,6 +1761,9 @@ export class S3MViewer {
         if (u.uAmbientGain && s.ambientGain != null) {
             u.uAmbientGain.value = s.ambientGain;
         }
+        if (u.uOpacity && s.opacity != null) {
+            u.uOpacity.value = clampOpacity(s.opacity);
+        }
         if (this.outlineMaterial) {
             if (this.outlineMaterial.uniforms.uElevation && s.selectElevation != null) {
                 this.outlineMaterial.uniforms.uElevation.value = s.selectElevation;
@@ -1713,7 +1788,7 @@ export class S3MViewer {
      * 现在逐帧只写一个 float（`uOpacity`），混合开关只在**真正跨过阈值**时切一次。
      */
     _applyOpacity() {
-        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;
@@ -1764,6 +1839,62 @@ export class S3MViewer {
         }
         this._requestRepaint();
     }
+    /**
+     * 预热另一种 `shading` 变体，让首次切换不再同步编译着色器。
+     *
+     * 做法是「把材质翻到另一种变体 → 编译 → 翻回来」：three 的 program 缓存按
+     * cacheKey（含 flatShading / defines）分桶，编译一次就留在缓存里，之后
+     * `_applyShading()` 切过去只是取缓存。
+     *
+     * 翻转期间材质是「错误变体」，所以用 `_prewarming` 让 renderFrame 跳过渲染——
+     * 少画一两帧看不出来，把平滑的楼画成平面的就很明显。
+     * 优先用 `compileAsync`（KHR_parallel_shader_compile），没有就退回同步 `compile`。
+     */
+    async prewarmShading() {
+        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 = [];
+        const seen = new Set();
+        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;
+            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();
+        }
+    }
     /**
      * 高度范围增量维护。
      *
@@ -1971,7 +2102,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);
@@ -2003,7 +2134,7 @@ export class S3MViewer {
         const s = this.style;
         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);
@@ -2025,7 +2156,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;
@@ -2560,13 +2691,30 @@ export class S3MViewer {
                     rotM3 = new THREE.Matrix3().set(rotMat[0], rotMat[1], rotMat[2], rotMat[3], rotMat[4], rotMat[5], rotMat[6], rotMat[7], rotMat[8]);
                     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 = 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;
                     const [lng, lat] = this._lngLatFromWorld(c.x * s + this.sceneAnchor.x, -c.y * s + this.sceneAnchor.y);
@@ -2804,7 +2952,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)
@@ -2894,6 +3042,10 @@ export class S3MViewer {
         const gl = this.renderer.getContext();
         if (gl && typeof gl.isContextLost === 'function' && gl.isContextLost())
             return false;
+        // shading 预热期间材质是「另一种变体」，这一帧先不画：少画一两帧看不出来，
+        // 把平滑的楼画成平面的一眼就能看出来。
+        if (this._prewarming)
+            return true;
         // 先推进动画，再刷脏标记，最后渲染 —— 保证本帧画出来的是最新值
         const animating = this.animator.tick();
         // 脏标记正常由微任务刷掉；这里再兜一次底，保证「本帧画出来的」一定是最新样式
@@ -2944,7 +3096,11 @@ export class S3MViewer {
         this._updateLineResolution(canvas);
         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();
         if (now - this._fps.last > 500) {
@@ -2954,11 +3110,16 @@ export class S3MViewer {
         }
         // 动态着色 / 动画进行中 / 瓦片加载中 / 瓦片层级或可见性改变，都需要宿主继续驱动下一帧。
         // 动画结束那一帧必须精确回到 false，否则 MapLibre 会永远重绘（耗电、发热）。
-        return (animating ||
+        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;
     }
     /* ---------------------------------------------------------------- 只读属性 */
     get fps() {