s3m-three 0.4.21 → 0.4.23

package/dist/render/S3MViewer.js

@@ -23,8 +23,8 @@
 import * as THREE from 'three';
 import { usableGeoBounds } from '../tileset/S3MTileset.js';
 import { setSplatViewport } from './GeometryBuilder.js';
-import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap } from './TextureFactory.js';
-import { getMaterialQuality, setMaterialQuality } from './StyleMaterial.js';
+import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap, applyAnisotropyCap } from './TextureFactory.js';
+import { getMaterialQuality, normalizeMaterialQuality, getColorPipeline, normalizeColorPipeline } from './StyleMaterial.js';
 import { LightRig } from './viewer/LightRig.js';
 import { HeightIndex } from './viewer/HeightIndex.js';
 import { SplatLayer } from './viewer/SplatLayer.js';
@@ -91,6 +91,17 @@ const STYLE_SCALAR_KEYS = [
     'edgeHullWidth',
     'outlineWidth',
 ];
+/**
+ * 标量样式键在「用户还没设过」时的动画起点。
+ *
+ * 只对 `metalness` / `roughness` 有意义：它们的 uniform 默认是 -1（不覆盖，保持数据
+ * 自身的值），从 -1 插值没意义 —— 取数据侧常见值当起点，过渡才不会先跳到 0。
+ * 其余键缺省仍是 0（与旧行为一致）。
+ */
+const SCALAR_ANIM_START = {
+    metalness: 0, // S3M 数据的 metalness 恒为 0
+    roughness: 0.95, // shininess 映射后的常见值，见 GeometryBuilder 的 roughness
+};
 /** 能逐帧插值的颜色键（在线性空间插值，与 shader 消费端一致） */
 const STYLE_COLOR_KEYS = ['colorA', 'colorB', 'colorC', 'selectColor', 'edgeColor'];
 /** 可动画的单体属性 */
@@ -129,6 +140,25 @@ export class S3MViewer {
     groundManager;
     /** 多数据集生命周期与锚点管理器 */
     _datasetManager = new DatasetManager();
+    /**
+     * 本图层的光照模型档位。
+     *
+     * `undefined` = 没指定，跟随模块级默认（`getMaterialQuality()`）—— 老代码
+     * `setMaterialQuality('lambert')` 一行改全场的用法靠这条继续有效。
+     * 传了值就只认自己，多图层同页各用各的，互不覆盖。
+     */
+    _materialQuality;
+    /**
+     * 本图层的颜色管线。
+     *
+     * `undefined` = 没指定，跟随模块级默认（`getColorPipeline()`）。
+     * 与 materialQuality 同理：传了值就只认自己，同页多图层互不污染 —— 这条尤其重要，
+     * 因为 `lightingPreset: 'supermap'` 会同时改管线、纹理解码方式与各向异性，
+     * 以前是三个模块级全局一起被改写。
+     */
+    _colorPipeline;
+    /** fade-through 编排的代次：中途再切一次，旧编排作废（与 setMode 同一套） */
+    _pipelineGen = 0;
     /** 单体样式、专题着色与状态纹理管理器 */
     _featureStyleManager;
     /** GPU 路径动画管理器 */
@@ -219,7 +249,11 @@ export class S3MViewer {
         this._unsupported = options.unsupported ?? 'warn';
         this._lodPixelRatioCap = options.lodPixelRatioCap ?? Infinity;
         setTextureSizeCap(options.maxTextureSize ?? Infinity);
-        setMaterialQuality(options.materialQuality ?? 'pbr');
+        // 只记本层的档位，**不写模块级全局**：以前这里 setMaterialQuality(...) 会把全局
+        // 改掉，于是同页后创建的图层顺手把先创建的图层也打回去了（多层互相覆盖的根因）。
+        this._materialQuality = normalizeMaterialQuality(options.materialQuality);
+        // 之后 addDataset 的数据集按这个默认建材质（数据集自己指定则用自己的）
+        this._datasetManager.defaultMaterialQuality = this._materialQuality;
         if (options.totalMaxTiles) {
             this._datasetManager.totalMaxTiles = options.totalMaxTiles;
         }
@@ -243,7 +277,12 @@ export class S3MViewer {
         // 图层自身是否半透明：全局透明度改走 uOpacity 后，材质 opacity 不再代表它
         () => this._opacityTransparent);
         this.uniforms = createSharedUniforms();
-        // 光源状态在这里就位：LightRig 构造时会按 lightingPreset 切模块级颜色管线，
+        // 图层 profile 先落位（显式传了就只认自己），再把 LightRig 挂上来 ——
+        // 它构造时会按 lightingPreset 覆盖一次管线，这一步走的是图层级通道，
+        // 不再去改模块级全局（以前三个全局一起被改写，同页多图层互相污染）。
+        this._colorPipeline = normalizeColorPipeline(options.colorPipeline);
+        this._applyRenderProfile({}, true);
+        // 光源状态在这里就位：LightRig 构造时会按 lightingPreset 切图层颜色管线，
         // 挂进场景要等 scene 建好（构造函数上面已经建了）。
         this._lights = new LightRig({
             scene: () => this.scene,
@@ -254,6 +293,8 @@ export class S3MViewer {
             // 走公共 triggerRepaint 而不是 _requestRepaint：宿主 / 单测会覆盖前者来观察重绘，
             // 绕过它会让「有没有触发重绘」这件事失去观测点
             repaint: () => this.triggerRepaint(),
+            // 构造期（initial）只记状态：那时还没有材质可重建、没有数据集可同步
+            applyRenderProfile: (p, initial) => this._applyRenderProfile(p, initial),
         });
         this._lights.addToScene();
         this._heights = new HeightIndex(this.uniforms);
@@ -1548,7 +1589,11 @@ export class S3MViewer {
             this.animator.register(`style.${key}`, {
                 dim: 1,
                 read: (out) => {
-                    out[0] = Number(this.style[key] ?? 0);
+                    // 金属度 / 粗糙度没设过时 uniform 是 -1（= 不覆盖，保持数据自身的值），
+                    // 动画起点不能取 0：那会让 roughness 从 0.95 先跳到 0 再爬回去。
+                    // 这里给的是数据侧的常见值（S3M 的 shininess 映射后 ≈0.95、metalness 恒 0），
+                    // 过渡起点因此是连续的。
+                    out[0] = Number(this.style[key] ?? SCALAR_ANIM_START[key] ?? 0);
                 },
                 write: (v) => {
                     this.style[key] = v[0];
@@ -1790,21 +1835,124 @@ export class S3MViewer {
         this._requestRepaint();
     }
     /**
-     * 运行时切换材质质感（`'pbr'` | `'lambert'`）。
+     * 运行时切换**本图层**的材质质感（`'pbr'` | `'lambert'`）。
      *
-     * 档位是模块级设置（影响之后新建的材质）；已加载瓦片的材质在这里**原位重建**：
-     * 不重拉瓦片、不重建几何，按创建时记录的参数（`userData.s3mOpts`）换一个
-     * 新材质实例，并保留逐材质状态（选中编号、瓦片淡入、批量状态纹理）。
-     * 切换后 program 需要重新编译一次（lambert / pbr 是不同着色器），这是唯一开销。
+     * 档位是图层级的：只改这一层，同页其它图层不受影响（也不会去动模块级默认）。
+     * 已加载瓦片的材质在这里**原位重建**：不重拉瓦片、不重建几何，按创建时记录的
+     * 参数（`userData.s3mOpts`）换一个新材质实例，并保留逐材质状态（选中编号、
+     * 瓦片淡入、批量状态纹理）。切换后 program 需要重新编译一次（lambert / pbr 是
+     * 不同着色器），这是唯一开销。
      */
     setMaterialQuality(q) {
-        setMaterialQuality(q);
+        this._materialQuality = normalizeMaterialQuality(q) ?? 'pbr';
+        // 已建好的数据集也要跟着换，否则之后新加载的瓦片还是旧档位（和重建结果打架）
+        this._datasetManager.setDefaultMaterialQuality(this._materialQuality);
         this._rebuildStyledMaterials();
         this._requestRepaint();
     }
-    /** 当前材质质感档位 */
+    /** 当前材质质感档位（本图层指定了就用本图层的，否则是模块级默认） */
     get materialQuality() {
-        return getMaterialQuality();
+        return this._materialQuality ?? getMaterialQuality();
+    }
+    /**
+     * 运行时切换**本图层**的颜色管线（`'linear'` | `'direct'`）。
+     *
+     * `'direct'` = 官方 iClient3D 的 sRGB 直乘管线（配合纹理解码关 sRGB），
+     * 见 `lightingPreset: 'supermap'`。切换牵扯三样东西：材质宏（换 program）、
+     * 纹理 colorSpace（重传，**不重新下载瓦片**）、以及各向异性档位。
+     *
+     * 给 `duration > 0` 时走 fade-through：压暗 → 在同一帧回调里换管线 → 亮回来。
+     * 逐像素混合做不到干净 —— 两条管线的差异有一部分在采样端（硬件 sRGB 解码 vs
+     * 原始字节），要混合就得让贴图恒为原始字节并在片元里手动解码，那会改掉默认路径。
+     */
+    setColorPipeline(q, opts = {}) {
+        const next = normalizeColorPipeline(q) ?? 'linear';
+        if (next === this.colorPipeline)
+            return Promise.resolve();
+        const d = Math.max(0, opts.duration ?? 0);
+        if (d <= 0) {
+            this._applyRenderProfile({ colorPipeline: next });
+            return Promise.resolve();
+        }
+        const dim = Math.min(1, Math.max(0.05, opts.dim ?? 0.35));
+        const gen = ++this._pipelineGen;
+        return new Promise((resolve) => {
+            this.animator.to('style.fade', dim, {
+                duration: d,
+                easing: 'easeInOutQuad',
+                onComplete: () => {
+                    // 中途又切了一次：这次编排作废，收尾交给新的那次
+                    if (gen !== this._pipelineGen) {
+                        resolve();
+                        return;
+                    }
+                    this._applyRenderProfile({ colorPipeline: next });
+                    this.animator.to('style.fade', 1, {
+                        duration: d,
+                        easing: 'easeInOutQuad',
+                        onComplete: resolve,
+                    });
+                },
+            });
+        });
+    }
+    /** 当前颜色管线（本图层指定了就用本图层的，否则是模块级默认） */
+    get colorPipeline() {
+        return this._colorPipeline ?? getColorPipeline();
+    }
+    /** 本图层此刻该用的纹理创建参数（图层的渲染 profile 就落在这里） */
+    _textureOptions() {
+        return {
+            // direct 管线的前提是贴图字节值不解码，两者必须一起切
+            srgbDecode: this.colorPipeline !== 'direct',
+            maxSize: this.options.maxTextureSize ?? Infinity,
+            anisotropyCap: this.options.anisotropyCap ?? Infinity,
+        };
+    }
+    /**
+     * 应用图层渲染 profile（颜色管线 / 各向异性上限）。
+     *
+     * `initial` = 构造期：只记状态并推给数据集管理器，不重建材质、不重传纹理
+     * （那时还没有瓦片）。
+     */
+    _applyRenderProfile(patch, initial = false) {
+        const prev = this.colorPipeline;
+        if (patch.colorPipeline !== undefined) {
+            this._colorPipeline = normalizeColorPipeline(patch.colorPipeline) ?? 'linear';
+        }
+        if (patch.anisotropyCap !== undefined)
+            this.options.anisotropyCap = patch.anisotropyCap;
+        const textureOptions = this._textureOptions();
+        // 之后加载的瓦片按新参数走（已建好的数据集也要跟着换）
+        this._datasetManager.setRenderProfile({ colorPipeline: this.colorPipeline, textureOptions });
+        if (initial)
+            return;
+        // 管线变了才需要换 program；只改各向异性时重建纯属浪费
+        if (this.colorPipeline !== prev)
+            this._rebuildStyledMaterials();
+        this._syncCachedTextures(textureOptions);
+        this._requestRepaint();
+    }
+    /**
+     * 把纹理解码方式 / 各向异性同步到**已上传**的纹理上。
+     *
+     * 两者都不需要重新解码：`colorSpace` 改了 + `needsUpdate` 让 three 重传一次像素，
+     * `anisotropy` 同理。所以切管线不用重拉瓦片，代价只有一次纹理上传。
+     */
+    _syncCachedTextures(opts) {
+        const want = opts.srgbDecode ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+        for (const entry of this.datasets.values()) {
+            const cache = entry.tileset?.textureCache;
+            if (!cache)
+                continue;
+            for (const tex of cache.values()) {
+                if (tex.colorSpace === want)
+                    continue;
+                tex.colorSpace = want;
+                tex.needsUpdate = true;
+            }
+            applyAnisotropyCap(cache.values(), opts.anisotropyCap ?? Infinity);
+        }
     }
     /** 按创建参数原位重建所有 styled 材质（materialQuality 切换用） */
     _rebuildStyledMaterials() {
@@ -1827,7 +1975,14 @@ export class S3MViewer {
             if (!old?.userData?.isStyled || !old.userData?.s3mOpts)
                 continue;
             const opts = old.userData.s3mOpts;
-            const fresh = createStyledMaterial({ ...opts, uniforms: this.uniforms });
+            // 显式传本层档位与管线：s3mOpts 里记的是创建时的参数，可能是 undefined（跟随全局），
+            // 重建时必须钉成本层当前值，否则「别处改了全局」会把这一层带跑。
+            const fresh = createStyledMaterial({
+                ...opts,
+                uniforms: this.uniforms,
+                materialQuality: this.materialQuality,
+                colorPipeline: this.colorPipeline,
+            });
             for (const key of PRESERVED) {
                 const src = old.userData[key];
                 const dst = fresh.userData[key];
@@ -2162,16 +2317,19 @@ export class S3MViewer {
         return this.options.anisotropyCap ?? Infinity;
     }
     /**
-     * 调整各向异性过滤上限（默认 Infinity = 取 GPU 最大值）。
-     * 只影响**之后创建**的纹理——已上传的纹理需要重新上传才会变，代价远大于收益，
-     * 所以切换档位请在建图层前决定，或接受「新瓦片按新档位、旧瓦片保持原样」。
+     * 调整本图层的各向异性过滤上限（默认 Infinity = 取 GPU 最大值）。
+     *
+     * 与 0.4.22 之前不同：已上传的纹理**会立刻跟着变**（改 sampling 参数 + 重传，
+     * 不需要重新解码，也不需要重载瓦片），所以切 `lightingPreset: 'supermap'` 时
+     * 立面清晰度是当场变的，不再等新瓦片。
      */
     setAnisotropyCap(cap) {
         const next = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
         this.options.anisotropyCap = next;
+        // 同步模块级默认：直接调 createTexture / buildTileObjects 的老用法仍读它
         const gpuMax = this.renderer?.capabilities.getMaxAnisotropy?.() ?? 1;
         setMaxAnisotropy(gpuMax, next);
-        this._requestRepaint();
+        this._applyRenderProfile({ anisotropyCap: next });
     }
     /** 当前纹理长边像素上限。Infinity = 不限制 */
     get maxTextureSize() {
@@ -2180,12 +2338,16 @@ export class S3MViewer {
     /**
      * 调整纹理长边像素上限（默认 Infinity = 不限制）。
      * 只影响之后解码的纹理；非图集的 RGBA / WebP 产物按 2× 减半逼近上限。
-     * 注意这是**模块级**设置（图集 / 解码 Worker 共享），多 viewer 实例会互相覆盖。
+     *
+     * 图层级：只改本层，同页其它图层不受影响（同时同步模块级默认，照顾直接调
+     * `createTexture` 的老用法）。已解码的纹理不会重解 —— 那是另一件事。
      */
     setMaxTextureSize(n) {
         const next = Number.isFinite(n) && n >= 1 ? n : Infinity;
         this.options.maxTextureSize = next;
         setTextureSizeCap(next);
+        // 只推给数据集，不动材质也不重传纹理（尺寸上限只影响「之后解码」的纹理）
+        this._datasetManager.setRenderProfile({ textureOptions: this._textureOptions() });
         this._requestRepaint();
     }
     /**