s3m-three 0.4.19 → 0.4.21

package/dist/render/viewer/EdgeDecorator.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 棱线装饰：折边线 / 外推 / 背面外扩轮廓 / GPU 后处理描边。
+ *
+ * 从 `S3MViewer` 整体搬出来的最大一块。它只碰 `mesh.userData`（`edges` / `edgeHull` /
+ * `nativeEdges`）与共享 uniform，不碰拾取表、不碰瓦片生命周期 —— 所以能独立成模块。
+ *
+ * ## 为什么外观 uniform 要共享
+ *
+ * 棱线材质必须**逐网格一份**（各绑各的单体状态纹理），但外观（颜色 / 粗细 / 透明度 /
+ * 外推距离）必须全局统一。做法是外观 uniform 用同一批对象，`syncStyle()` 改一次全部生效，
+ * 棱线淡入淡出也只改一个 `uEdgeFade` —— 新建瓦片自动继承当前进度。
+ *
+ * ## 三种画法的成本
+ *
+ * - `line` / `offset`：CPU 现算 EdgesGeometry，按 8ms 一帧切片建，几十万面不会卡死；
+ * - `hull`：不建几何，把同一块网格沿法线外扩再画一遍，只画背面；
+ * - `gpu`：零几何、零额外 pass 的片元描边，线宽约 1 像素。
+ */
+import * as THREE from 'three';
+import type { Animator, TransitionOptions } from '../../anim/Animator.js';
+import type { AuthenticateFn } from '../../core/AuthFetch.js';
+import type { StyleUniforms } from '../../core/types.js';
+import { type EdgeModes, type EdgesOption } from '../StyleMaterial.js';
+import { type LineSharedUniforms, type ThickLineMaterial } from '../EdgeLines.js';
+import { GpuEdgePass } from '../GpuEdgePass.js';
+import type { S3MDatasetEntry } from '../DatasetManager.js';
+/** 宿主需要提供的东西。只列真正用到的，避免模块偷偷依赖整只 viewer */
+export interface EdgeHost {
+    readonly uniforms: StyleUniforms;
+    /** 当前**显示**的样式（动画推进中会逐帧变） */
+    readonly style: {
+        edges: EdgesOption;
+        forceCpuEdges?: boolean;
+        edgeColor: string;
+        edgeWidth?: number;
+        edgeOpacity?: number;
+        edgeOffset?: number;
+        edgeHullWidth?: number;
+        edgeThreshold?: number;
+        opacity?: number;
+    };
+    /** 用户想要的样式（`setEdges` 要同步写回，`getStyle()` 才拿得到） */
+    readonly styleTarget: {
+        edges: EdgesOption;
+    };
+    readonly animator: Animator;
+    readonly pickables: Map<number, {
+        mesh: THREE.Mesh;
+    }>;
+    scene: THREE.Scene | null;
+    renderer: THREE.WebGLRenderer | null;
+    camera: THREE.Camera | null;
+    readonly authenticate: AuthenticateFn | undefined;
+    requestRepaint(): void;
+}
+export declare class EdgeDecorator {
+    private readonly host;
+    /** 等宽线共享的分辨率 uniform（全局棱线 + 选中棱线共用） */
+    readonly lineShared: LineSharedUniforms;
+    /** 全局棱线材质（外观 uniform 的持有者，逐网格棱线材质共享它的对象） */
+    readonly edgeMaterial: ThickLineMaterial;
+    /** 选中棱线材质（同上，选中棱线的逐网格材质共享它的对象） */
+    readonly selectionEdgeMaterial: ThickLineMaterial;
+    private readonly _edgeStyleUniforms;
+    private readonly _selEdgeStyleUniforms;
+    private readonly _hullStyleUniforms;
+    private _enabled;
+    private _modes;
+    /** 预制棱线缓存（Crease Cache）：外部载入的全局统一 LineSegments */
+    private _creaseLines;
+    /** 数据自带的棱线对象：改颜色时只刷这些，不再全场景 traverse */
+    private readonly _nativeLines;
+    /** GPU 描边后处理（深度 + 法线），只在 edges 含 'gpu' 时按帧执行 */
+    private _gpuEdge;
+    /** 给 GPU 描边传色用的临时 Color，避免每帧 new */
+    private readonly _gpuEdgeColor;
+    constructor(host: EdgeHost);
+    /** 当前是否开启棱线 */
+    get enabled(): boolean;
+    /** 当前生效的画法 */
+    get modes(): EdgeModes;
+    /** 数据自带棱线包在当前画法下还算不算数 */
+    useNativeEdges(hasNative: boolean): boolean;
+    /** 登记数据自带的棱线（注册瓦片时调） */
+    registerNativeLine(lines: THREE.LineSegments, visible: boolean): void;
+    /** 注销数据自带的棱线（瓦片淘汰时调） */
+    unregisterNativeLine(lines: THREE.LineSegments): void;
+    /** 新瓦片是否要自动补棱线装饰（受全局开关 / 数据集开关 / 关键字跳过三道控制） */
+    autoDecorate(mesh: THREE.Mesh, entry: S3MDatasetEntry, hasNativeEdges: boolean): void;
+    /** 释放全部装饰与后处理资源（unmount 时调） */
+    disposeAll(): void;
+    /** @internal GPU 描边实例，单测会替换成假对象观察 dispose */
+    get gpuEdge(): GpuEdgePass | null;
+    set gpuEdge(v: GpuEdgePass | null);
+    /** GPU 描边资源单独释放（换上下文时调，下一帧按需重建） */
+    disposeGpuEdge(): void;
+    /** 一帧的 GPU 描边，必须画在主场景之后（依赖本帧已写好的深度） */
+    renderGpuEdges(canvas: HTMLCanvasElement): void;
+    /** 建逐网格棱线材质；`selection` 为真时用选中棱线那套外观 uniform */
+    createPerMeshEdgeMaterial(mesh: THREE.Mesh, selection?: boolean): ThickLineMaterial;
+    /**
+     * 全局棱线开关。
+     *
+     * 取值是 `boolean | EdgeStyle | EdgeStyle[]`（见 resolveEdgeModes）：
+     *   - `true` / `'line'`   折边线（旧口径）
+     *   - `'offset'`          折边线 + 沿边法线外推 `edgeOffset` 米
+     *   - `'hull'`            背面外扩轮廓（选中侧 outlineStyle:'hull' 的整场景版）
+     *   - `'gpu'`             纯片元描边：零几何、零额外 pass，线宽约 1 像素
+     *   - 数组                叠加，例如 `['line', 'hull']`
+     *
+     * 数据自带棱线包（primitiveType 13）时直接用，成本为零；`style.forceCpuEdges`
+     * 可以无视它，改由 CPU 现算 —— 那是 CPU 端的活，几十万面一次性建会卡住主线程
+     * （实测 20 个网格 1.9s），所以按 8ms 一帧切片，边建边出。
+     *
+     * 棱线本身用「屏幕空间等宽线」画（见 EdgeLines.ts）：WebGL 的 lineWidth 基本无效，
+     * 只有摊成面向屏幕的四边形，`edgeWidth` 才能真正调粗。
+     *
+     * 带 `transition` 时做「淡入 / 淡出」，**不对几何做插值**（几何没法插值）：
+     * 开：立刻置位 + 开始分片建线，同时 `uEdgeFade` 0→1 —— 建好一块亮一块，视觉上是渐显；
+     * 关：`uEdgeFade` 1→0，淡完才 dispose，避免棱线「啪」一下消失。
+     */
+    setEdges(edges: EdgesOption, transition?: TransitionOptions): void;
+    /** 直接写棱线淡入乘子（不走动画通道） */
+    private _setEdgeFade;
+    /** 释放所有现算棱线几何 */
+    private _disposeEdges;
+    /**
+     * 挂载预制棱线缓存（Crease Cache）。
+     *
+     * 直接把 `source-creases.f32` 这类 Float32Array 缓冲载入为一组全局统一的
+     * LineSegments —— 相比逐 Mesh 现算 EdgesGeometry，性能高一个量级，视觉也最干净。
+     * 坐标按「场景本地坐标」（相对场景锚点的米）处理，与瓦片几何同一坐标系。
+     *
+     * @param url  棱线缓存地址（二进制 Float32 序列：x,y,z,x,y,z,… 成对成段）
+     */
+    loadCreases(url: string): Promise<void>;
+    /** 移除并释放预制棱线缓存 */
+    clearCreases(): void;
+    /**
+     * 让全局棱线材质跟上 style.edgeColor / edgeWidth / edgeOpacity / edgeOffset。
+     *
+     * 全程 O(1)：只有一份共享 edgeMaterial（所有逐 mesh 棱线都用它）+ 一份预制缓存
+     * + 一批共享外观对象的轮廓壳，所以棱线淡入淡出只要改一个 uniform，
+     * 新建瓦片自动继承当前进度。
+     */
+    private _syncEdgeStyle;
+    /** 让数据自带的棱线跟着 style.edgeColor / opacity 走（这些是 LineBasicMaterial，改不了粗细） */
+    private _styleEdgeLine;
+    /**
+     * 刷新所有棱线外观。
+     *
+     * 数据自带的棱线是逐对象的 LineBasicMaterial，改颜色只能一个个写；但原来每次都要
+     * 遍历整个数据集树（几千个节点），颜色动画逐帧跑就是灾难。改成只刷注册时收集好的
+     * 那批 LineSegments，复杂度降到 O(棱线条数)。
+     */
+    private _refreshEdgeLines;
+    /** 地形 / 绿地 / 道路 / 地面铺装等不参与自动描边（数据自带棱线包另说） */
+    /** 数据集级别的棱线开关：enableEdges 优先，否则跟随全局 style.edges */
+    private _datasetEdgesEnabled;
+    /** 该 mesh 是否命中「跳过自动描边」的关键字（skeletonName / 数据集名） */
+    private _shouldSkipAutoEdges;
+    /**
+     * 这块网格还缺哪种棱线装饰（缺就建，齐了就不动）。
+     *
+     * setEdges 的分片建线靠它筛「还没建完的」，注册新瓦片也靠它决定要不要动手。
+     */
+    private _needsEdgeDecoration;
+    /** 按当前画法补齐这块网格的棱线装饰 */
+    private _ensureEdgeDecoration;
+    private _ensureEdges;
+    /**
+     * 给一块网格挂「背面外扩轮廓」（整场景版）。
+     *
+     * 复用选中侧那套 `createOutlineMaterial`：顶点沿法线鼓 `edgeHullWidth` 米、只画背面，
+     * 于是被本体挡住的部分不显示，露出来的那圈就是描边。与折边线的差别在于——
+     * 这里**不建任何新几何**，成本只是把同一块网格多画一遍，折边判定那套 CPU 活全省了。
+     *
+     * 实例化几何拿不到逐实例变换（轮廓壳是 mesh 的子节点，不吃 instanceMatrix），
+     * 直接跳过：宁可这栋没描边，也不要所有实例的壳叠在原点。
+     */
+    private _ensureHull;
+    /**
+     * 给一块网格造专属的棱线材质。
+     *
+     * 棱线材质必须逐网格一份，因为它要绑定**这个网格**的单体状态纹理；但外观
+     * （颜色 / 粗细 / 透明度）必须全局统一——所以外观 uniform 直接复用
+     * `_edgeStyleUniforms` 里的对象，`_syncEdgeStyle()` 改一次全部生效，
+     * program 也因为着色器相同而只编译一次。
+     */
+    /** 选中棱线的逐网格材质，道理同上 */
+    private _createSelectionEdgeMaterial;
+    private _removeEdges;
+    /** 让全局棱线材质跟上当前 style（颜色 / 粗细 / 透明度 / 外推距离），O(1) */
+    syncStyle(): void;
+    /** 刷新所有棱线外观：共享材质 + 数据自带的那批 LineSegments */
+    refreshLines(): void;
+    /** 释放所有现算棱线几何（临界角 / 画法变了要重建，见 setEdges） */
+    disposeEdgeGeometry(): void;
+    /** @internal 给一块网格补折边线（单测直接调，观察顶点焊合 / 临界角） */
+    ensureEdges(mesh: THREE.Mesh): void;
+    /** 拆掉一块网格的棱线与外扩壳（瓦片淘汰时调） */
+    removeEdges(mesh: THREE.Mesh): void;
+    /** 选中棱线的逐网格材质 */
+    createSelectionEdgeMaterial(mesh: THREE.Mesh): ThickLineMaterial;
+}
+//# sourceMappingURL=EdgeDecorator.d.ts.map

package/dist/render/viewer/EdgeDecorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeDecorator.d.ts","sourceRoot":"","sources":["../../../src/render/viewer/EdgeDecorator.ts"],"names":[],"mappings":"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"}