three-base 2.0.137 → 2.0.142

package/Mirror.ts

@@ -0,0 +1,203 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2023-08-04 17:17:15
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-01-20 05:33:51
+ */
+import { Color, DoubleSide, HalfFloatType, Matrix4, Mesh, PerspectiveCamera, Plane, PlaneGeometry, ShaderMaterial, Vector3, Vector4, WebGLRenderTarget, WebGLRenderer, Scene, Camera, BufferGeometry, Material, Group, Texture } from "three";
+
+// 镜子模型
+export default class Mirror extends Mesh {
+    constructor(geometry: BufferGeometry = Mirror.geometry) {
+        super(geometry);
+        // 镜子虽标了 transparent:true（为渲染顺序），但 fragment shader 实际输出 alpha=1.0，
+        // 是实心反射面、并非可透视表面 → 必须参与 AO 与描边/辉光的深度遮挡。
+        // SSAO 的 AO 数据准备会排除所有 transparent 物体，故此处显式声明保留。
+        this.userData.aoOpaque = true;
+    }
+
+    // 正方形网格
+    static geometry: PlaneGeometry = (() => {
+        const geometry = new PlaneGeometry(10, 10, 1, 1);
+        return geometry;
+    })();
+
+    isReflector: boolean = true;
+    type: string = 'Reflector';
+    camera: PerspectiveCamera = new PerspectiveCamera();
+    reflectorPlane: Plane = new Plane();
+    normal: Vector3 = new Vector3();
+    reflectorWorldPosition: Vector3 = new Vector3();
+    cameraWorldPosition: Vector3 = new Vector3();
+    rotationMatrix: Matrix4 = new Matrix4();
+    lookAtPosition: Vector3 = new Vector3(0, 0, -1);
+    clipPlane: Vector4 = new Vector4();
+    view: Vector3 = new Vector3();
+    target: Vector3 = new Vector3();
+    q: Vector4 = new Vector4();
+    textureMatrix: Matrix4 = new Matrix4();
+    virtualCamera: PerspectiveCamera = this.camera;
+    renderTarget: WebGLRenderTarget<Texture> = new WebGLRenderTarget(2048, 2048, { type: HalfFloatType });
+    material: ShaderMaterial = new ShaderMaterial({
+        uniforms: {
+            'color': {
+                value: new Color("#b6b6b6")
+            },
+            'tDiffuse': {
+                value: this.renderTarget.texture
+            },
+            'textureMatrix': {
+                value: this.textureMatrix
+            },
+            blurAmount: {
+                value: 0.5
+            } // 模糊程度，可以根据需求调整
+        },
+        vertexShader: /* glsl */ `
+                    uniform mat4 textureMatrix;
+                    varying vec4 vUv;
+        
+                    #include <common>
+                    #include <logdepthbuf_pars_vertex>
+        
+                    void main() {
+        
+                        vUv = textureMatrix * vec4( position, 1.0 );
+        
+                        gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+        
+                        #include <logdepthbuf_vertex>
+        
+                    }`,
+        fragmentShader: /* glsl */ `
+            uniform vec3 color;
+            uniform sampler2D tDiffuse;
+            varying vec4 vUv;
+            uniform float blurAmount;
+
+            #include <logdepthbuf_pars_fragment>
+
+            float blendOverlay( float base, float blend ) {
+
+                return( base < 0.5 ? ( 2.0 * base * blend ) : ( 1.0 - 2.0 * ( 1.0 - base ) * ( 1.0 - blend ) ) );
+
+            }
+
+            vec3 blendOverlay( vec3 base, vec3 blend ) {
+
+                return vec3( blendOverlay( base.r, blend.r ), blendOverlay( base.g, blend.g ), blendOverlay( base.b, blend.b ) );
+
+            }
+
+            void main() {
+
+                #include <logdepthbuf_fragment>
+
+                vec2 texelSize = 1.0 / vec2(1024,1024);
+                vec4 fragColor = vec4(0.0);
+            
+                  for (float offsetX = -blurAmount; offsetX <= blurAmount; offsetX += texelSize.x) {
+                    for (float offsetY = -blurAmount; offsetY <= blurAmount; offsetY += texelSize.y) {
+                        //  fragColor += texture2DProj(tDiffuse, vUv + vec4(offsetX, offsetY, 0.0, 0.0) * texelSize);
+                         fragColor += texture2DProj(tDiffuse, vUv + vec4(offsetX * texelSize.x, offsetY * texelSize.y, 0.0, 0.0) );
+                    }
+                  }
+            
+                // fragColor /= pow(2.0 * blurAmount + 1.0, 2.0);
+                // gl_FragColor = color;
+
+                fragColor = texture2DProj( tDiffuse, vUv );
+                gl_FragColor = vec4( blendOverlay( fragColor.rgb, color ), 1.0 );
+
+                #include <tonemapping_fragment>
+                #include <colorspace_fragment>
+            }`,
+        depthTest: true,
+        depthWrite: true,
+        transparent: true,
+        side: DoubleSide
+    });
+
+    onBeforeRender = (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group): void => {
+        this.reflectorWorldPosition.setFromMatrixPosition(this.matrixWorld);
+        this.cameraWorldPosition.setFromMatrixPosition(camera.matrixWorld);
+        this.rotationMatrix.extractRotation(this.matrixWorld);
+        this.normal.set(0, 0, 1);
+        this.normal.applyMatrix4(this.rotationMatrix);
+        this.view.subVectors(this.reflectorWorldPosition, this.cameraWorldPosition);
+        // Avoid rendering when reflector is facing away
+        if (this.view.dot(this.normal) > 0) {
+            this.normal.set(0, 0, -1);
+        };
+        this.view.reflect(this.normal).negate();
+        this.view.add(this.reflectorWorldPosition);
+        this.rotationMatrix.extractRotation(camera.matrixWorld);
+        this.lookAtPosition.set(0, 0, -1);
+        this.lookAtPosition.applyMatrix4(this.rotationMatrix);
+        this.lookAtPosition.add(this.cameraWorldPosition);
+        this.target.subVectors(this.reflectorWorldPosition, this.lookAtPosition);
+        this.target.reflect(this.normal).negate();
+        this.target.add(this.reflectorWorldPosition);
+        this.virtualCamera.position.copy(this.view);
+        this.virtualCamera.up.set(0, 1, 0);
+        this.virtualCamera.up.applyMatrix4(this.rotationMatrix);
+        this.virtualCamera.up.reflect(this.normal);
+        this.virtualCamera.lookAt(this.target);
+        this.virtualCamera.far = this.camera.far; // Used in WebGLBackground
+        this.virtualCamera.updateMatrixWorld();
+        this.virtualCamera.projectionMatrix.copy(camera.projectionMatrix);
+        // Update the texture matrix
+        this.textureMatrix.set(0.5, 0.0, 0.0, 0.5, 0.0, 0.5, 0.0, 0.5, 0.0, 0.0, 0.5, 0.5, 0.0, 0.0, 0.0, 1.0);
+        this.textureMatrix.multiply(this.virtualCamera.projectionMatrix);
+        this.textureMatrix.multiply(this.virtualCamera.matrixWorldInverse);
+        this.textureMatrix.multiply(this.matrixWorld);
+        // Now update projection matrix with new clip plane, implementing code from: http://www.terathon.com/code/oblique.html
+        // Paper explaining this technique: http://www.terathon.com/lengyel/Lengyel-Oblique.pdf
+        this.reflectorPlane.setFromNormalAndCoplanarPoint(this.normal, this.reflectorWorldPosition);
+        this.reflectorPlane.applyMatrix4(this.virtualCamera.matrixWorldInverse);
+        this.clipPlane.set(this.reflectorPlane.normal.x, this.reflectorPlane.normal.y, this.reflectorPlane.normal.z, this.reflectorPlane.constant);
+        const projectionMatrix = this.virtualCamera.projectionMatrix;
+        this.q.x = (Math.sign(this.clipPlane.x) + projectionMatrix.elements[8]) / projectionMatrix.elements[0];
+        this.q.y = (Math.sign(this.clipPlane.y) + projectionMatrix.elements[9]) / projectionMatrix.elements[5];
+        this.q.z = -1.0;
+        this.q.w = (1.0 + projectionMatrix.elements[10]) / projectionMatrix.elements[14];
+        // Calculate the scaled plane vector
+        this.clipPlane.multiplyScalar(2.0 / this.clipPlane.dot(this.q));
+        // Replacing the third row of the projection matrix
+        projectionMatrix.elements[2] = this.clipPlane.x;
+        projectionMatrix.elements[6] = this.clipPlane.y;
+        projectionMatrix.elements[10] = this.clipPlane.z + 1.0 - 0.003;
+        projectionMatrix.elements[14] = this.clipPlane.w;
+        // Render
+        this.visible = false;
+        const currentRenderTarget = renderer.getRenderTarget();
+        const currentXrEnabled = renderer.xr.enabled;
+        const currentShadowAutoUpdate = renderer.shadowMap.autoUpdate;
+        renderer.xr.enabled = false; // Avoid camera modification
+        renderer.shadowMap.autoUpdate = false; // Avoid re-computing shadows
+        renderer.setRenderTarget(this.renderTarget);
+        renderer.state.buffers.depth.setMask(true); // make sure the depth buffer is writable so it can be properly cleared, see #18897
+        if (renderer.autoClear === false)
+            renderer.clear();
+        renderer.render(scene, this.virtualCamera);
+        renderer.xr.enabled = currentXrEnabled;
+        renderer.shadowMap.autoUpdate = currentShadowAutoUpdate;
+        renderer.setRenderTarget(currentRenderTarget);
+        // Restore viewport
+        const cameraWithViewport = this.camera as PerspectiveCamera & { viewport?: { x: number; y: number; width: number; height: number } };
+        const viewport = cameraWithViewport.viewport;
+        if (viewport !== undefined) {
+            renderer.state.viewport(viewport);
+        }
+        this.visible = true;
+    };
+
+    getRenderTarget(): WebGLRenderTarget<Texture> {
+        return this.renderTarget;
+    };
+
+    dispose(): void {
+        this.renderTarget.dispose();
+        // this.material.dispose();
+    };
+}

package/MktMesh/MktMesh.d.ts

@@ -0,0 +1,291 @@
+import { BufferGeometry, Camera, Matrix4, Mesh, ShaderMaterial, Texture, Vector3 } from "three";
+import { type PanoTexMode } from "./mktShader";
+import { type PanoStitcher } from "./panoTileStitcher";
+import type { MktMeshData, MktTextureInfo, WallPoint, WallSide } from "./types";
+export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
+    /** 纹理列表（每个纹理的 url + 世界矩阵） */
+    textures: MktTextureInfo[];
+    /** 当前激活（正在绘制）的纹理索引，-1 表示尚未激活。⭐ 10-03 起该值 = 槽位名册的**中心**（`_slotPanos[0]`），不是「每帧纯最近那张」 */
+    activeIndex: number;
+    /** 墙体地面折线点位（XZ 平面，世界坐标） */
+    wallPoints: WallPoint[];
+    /** 墙体高度（沿 +Y 挤出） */
+    wallHeight: number;
+    /** 墙体折线是否闭合（首尾相连成环） */
+    wallClosed: boolean;
+    /** 墙体正反面显示（字段保留兼容存档；09-29 晚旨后无论何值材质一律 BackSide，见 _wallSideToThree） */
+    wallSide: WallSide;
+    /** 是否跳过墙体上/下多边形封盖（true = 只留侧面幕墙）。⚠️ 2026-09-26 核实：本库与编辑态**都取默认 false**
+     *  （旧注释写「编辑态 MktDevMesh 设为 true」是错的 —— MktDevMesh 明确保留封盖，与发布态一致，
+     *   见其类头注释）。封盖与侧面**同一份几何、同一份材质** ⇒ 正反面（material.side）天然同步，
+     *   没有「封盖不跟墙体正反面」的第二套口径（这正是皇上 09-26 第①条要查的点）。 */
+    skipWallCaps: boolean;
+    /**
+     * ⭐ 皇上旨 2026-10-07「上下封口的三角面能不能不要那么长 / 三角面再细分一下，不要那么大」：
+     *  上/下封盖在耳切三角化之后，再按**最长边二分**切到每条边都 ≤ 本值（米）。粒度越细 ⇒
+     *  封盖上「一个三角面 = 一张全景」的区块越小，序号映射 / 取图在天花板和地面上分得越准
+     *  （原先一个耳切大三角能横跨整个房间 ⇒ 整片天花板只能是同一张全景）。
+     *  ⛔ 0 / 负数 = 不细分（= 10-07 之前的形状）。
+     *  ⚠️ 改这个值会**改变面数** ⇒ 存档里的逐面序号按「块」继承（见 `importData` 那句 warn）。
+     */
+    wallCapMaxEdgeM: number;
+    /**
+     * 全景「序号直接取」映射：每个三角面（faceIndex）→ 被指派的「全景全局序号」（-1=未设）。
+     * 序号直接取由着色器读取 geometry 的 aPanoIndex；与 panoIndices 槽数组配合取对应全景纹理。
+     * 长度 = 几何三角面数，随 rebuildWallGeometry 按位置重算（保留旧映射，见下方注释）。
+     * 该数据随工程存档持久化（MktMeshData.panoFaceMapping），编辑器/预览/发布三端同源。
+     */
+    panoFaceMapping: number[];
+    /**
+     * 全景点坐标数组（每全景 3 个数 = 中心点 xyz，世界坐标）。
+     * ⭐ 2026-09-30 旨：全景点数据是**独立的纯几何数据**，与纹理图片是否加载/解码无关；
+     *    智能序号只认这份，不认 textures。由 setTextures/addTexture/removeTexture/setTexture(矩阵变更) 派生（_syncPanoCenters）。
+     *    本数组是「每全景 xyz」的**源**；序号映射最终烘焙成几何属性 `aPanoCenter`（每三角面9数，与 position 对齐），见 _syncPanoCenterAttr。
+     * ⚠️⚠️ 2026-10-01 血案修复：本字段改为**读取时实时派生**（getter），不再依赖「谁记得调 _syncPanoCenters」。
+     *    起因：`MktDevMesh.setTextures` 覆写了基类（编辑态不激活单全景），直接 `this.textures = textures` 而**不调
+     *    super** ⇒ 派生点整条被绕过，`panoCenters` 恒为空 ⇒ 映射模式下点「智能序号」在 centerCount===0 处静默 return，
+     *    墙上全空且无任何提示。派生点式缓存在有子类覆写时就必然漏，**改为实时派生才是根治**（读一次 O(全景数)，
+     *    调用方只有智能序号与 _syncPanoCenterAttr，都不是每帧路径）。
+     */
+    get panoCenters(): number[];
+    /** 派生结果的落点（勿直接读写，统一走 panoCenters getter / _syncPanoCenters） */
+    private _panoCentersCache;
+    /** 旧几何的「面中心 XZ→{y, 序号}」索引，用于改墙/改高后按位置保留全景序号映射（皇上旨 2026-09-28 决策②）。 */
+    private _panoXZMap;
+    /**
+     * ⭐ 槽位名册（皇上旨 2026-10-03「库侧也一并改成中心 ± 邻居」）：每帧由 `updateTexture` 走
+     *    `panoSlotRosterStep` 算出，**0 号槽 = 中心**（⭐ 10-07 第二十一道旨：离**控制器中心点** XZ 最近那张，
+     *    带 `PANO_SLOT_SWAP_MARGIN_M` 死区；锚点见 `_rosterCenter`），
+     *    1..7 = 中心在全景列表里的序号一层层往外扩的邻居（⭐ 10-07 旨「尽可能填满 8 个全景位置」⇒ 越界的序号不占格、
+     *    继续往有货那侧扩 ⇒ 填几格 = min(项目全景总数, 8)，只有全景总数不够时才有空格）。
+     *    ⇒ 与编辑态 `mktMeshEditRenderer._slotPanos` **同一份算法、同一个常数**（预览看到的那几张 = 编辑器里的那几张，均为 8 个全景槽）。
+     *    存**对象引用**不存下标（删点会让下标整体前移，引用不会认错人）。
+     *    消费方 = `feedFaceMapping`（墙 8 格）；⭐ 10-03 旨② 后预览立方体与墙**共用同一份材质**，
+     *    立方体几何无 `aPanoIndex` ⇒ `vPanoIndex ≡ 0` ⇒ 它显示的就是 0 号槽那张（墙与立方体天然同源，
+     *    原来那条「把中心那几张抄给立方体单全景材质」的 `currentTiles` 旁路已整条删除）。
+     */
+    private _slotPanos;
+    /**
+     * ⭐ 名册那把尺子的**锚点**（皇上旨 2026-10-07 第二十一道旨：「判断使用哪些全景球的判断条件，
+     *    从距离相机的距离改成判断距离控制器的中心点的距离」）。这里存外部控制器的中心点
+     *    （轨道控制器 = `controls.target`，也就是画面正中央那个注视点），由消费方经 `setRosterCenter()` 注入。
+     *  · 只读 XZ ⇒ 与名册历代那把「水平距离」尺同一把（09-28 旨），高度差不进尺子。
+     *  · `null` ⇒ 回落 `camera.position`（老口径）：发布页那一路没有控制器引用，不注入就一切照旧。
+     *  · 存的是**引用**（OrbitControls 原地改它那个 Vector3）⇒ 消费方设一次即可，不必每帧重设。
+     *  · ⚠️ 全景点矩阵本就是**世界矩阵**，锚点也取世界坐标；⛔ 别再乘一遍 `matrixWorld`（同 `updateTexture` 里那句提醒）。
+     */
+    private _rosterCenter;
+    /**
+     * ⭐ 皇上旨 2026-10-03「整套搬进库（彻底同源）」：库侧不再自养「按全景序号取整槽、齐活才写」那一路，
+     *    改成与编辑态**同一份换绑策略**（`./panoSlotBind`）+ 同一口径的三张表：
+     *    地址→纹理缓存、已上传 GPU 集合、待上传排队集合。治的两个病：
+     *    ① 换景点闪一帧灰（库侧原先没有「未就绪整槽沿用上一批」这层兜底）；
+     *    ② 图与投影矩阵来自**不同批**（原先矩阵无条件 copy，纹理却可能还在路上）。
+     *    地址 → 已解码纹理；值为 `null` = 该地址正在加载（占位 ⇒ 同一地址不会被问两次就下两遍）。
+     *    ⚠️ 皇上旨 2026-10-02：运行中**不淘汰**任何一张，只在 `dispose()` 整批释放。
+     */
+    private _texCache;
+    /** 已上传 GPU 的纹理：没进这张表的**不许**绑进 shader（首绑现场 `texImage2D` 就是那一下卡顿，皇上旨 09-29「两个大头别在同一帧」） */
+    private _texUploaded;
+    /** 已排进全局队列、等着「只干上传那一句」的纹理（`addWork` 按闭包判重判不出来 ⇒ 必须自备集合） */
+    private _uploadQueued;
+    /** 加载地址真的拼了 ossSize 缩放参数的条目 ⇒ 换档只重载这些（真瓦片一律原图，不进此集） */
+    private _ossSizeDepKeys;
+    /** 渲染器：由 `onBeforeRender` 每帧捕获，预上传走它的 `initTexture`；没捕获到就退回 three 的自绑路径（不报错） */
+    private _glRenderer;
+    /** ⭐ 32 瓦片（横 8 × 竖 4 切片）离屏拼合器：左右 2 槽纹理由它逐格拼出（每帧一张新纹理进 GPU + 已进 GPU 的逐格画）。
+     *  编辑器渲染器经 `panoStitcher` 复用同一实例（同一份槽纹理缓存，⛔ 不另建第二份显存）。
+     *  皇上旨 2026-10-06「不用 canvas 2D 的 drawImage 拼合, 用一个 shader 一个一个渲染到 RT 上面去」
+     *  +「canvas 是什么意思, 按照我的想法, 不应该有 canvas 才对啊」⇒ **只此一份实现**：旧的 canvas 2D
+     *  那一份连同 `?panoStitch=canvas` 对照开关整条删除。⚠️ RT 是 GL 上下文私有资源 ⇒ 见拼合器 `_switchRenderer`。 */
+    private _stitcher;
+    /** 拼合器只读访问（编辑器渲染器共用；⛔ 不另建第二实例） */
+    get panoStitcher(): PanoStitcher;
+    /** 融合材质未绑纹理时的占位（避免空纹理采样报错；深灰兜底由着色器 uFaceMissingColor 负责） */
+    protected _placeholder: Texture;
+    /** 纹理 OSS 缩放尺寸（1024 / 2048 / 空=原图），由外部 setOssSize 注入；默认 1024 保持旧行为。
+     *  编辑器渲染器与预览渲染器各自把 store.ossSize 推下来，使全景球/预览按该尺寸加载。 */
+    private _ossSize;
+    /** 全景纹理形态：tiled=左右 2 槽各装一张**拼合槽纹理**（该点 32 片 横 8 × 竖 4 → 2 张 4096×4096，10-06 晚旨）
+     *  / whole=2 槽同为一张完整等距柱状原图。
+     *  由外部 setPanoTexMode 注入（与 _ossSize 同一套注入路径），默认 tiled 保持改造前行为。 */
+    private _panoTexMode;
+    /** 当前全景纹理形态（只读）。消费方（预览立方体等自持材质的路径）据此算 `mktPanoTiledFlag`，
+     *  必须与基类喂纹理处用同一个值，否则标记与地址不同源 ⇒ 整图被按 1/2 横向铺满球面（10-06 晚起纵向不分块，四槽时代是 1/4）。 */
+    get panoTexMode(): PanoTexMode;
+    private _tmpV3;
+    constructor(opts?: {
+        wallHeight?: number;
+        wallClosed?: boolean;
+    });
+    /**
+     * 设置墙体地面折线点位，并重建墙体几何。
+     * @param points 地面折线点位（XZ 平面，世界坐标），至少 2 个点才能生成墙体
+     * @param opts.closed 是否闭合（首尾相连成环），默认沿用当前 wallClosed
+     * @param opts.height 墙高（沿 +Y 挤出），默认沿用当前 wallHeight
+     */
+    setWallPoints(points: WallPoint[], opts?: {
+        closed?: boolean;
+        height?: number;
+    }): void;
+    /** 读取墙点位（副本，含 y，调用方可自行修改再回设） */
+    getWallPoints(): WallPoint[];
+    /**
+     * 墙正面/反面枚举 → three.js Side 常量。
+     * ⭐ 2026-09-29 晚旨「shader 设反面显示、不要双面」：三档**全部**落到 BackSide（对应历史上
+     *   的 wallSide="back" 档 —— 零厚度幕墙只画**朝房间内的那一面**，从房间外看穿过去、看不到内部全景）。
+     * API 形参与 wallSide 字段保留（存档/调用方兼容）。⚠️ 地板/立方体**不由这里控制**：编辑态地板恒走「仅显示选中」工厂（DoubleSide）；
+     *   立方体在 mapping 档与墙**共用同一份材质实例**（皇上旨 2026-10-02），⇒ 朝向跟着墙 = BackSide，
+     *   另两档（blend / selected）另建一份 mapping 并显式拉回 DoubleSide（见渲染器 `_applyDisplayMode`；预览自 10-07 旨起与编辑态同口径）。
+     * ⚠️ 若实测房间内反而看不到墙（几何法线朝向与预期相反），把这里的 BackSide 换成 FrontSide 即可（一行）。
+     */
+    private _wallSideToThree;
+    /** 设置墙体正反面显示（**材质 side 的唯一写入口**；参数保留兼容，当前无论传什么都渲染**反面**，见 _wallSideToThree） */
+    setWallSide(side: WallSide): void;
+    /** 由 wallPoints / wallHeight / wallClosed 重建墙体几何：侧面(ExtrudeMesh) + 上下封盖(ShapeGeometry) */
+    private rebuildWallGeometry;
+    /**
+     * 设置某个三角面（faceIndex）归属的全景全局序号；-1=清除（序号模式下显示深灰兜底色）。
+     * 更新映射数组 + 几何 aPanoIndex 属性（仅该面 3 顶点），并同步 XZ 索引供后续改墙保留。
+     */
+    setFacePanoIndex(faceIndex: number, globalIndex: number): void;
+    /** 重建 XZ 索引（映射变化后调用，保证下次改墙按位置保留） */
+    private _rebuildXZMap;
+    /** 三角面总数（= 几何顶点数 / 3，因非索引三角形汤） */
+    getFaceCount(): number;
+    /**
+     * 返回被三角面引用的全景全局序号集合（去重），按引用面数降序、最多 maxSlots 个。
+     * ⚠️ 2026-10-03 起**不在喂料路上**（墙那 8 格改由槽位名册决定，见 `feedFaceMapping`）；保留为公共查询 API
+     *   （外部若要按「哪几张全景被指派得最多」统计仍可用），⛔ 不许再拿它决定 shader 装哪几张。
+     */
+    getReferencedPanoIndices(maxSlots: number): number[];
+    /** 仅重建 aPanoIndex 几何属性（映射数据变化、几何未变时调用，避免整面重建） */
+    rebuildPanoIndexAttribute(): void;
+    /** 从 textures 各矩阵平移分量（elements[12,13,14]，即墨卡托投影中心）派生 panoCenters（每全景 xyz）。
+     *  全景点位置与纹理图片加载解耦，纯几何；智能序号只依赖这份数据。 */
+    protected _syncPanoCenters(): void;
+    /**
+     * 写 aPanoCenter 几何属性：每三角面 9 数（该面归属全景的中心 xyz，复制到 3 顶点），
+     * itemSize=3、count = position.count，与 position **完全对齐**
+     * （皇上旨 2026-09-30 第③点：「每个三角面 9 个数一组，全景也按 9 数一组、和顶点数组长度对齐」）。
+     * 源 = panoCenters（每全景 xyz）；面未映射（gi<0 或越界）填 0。
+     * rebuildWallGeometry / rebuildPanoIndexAttribute / setFacePanoIndex 都会调它保持同步。
+     */
+    private _syncPanoCenterAttr;
+    /** 设置纹理列表并激活第一个（或最近的）纹理 */
+    setTextures(textures: MktTextureInfo[]): void;
+    /** 追加一个纹理 */
+    addTexture(info: MktTextureInfo): void;
+    /** 删除一个纹理；若删除的是当前激活纹理则回退，索引随之前移 */
+    removeTexture(index: number): void;
+    /**
+     * 更新单个纹理的 url / 名称 / 矩阵；若改的是「当前激活纹理」则同步生效。
+     *
+     * ⚠️ 需求铁律（防止回归）：墙面绘制的是「当前激活纹理」，其朝向由 shader 的 textureMatrix uniform 决定。
+     * 所以只要激活纹理的位置/旋转变了，必须**立即**把新矩阵 copy 进 textureMatrix uniform——
+     * 否则用户旋转/移动全景球时，平面纹理不会跟着一起转。
+     * 另：改旋转不要触发纹理网络 reload，只有 url 真正变化才重载。
+     */
+    setTexture(index: number, opts: {
+        url?: string;
+        name?: string;
+        matrix?: Matrix4;
+        tiles?: string[];
+    }): void;
+    /**
+     * 把 inverse(matrixWorld) 写进当前材质的 uProjInvMatrix（每帧一次）—— 「投影与自身变换解耦」的唯一写入点。
+     *
+     * ⚠️ 需求铁律（皇上旨 2026-09-19）：「墙的矩阵和全景的矩阵是相对的，无论 MktMesh 模型整体
+     * 怎么移动/旋转/缩放，墙上的纹理都保持不变」。
+     * 达成条件是「取样方向的两个操作数都对 MktMesh 的整体变换免疫」：
+     *   · 全景点矩阵（textureMatrix）是**世界矩阵**、属独立于 MktMesh 的外部数据 → 本就不随它动；
+     *   · 墙顶点经 modelMatrix 升到世界坐标 → **会**随它动 → 一个动一个不动，方向即变，纹理在墙上滑动。
+     * 故此处把 inverse(matrixWorld) 交给着色器，把墙顶点也拉回「与整体变换无关的几何局部坐标」，
+     * 两个操作数双双免疫，方向恒定，纹理稳稳贴在墙上。
+     * ⚠️ M ≠ I 时 vProjPos（局部）与 textureMatrix（世界）并不在同一空间 —— 这是**刻意**的：
+     *    皇上要的是「纹理贴在墙上不动」，条件是「两个操作数都不随 M 变」，而非「同处一个空间」。
+     *    千万别"好心"再去把 textureMatrix 也乘一遍 inverse(matrixWorld)，那会让纹理重新动起来。
+     *
+     * 每帧无条件重算（一次 4x4 求逆，代价可忽略）：用户拖预览变换面板时 matrixWorld 每帧都在变，
+     * 靠「变更时通知」容易漏，无条件同步最稳。材质被替换（如编辑态 blend↔single 重建）时按当前材质重新取
+     * uniform，故 **MktDevMesh 也必须每帧调用本方法**（它同样会重建材质，见该类 onBeforeRender 注释）。
+     * 材质没有该 uniform（旧材质/第三方材质）时静默跳过 —— 退化为「世界坐标」的旧行为。
+     */
+    syncProjInvMatrix(): void;
+    /** 每帧算「离**名册锚点**最近」的水平距离（XZ）⇒ 走**槽位名册**（中心 ± 邻居）⇒ 名册中心变化时切换激活纹理。
+     *  ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入的轨道注视点）；
+     *  没注入（如发布页那一路）才回落相机位置。 */
+    updateTexture(camera: Camera): void;
+    /** 给纹理地址追加 OSS 图片缩放参数（1024 / 2048 / 空=不缩放）。
+     *  尺寸由外部 setOssSize 控制（默认 1024，与编辑器渲染器 resolveOssUrl 语义一致）；
+     *  预览/发布库经 setOssSize 注入，使全景球按所选尺寸加载。
+     *  ⚠️ `original=true`（这一槽喂的是**真瓦片地址**，即 rt 虚拟键那一路）时**一律走原图**、不拼尺寸参数
+     *  （皇上旨 2026-09-23「切换到4片瓦片的时候, 就不需要设置oss 尺寸参数了, 默认使用原图」）。
+     *  判据与喂地址、写 `uPanoTiled` 同源（`mktPanoTiledFlag`），别另算一套。 */
+    private resolveOssUrl;
+    /** ⭐ 皇上旨 2026-10-07 第二十一道旨：把「用哪些全景球」那把尺子的锚点从相机位置换成**控制器中心点**。
+     *  消费方（预览弹窗）把轨道控制器的 `target` 交进来即可；传 `null` = 回落相机位置（老口径，发布页照旧）。
+     *  存引用不存副本 ⇒ 轨道控制器原地改那个 Vector3，设一次就一直跟着走。 */
+    setRosterCenter(center: Vector3 | null): void;
+    /** 设置纹理 OSS 缩放尺寸（1024 / 2048 / 空=原图）；变化即按新尺寸重载当前激活纹理。
+     *  编辑器 MktDevMesh 关闭了 activateTexture（activeIndex=-1），此处为 no-op；预览/发布库用基类激活，会真正按新尺寸重载。 */
+    setOssSize(size: "1024" | "2048" | ""): void;
+    /** ossSize 换档后重载「加载地址拼了尺寸参数」的那批条目（与编辑态 `_reloadFloorTextures` 同口径：
+     *  dispose + 删条目，下一帧 `_peekTileAt` 自然按新档重拉）。
+     *  ⚠️ 真瓦片（现行 32 片/全景）一律走原图 ⇒ 不在重载范围；整图档才受尺寸档影响（皇上旨 09-23）。 */
+    private _reloadActiveTexture;
+    /** 换绑一个点槽的左右 2 张拼合槽纹理：策略全在 `./panoSlotBind`（皇上旨 10-03「整套搬进库」⇒ 编辑器与库**同一份**），
+     *  这里只把本类的取图口与占位纹理注入进去。返回 true = 图与点位配好了（调用方才写投影矩阵）。 */
+    private _bindSlotTiles;
+    /** 本材质「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的账本（⚠️ 账本实体在 `./panoSlotBind`，
+     *  与编辑态共一本，按材质实例分键 ⇒ 两处材质不同实例、天然不串味）。 */
+    private _tileKeys;
+    /** 按缓存键要一张**已经设进 shader** 的纹理：没有就当场发起下载（异步代码一律不进全局队列 —— 皇上旨 2026-09-25），
+     *  解码完还没上传的排一个「只干上传那一句」的队列项；两关都过了才返回给它去绑。
+     *  ⭐ `rt:` 虚拟键（32 瓦片拼合槽）走拼合器 peek；⛔ 不在这里 pump（每帧驱动点唯一，见 `updateTexture`，
+     *    否则一帧画好几格 = 把「每帧只载入一张新纹理」那道闸从后门拆了）。 */
+    private _peekTileAt;
+    /** 真正发起一张瓦片纹理的加载（`key` = 原始地址；rt 虚拟键由 `_peekTileAt` 上半段拦走，不会到这里）。
+     *  ⚠️ 皇上旨 2026-09-28「加载瓦片的时候, 瓦片纹理不需要添加 oss 的参数」⇒ 真瓦片（`original=true`，现行 32 片/全景）走原图，
+     *     整图档才按 ossSize 档缩（`resolveOssUrl`）。 */
+    private ensureTileTexture;
+    /** ⭐ 把一张「已经加载解码好」的纹理排进全局队列，排到的那个 tick 只做一件事：把它上传到 GPU。
+     *  皇上旨 2026-09-25 原文：「队列里面的代码就是 把加载好的纹理 设置给 shader 的 这一句代码」——
+     *  所以下载、淘汰、绑定判断统统不许出现在回调里。
+     *  ⚠️ 去重闸门必须是自己的 `_uploadQueued`：`addWork` 用 `workList.includes(work)` 判重，而每次都是新闭包 ⇒ 判不出来。
+     *  ⭐ 皇上旨 2026-10-05：「你在调用 addWork 的时候，再调一次 addWork 传入一个空函数，这样真正需要执行的方法就会隔一帧执行」
+     *  ⇒ 真活前面先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 多一格 = 晚一帧），与编辑态 `_commitTileToShader` 同一口径。
+     *  ⚠️ 空函数**必须内联每次现造**：`addWork` 按引用判重，共用一个常量引用时第二张起空格进不了队列 ⇒ 改动静默失效。 */
+    private _commitTileToShader;
+    /** 队列回调的全部内容：把这一张纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的），每 tick 一张。 */
+    private _uploadTileTexture;
+    /**
+     * 序号直接取模式喂食（皇上旨 2026-09-28 决策③：MktMesh 基类只有这一种模式）。
+     * ⭐ 皇上旨 2026-10-03「1.可以」：shader 各槽装的是**槽位名册**那 `MKT_PANO_MAX_SLOTS` 张（`_slotPanos`，
+     *   中心 ± 邻居，与编辑态 `mktMeshEditRenderer.feedFaceMapping` 同一份算法、同一个死区常数）
+     *   ⇒ 预览/发布与编辑器同一屏装同一批全景。⛔ 不再按「被引用面数取前 4」（那是 09-28 的静态名单，
+     *   与相机无关 ⇒ 走近的景点进不了槽，正是他这次报「预览里 shader 不对」的根因）。
+     * 片元按 aPanoIndex 在 panoIndices 里找对应 slot 取纹理；指派的那张不在当前名册里 ⇒ 该面回落 `uFaceMissingColor` 深灰，
+     * 把**名册锚点**挪近那张景点后自动出图（⭐ 10-07 第二十一道旨：预览轨道模式 = 控制器中心点，第一人称/未注入 = 相机位置；与编辑态同一份已知代价）。
+     */
+    feedFaceMapping(): void;
+    /** 设置全景纹理形态（tiled=8×4 三十二片走拼合器 / whole=一整片原图）；非法值回落 tiled。
+     *  ⭐ 10-03 旨⑤：这里**不再**手工重载纹理 —— 形态一变目标地址就变了（瓦片 URL ↔ 整图 URL），
+     *     下一帧 `feedFaceMapping` 里共用的那份 binder 见「槽内现有形态 ≠ 目标形态」自动走整档判齐、一次换绑并同帧翻标记。
+     *  编辑器 MktDevMesh 走的是自己那路（同一个 binder、同一份策略），本方法对它只是记下形态。 */
+    setPanoTexMode(mode: PanoTexMode): void;
+    /**
+     * 记下「当前激活（名册 0 号槽 = 中心）是第几个全景」。
+     * ⭐ 皇上旨 2026-10-03 旨②：预览立方体已与墙**共用同一份材质**，原来那句「把中心那几张抄给立方体单全景材质」
+     *   的 `currentTiles` 旁路整条删除 ⇒ 本方法不再加载瓦片、不再写 `uPanoTiled`（形态标记归 binder 逐槽写，
+     *   地址/标记/分辨率三者同源的判据在 `feedFaceMapping`）。留着它是因为 `updateTexture` 用它做「中心换人」的闩锁，
+     *   且它是发布态的公共 API（外部只读 `activeIndex` 靠这里维护）。
+     */
+    activateTexture(index: number): void;
+    /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵） */
+    exportData(): MktMeshData;
+    /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理 */
+    importData(data: MktMeshData): void;
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+    dispose(): this;
+}