three-base 2.0.134 → 2.0.142

package/MktMesh/mktShader.d.ts

@@ -0,0 +1,263 @@
+import { DataTexture, Matrix4, ShaderMaterial } from "three";
+/** 诊断配色是否开启（应用层据此把全景点标记染成同色板，两边对得上） */
+export declare const MKT_PANO_TINT_ON: boolean;
+/**
+ * 🔬 **编辑器这一页**该不该有近白远黑图：**默认关**（皇上旨 2026-09-27 晚「把颜色换成纹理，全景的纹理」——
+ *      灰阶诊断盖住了真投影，默认让位给全景纹理；要看诊断图 URL 显式写 `panoDist=1`，`#` 前后都认）。
+ * ⚠️ 这是个**纯查询**（不改任何全局状态）：应用层每建一份材质调一次，传进 `createMktFloorBlendShaderMaterial({ panoDist })`。
+ *      ⛔ 不要图省事改成「调一次翻全局」—— 静态字段上的材质在模块求值期就建好了，翻不到它（见上面第 ② 版事故）。
+ * ⚠️ URL 解析只留库侧这一处（与 `panoDebugOn` 同族口径），⛔ 应用层不许再各解一遍。
+ */
+export declare function mktPanoDistEditorOn(): boolean;
+/** 末尾 4 色（红/绿/蓝/黄）：景点数 > 20 时循环取用 */
+export declare const MKT_PANO_TINT_HEX: readonly number[];
+/** 「第 i 个**景点**」的诊断色（按景点序号，不是槽位）：0~19 各一色，>=20 循环末尾 4 色 */
+export declare function panoTintHex(i: number): number;
+/**
+ * 写入诊断色 uniform（**仅 `?panoTint=1` 时这些 uniform 才存在**，关态本函数直接空转 ⇒ 线上零开销）。
+ *
+ * 为什么色相改走 uniform、不再编译期按槽位写死（皇上旨 2026-09-25「每个全景点的叠加色都是红色，我想要让他们的颜色不一样」）：
+ *   槽位不等于景点。融合材质下「第 i 槽 = 第 i 个点」（09-25 去相机化定论）时才恰好相等，
+ *   而「仅映射选中的那一个」模式下地板永远只喂**选中那一张到 0 号槽** ⇒ 按槽写死 = 无论选第几个点都涂红，
+ *   且那个模式下的墙/家具是另一份单全景材质（压根没有染色段）⇒ 墙一点色都没有。两处同一个错。
+ * 故应用层在**每次往某个槽写全景时**顺手写「这个槽里躺的是第几个景点」的颜色：
+ *   - 融合材质：`uPanoTintColors[slot]`（vec3 数组）
+ *   - 单全景材质：`uPanoTint`（vec3，整面恒为选中的那一个，slot 恒 0）
+ * 材质没有这些 uniform（关态 / 旧材质 / 误传）时静默跳过，不抛错。
+ */
+export declare function setMktPanoTint(material: ShaderMaterial | null | undefined, index: number, slot?: number): void;
+/**
+ * 写入距离明暗诊断图的**黑端距离**（米）：材质上没有这根 uniform（那份材质建时就没开这张图 / 误传）时静默跳过。
+ * ⚠️ 判据只看**材质自己有没有** `uPanoDistMax`，⛔ 不再读全局 `PANO_DIST_ON`：编辑器那三份材质是显式传 `panoDist`
+ *      建出来的（全局开关可能仍是关 —— 发布页/预览走的就是全局），拿全局判会把编辑器该喂的尺子饿掉。
+ * 传的是「多远算全黑」= 全局一把尺（应用层现场量），⛔ 不要按「每个槽各自」给 —— 跨面可比才读得出远近。
+ */
+export declare function setMktPanoDistRange(material: ShaderMaterial | null | undefined, meters: number): void;
+/**
+ * 写入距离明暗诊断图的**圆心清单**（皇上旨 2026-09-27「shader 里面有四个全景点的坐标, 每个像素点都判断距离 4 个全景点
+ * 的距离中最小的那个值, 然后用这个值来设置颜色」）：一条 = 一个全景点的世界矩阵（只取平移列），空位传 null。
+ * ⛔ 不要拿 `weights` 当这份清单：`weights[i]` 说的是「第 i 格的**瓦片绑好了没**」（没绑好给 0 是防止拿 1×1 占位图
+ *      刷一片素灰，09-25 线上抓到的病灶），而本数组说的是「第 i 格**有没有一个点**」。
+ *      两者在「景点已放置、图还在下载」那段时间里就是不一样 ⇒ 明暗图按点数画圆，取图仍按绑好的那几张。
+ * ⚠️ 材质上没有这根 uniform（那份材质建时没开这张图 / 误传）时静默跳过，与 `setMktPanoDistRange` 同口径。
+ */
+export declare function setMktPanoPoints(material: ShaderMaterial | null | undefined, matrices: (Matrix4 | null | undefined)[]): void;
+/**
+ * 多全景地面融合着色器的顶点着色器（**地板 / 墙体 / 立方体 三者共用同一份**）。
+ * three.js 渲染 InstancedMesh 时会自动定义 USE_INSTANCING 宏并注入 instanceMatrix / instanceColor，
+ * 同一份代码因此同时服务两类网格：
+ *  - 普通 Mesh（墙/地板）：无实例矩阵，im 退化为单位阵；
+ *  - InstancedMesh（家具立方体，InstancedChild 合批）：im = instanceMatrix，各实例世界变换在其中。
+ * 故「地板/墙体/立方体」共用这一个着色器，无需为立方体另写实例化版（消除原先的 instanced 分支）。
+ * instanceColor（逐实例染色，选中高亮）同样用 USE_INSTANCING_COLOR 宏在顶点→片段间传递。
+ */
+/** ⭐ 32 瓦片拼合（2026-10-06 晚皇上旨：一张全景切 **横 8 × 竖 4 = 32 片**，每 **4×4 = 16 片**离屏拼成
+ *  1 张 **4096×4096 正方形**槽纹理，**左右 2 槽**组成完整全景；上一版是同日早些时候的 8×8 = 64 片 / 4 槽
+ *  2×2 象限，再上一版是 09-29 旨的 4×4 = 16 片）的「槽虚拟地址」前缀。
+ *  虚拟键不是真 URL，纹理由 `PanoTileStitcher` 用 shader 逐格画进 `WebGLRenderTarget` 提供，
+ *  消费方（基类 `_ensurePanoTiles` / 编辑器 `_peekTileAt`）见前缀即走拼合器，⛔ 不得当 URL 下载。
+ *  ⚠️ 键协议 `rt:<batch>#<slot>` 与 `uPanoTiled` 这套对外接口**一字未改** —— 变的只有「每批几条地址」
+ *  和「槽怎么分」；`slot` 的取值范围从 0..3 缩到 0..1，消费方一律用 `RT_STITCH_SLOT_COUNT` 取，不许写死。
+ *  ⚠️ 旧存档不兼容（皇上 2026-10-06 拍板）：存档里 64 条瓦片地址会因张数超限被判废 ⇒ **老项目需重新上传**。 */
+export declare const RT_STITCH_KEY_PREFIX = "rt:";
+/** 原图**横向**（经度方向 u）切几片（旨「横 8」） */
+export declare const RT_STITCH_COLS = 8;
+/** 原图**纵向**（纬度方向 v）切几片（旨「竖 4」）⇒ 竖着不再分块，一个 RT 就装下整幅的上下 180° */
+export declare const RT_STITCH_ROWS = 4;
+/** 一个批次（= 一个全景点）的瓦片总数 = 8 × 4 = 32；`tiles` 存档数组的硬上限 */
+export declare const RT_STITCH_TILES_PER_BATCH: number;
+/** 一个拼合槽每边几格（旨「每个 RT 由 16 个全景瓦片组成」⇒ 4×4 = 16）*/
+export declare const RT_STITCH_SLOT_GRID = 4;
+/** 一个拼合槽的格数 = 4² = 16（画满 16 格 = 这一槽齐活） */
+export declare const RT_STITCH_CELLS_PER_SLOT: number;
+/** 拼合槽个数 = **左右 2 槽**（旨「每个全景纹理由左右 2 个 RT 组成」）⇒ 一个全景点只占 **2 个 sampler**。
+ *  ⛔ 别以为 32 片就要 32 个 sampler：皇上本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 16 = 2 槽 × 8 景点，
+ *  这一条是硬顶，也是「必须拼进 RT」而不是「直接喂瓦片」的根本原因。
+ *  ⭐ 分块口径：槽 0 = **左半幅**（列 0-3、行 0-3）、槽 1 = **右半幅**（列 4-7、行 0-3），
+ *    即「只按 u 分左右，v 不再分上下」⇒ 每槽覆盖 **横向 180° × 纵向 180°**，是原图左/右半个**正方形**
+ *    ⇒ 槽纹理必须跟着变正方形（见下 `RT_STITCH_SLOT_W/H`），否则纵向被压 2 倍。 */
+export declare const RT_STITCH_SLOT_COUNT = 2;
+/** 单槽像素尺寸 **4096×4096 正方形**（皇上 2026-10-06 拍板保画质）：2 槽 = 有效分辨率 8192×4096。
+ *  ⚠️ 为什么必须变正方形：每槽覆盖的原图区域从「横 180° × 竖 90°（2:1）」变成「横 180° × 竖 180°（1:1）」，
+ *     RT 若仍是 4096×2048 ⇒ 纵向缩放比是横向的 2 倍、**纵向分辨率腰斩**，直接踩「不降质」红线。
+ *  每格 = 1024×1024；一片瓦片的原图边长 = 横 W/8、竖 H/4 ⇒ 横向缩放比 = (W/8)/1024 = 1.4533（11904 宽原图），
+ *  与 64 片那一版**逐字相同** ⇒ 本次改版**不涨也不降画质**；变的是同屏全景数 4 → 8、
+ *  单全景下载片数 64 → 32（减半）、单全景 RT 显存 128MB（不变，只是从 4 张 32MB 变 2 张 64MB）。
+ *  ⚠️ 红线（「千万不要降低质量」）：这两个数与「原图切几片」无关，⛔ 不许当成省显存的旋钮去缩。 */
+export declare const RT_STITCH_SLOT_W = 4096;
+export declare const RT_STITCH_SLOT_H = 4096;
+export declare const floorVertexShader = "\n    #include <common>\n    #include <logdepthbuf_pars_vertex>\n\n    // \u6295\u5F71\u7A7A\u95F4\u9006\u77E9\u9635\uFF1A\u89C1\u5355\u5168\u666F\u9876\u70B9\u7740\u8272\u5668\u5904\u7684\u540C\u4E00\u6BB5\u8BF4\u660E\uFF08\u7687\u4E0A\u65E8 2026-09-19\uFF09\u3002\n    // \u9ED8\u8BA4\u4FDD\u6301\u5355\u4F4D\u9635\uFF08\u5730\u677F / \u7ACB\u65B9\u4F53\u884C\u4E3A\u4E0E\u6539\u9020\u524D\u5B8C\u5168\u4E00\u81F4\uFF09\uFF1B\u7F16\u8F91\u5668\u5899\uFF08MktDevMesh\uFF09\u4E0E\u53D1\u5E03\u6001 MktMesh\n    // \u4E00\u6837\u6BCF\u5E27\u5199\u5165 inverse(matrixWorld)\uFF0C\u6545\u5899\u4E0A\u7684\u7EB9\u7406\u540C\u6837\u4E0D\u968F\u6574\u4F53\u53D8\u6362\u6F02\u79FB\u3002\n    uniform mat4 uProjInvMatrix;\n\n    // \u5168\u666F\u5E8F\u53F7\u6620\u5C04\u6A21\u5F0F\uFF1A\u672C\u4E09\u89D2\u9762\u5F52\u5C5E\u7684\u5168\u5C40\u5168\u666F\u5E8F\u53F7\uFF08\u6765\u81EA geometry \u7684 aPanoIndex\uFF1B\u65E0\u6B64 attribute \u7684\u5BF9\u8C61\u6052\u4E3A 0\uFF0C\u4EC5 mode=1 \u65F6\u8BFB\u53D6\uFF09\n    attribute float aPanoIndex;\n    varying float vPanoIndex;\n\n    varying vec3 vProjPos;\n    // \u53D6\u56FE\u300C\u6B63\u9762\u5939\u89D2\u300D\u5224\u636E\u7528\uFF08\u7687\u4E0A\u65E8 2026-09-27 \u6DF1\u591C\uFF09\uFF1A\u51E0\u4F55\u6CD5\u7EBF\uFF0C\u53D8\u6362\u5230\u4E0E vProjPos **\u540C\u4E00\u7A7A\u95F4**\n    // \uFF08uProjInvMatrix * modelMatrix * instanceMatrix \u7684\u65CB\u8F6C\u90E8\u5206\uFF09\uFF0C\u7247\u5143\u91CC\u4E0E\u300C\u70B9\u2192\u5168\u666F\u300D\u5411\u91CF\u70B9\u79EF\u7B97\u5939\u89D2\u3002\n    // \u26D4 normal \u662F three.js \u81EA\u52A8\u6CE8\u5165\u7684\u6807\u51C6 attribute\uFF08\u5899=computeVertexNormals \u9010\u9762\u6CD5\u7EBF / \u5C01\u76D6=ShapeGeometry /\n    //    \u5730\u677F=PlaneGeometry / \u5BB6\u5177=BoxGeometry\uFF09\uFF0C\u6B64\u5904\u65E0\u9700\u81EA\u5DF1\u58F0\u660E\u3002\n    varying vec3 vWNormal;\n    #ifdef USE_INSTANCING_COLOR\n    varying vec3 vInstanceColor;\n    #endif\n\n    void main() {\n        // \u5B9E\u4F8B\u77E9\u9635\uFF1AInstancedMesh \u81EA\u52A8\u5B9A\u4E49 USE_INSTANCING \u5E76\u63D0\u4F9B instanceMatrix\uFF1B\n        // \u666E\u901A Mesh\uFF08\u5899/\u5730\u677F\uFF09\u65E0\u5B9E\u4F8B\u77E9\u9635\uFF0C\u9000\u5316\u4E3A\u5355\u4F4D\u9635 \u2014\u2014 \u4E00\u4EFD\u7740\u8272\u5668\u540C\u65F6\u670D\u52A1\u5899/\u5730\u677F/\u7ACB\u65B9\u4F53\u3002\n        #ifdef USE_INSTANCING\n            mat4 im = instanceMatrix;\n        #else\n            mat4 im = mat4(1.0);\n        #endif\n        // \u6A21\u578B/\u5B9E\u4F8B\u5C40\u90E8\u5750\u6807\uFF1B\u7ACB\u65B9\u4F53\u5B9E\u4F8B\u7684\u53D8\u6362\u5728 instanceMatrix\uFF0C\u5899/\u5730\u677F\u5728 modelMatrix\n        vec4 modelPos = im * vec4(position, 1.0);\n        vProjPos = (uProjInvMatrix * modelMatrix * modelPos).xyz;\n        // \u6CD5\u7EBF\u4E0E vProjPos \u8D70\u540C\u4E00\u6761\u77E9\u9635\u94FE\uFF08mat3 \u53D6\u65CB\u8F6C/\u7F29\u653E\u90E8\u5206\uFF0C\u7247\u5143\u91CC normalize \u62B5\u6D88\u7F29\u653E\uFF09\n        vWNormal = mat3(uProjInvMatrix * modelMatrix * im) * normal;\n        // \u5168\u666F\u5E8F\u53F7\u6620\u5C04\u6A21\u5F0F\uFF1A\u628A\u672C\u4E09\u89D2\u9762\u7684\u5F52\u5C5E\u5E8F\u53F7\u4F20\u7ED9\u7247\u5143\uFF08geometry \u65E0 aPanoIndex \u7684\u5BF9\u8C61\u6052\u4E3A 0\uFF0C\u4EC5 mode=1 \u65F6\u8BFB\u53D6\uFF09\n        vPanoIndex = aPanoIndex;\n\n        #ifdef USE_INSTANCING_COLOR\n            vInstanceColor = instanceColor;\n        #endif\n\n        gl_Position = projectionMatrix * modelViewMatrix * modelPos;\n\n        #include <logdepthbuf_vertex>\n    }\n";
+/** 1×1 白色占位纹理：panorama 在尚未激活任何纹理前使用，避免空纹理采样报错 */
+export declare function createPlaceholderTexture(): DataTexture;
+/**
+ * 全景纹理形态（皇上旨 2026-09-22「全景球可以切成 4 片和一整片，两者效果很不一样，做个功能可以切换」）。
+ *
+ *   "tiled" = 2 个 sampler 各装一张**离屏拼合好的槽纹理**（原图 **8×4 = 32 片**，每 16 片拼一张；
+ *            10-06 晚旨；再早是同日的 8×8 = 64 片 / 4 槽、09-29 的 4×4 = 16 片），`uPanoTiled` 写 1；
+ *   "whole" = 2 个 sampler 都装**同一张完整等距柱状原图**，`uPanoTiled` 写 0（改用全图 UV）。
+ *
+ * ⚠️ 两种形态在**几何上应当逐像素一致**（`panoU/panoV` 的还原式就是恒等式，见文件头 🧩 段与
+ *    `test/panoVMapping.test.js` 的等价性数值证明）。所以线上若看着「很不一样」，差异只可能来自下面两条，
+ *    与本切换功能无关、也不会被它修掉：
+ *      ① **分辨率**：`x-oss-process=image/resize,m_lfit,w_<ossSize>` 是**按 URL** 生效的，且 2026-09-23 皇上定
+ *        「**切片的瓦片不走该尺寸档，默认用原图**」（每片本就只有原图的 1/8 边长，再按档缩是二次损失）⇒
+ *        判据 = `mktPanoTiledFlag(...)===1`（喂地址与写 `uPanoTiled` 同源，见 `resolveOssUrl` 两处）。
+ *        于是 tiled 态 = 拼合槽纹理**逐片取自原始分辨率**瓦片（合计像素≈整张原图，10-06 那版仍是 8192×4096 等效），
+ *        whole 态 = 整图按档（w_1024 ⇒ 等效 1024×512）。
+ *        ⚠️ 两档清晰度差**不是固定的倍数**，而取决于「原图宽 ÷ 所选档位」；又因 `m_lfit` 只缩不放，
+ *        原图宽 ≤ 2×档位时 whole 态其实也没被缩，两态清晰度自然接近 —— 别把这当成「切换坏了」。
+ *      ② **瓦片边界**（10-06 晚切 32 片后这一条分两层，⚠️ 口径不同）：
+ *        · **拼合槽之间**（u=0.5 那一竖；⭐ v=0.5 不再有横缝 —— 竖着已不分块）：2 张槽是 2 张独立纹理，
+ *          各自 mip + ClampToEdge ⇒ 仍可能有细亮/细暗线，这一条**与 09-29 那版一字未变**，
+ *          `RT_STITCH_SEAM_MARGIN_PX` 管不到它（它治的是「同一张纹理内」的格子边界）；
+ *          whole 态是同一张贴图，天然无此缝。
+ *        · **拼合槽内部**（每张 4096×4096 里的 3 横 3 竖格子线，16 片时代只有 1 横 1 竖）：
+ *          靠「上传多切 `RT_STITCH_SEAM_MARGIN_PX` 像素 + 拼合只采中间那块」消掉，见该常量的说明。
+ *
+ * 旧数据 / 种子图没有 `tiles`（或只有 1 条）⇒ 两种形态都只能退回整图，`whole` 与 `tiled` 表现相同。
+ */
+export type PanoTexMode = "tiled" | "whole";
+/** 形态合法值（序列化 / 反序列化单一来源，勿在别处另立字面量） */
+export declare function isPanoTexMode(v: unknown): v is PanoTexMode;
+/** 缺失格涂灰（09-29 晚旨「不足张数缺的地方涂灰，一眼看出数据不全」）。
+ *  取 #767676 ≈ mapping 模式 `uFaceMissingColor`（线性 0.18）的 sRGB 值，两处观感一致。
+ *  10-06 起拼合器只有一份（canvas 那一份奉旨删除）⇒ 常量搬到本文件当唯一来源。 */
+export declare const MISSING_TILE_GRAY = "#767676";
+/** 接缝余量（**原图像素**，每片向四边各多切这么多；贴原图边那侧裁到剩多少算多少）。
+ *
+ *  10-06 槽内改成 4×4 = 16 格 ⇒ 一张槽内部的接缝从旧版的 1 条十字变成 **3 横 3 竖**，这一条是随之而来的画质护栏：
+ *   ① 上传时每片**向四边多切 M 像素**（`rtStitchTileRects`）；
+ *   ② 拼合时**只采中间那块**（`rtStitchTileInset` 算出的 UV 内缩窗口），多切的那一圈**不画进格子**。
+ *
+ *  为什么这样就没了细亮/细暗线：缝的病根是「双线性 / mipmap 在瓦片边界外拿不到邻居像素，只能复制自己的
+ *  边缘像素」（就是 `PanoTexMode` 文件头 ② 那条）。多带的 M 像素就是**真的邻居像素**，插值不再靠复制。
+ *
+ *  M 取 8 够不够：一格 1024×1024px、一片原图 1488×1488px（横 W/8、竖 H/4）⇒ 两个方向都是 1.45× 缩小，
+ *  三线性 mip 的 footprint 半径最大约
+ *  `2 × 1.45 ≈ 3` texel ⇒ 8px 有 ≈2.7 倍余量；再小一档（4px）也够用，取 8 是给「原图比 8192 窄 ⇒ 格子
+ *  反而在放大」那类点留边界。**代价**：每片文件比「正好 1/8」宽 16px、高 16px（≈ +4% 面积），⛔ 不是降质。 */
+export declare const RT_STITCH_SEAM_MARGIN_PX = 8;
+/** 32 瓦片批次的标识 = 第一条**非空**瓦片地址（同批上传 URL 前缀一致，足以唯一；
+ *  09-29 晚旨「不足张数缺的地方涂灰」后批次里允许有空串占位 ⇒ 取首个非空，防首张缺失时键为空串互撞） */
+export declare function rtStitchBatchOf(tiles: string[]): string;
+/** 某一拼合槽的虚拟键：`rt:<batch>#<slot>` */
+export declare function rtStitchKey(batch: string, slot: number): string;
+/** 是否拼合槽（`rt:<batch>#<slot>`）的虚拟键 —— 16 片 / 64 片 / 现行 32 片**同一个前缀**，键本身不含片数信息 */
+export declare function isRtStitchKey(key: string): boolean;
+/** 解析虚拟键 → { batch, slot }；非 rt 键返回 null */
+export declare function rtStitchKeyParts(key: string): {
+    batch: string;
+    slot: number;
+} | null;
+/** 槽 slot 用哪 16 张瓦片（原图 **8 列 × 4 行 行优先**下标 `r*8+c`；**槽内格序 = 4×4 行优先、图像左上起**）：
+ *  槽 0 = 图像**左半幅**（行 0-3 × 列 0-3）→ `[0,1,2,3, 8,9,10,11, 16,17,18,19, 24,25,26,27]`；
+ *  槽 1 = **右半幅**（行 0-3 × 列 4-7）→ `[4,5,6,7, 12,13,14,15, 20,21,22,23, 28,29,30,31]`。
+ *  ⭐ 竖着**不再分块**（皇上旨「每个全景纹理由左右 2 个 RT 组成」）⇒ 两个槽**都是全高**，只按 u 分左右，
+ *    故槽纹理也必须跟着变正方形（见 `RT_STITCH_SLOT_W/H` 那条注释，⛔ 别只改这里漏了那边）。
+ *  ⚠️ 表是**从上面那几个网格常数生成**的（⛔ 手抄 32 个数）：正确性由护栏 `test/mktmesh.test.js` BE 组
+ *  对着手写死的字面量逐个数断言 —— 改了网格常数而护栏没跟着改，当场红。 */
+export declare const RT_STITCH_SLOT_TILES: ReadonlyArray<ReadonlyArray<number>>;
+/** 槽内第 cell 格在**图像方向**的位置 `[列, 行]`（0 起，与 `RT_STITCH_SLOT_TILES` 的格序同一口径）。
+ *  ⚠️ 这是「图像方向」（行 0 = 图像最上），GL 的 y 向上 ⇒ 画进 RT 时 y 要翻（拼合器里那句 `1 - (2*r+1)/n`）。 */
+export declare function rtStitchCellPos(cell: number): [number, number];
+/** 一片瓦片的切图矩形（原图像素）。`sx/sy/sw/sh` = **含多切余量**的实际切片区；
+ *  `ml/mt/mr/mb` = 四边各多切了多少（贴原图边那侧被裁 ⇒ 0）。 */
+export interface RtStitchTileRect {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+    ml: number;
+    mt: number;
+    mr: number;
+    mb: number;
+}
+/** 32 片瓦片的切图矩形（行优先、图像左上起，下标 `i = r*8+c` 与 `RT_STITCH_SLOT_TILES` 同源；
+ *  ⭐ 10-06 晚旨「横 8 × 竖 4 = 32」：`r` 走 `RT_STITCH_ROWS`(4)、`c` 走 `RT_STITCH_COLS`(8)，不再相等）。
+ *
+ *  ⭐ **上传侧（`panoramaUpload`）与拼合侧（`PanoTileStitcher`）必须共用这一份几何**：
+ *  上传多切多少、拼合就内缩多少；两边各算一次就是「缝没治掉、反而把画面挤歪」。
+ *  拼合侧拿不到原图尺寸（它只有 32 个 URL 和 32 张已解码纹理），所以它用 `rtStitchTileInset`
+ *  —— 那条只需「下标 + 该瓦片自己的像素尺寸」，两者等价的前提是「多切量 = 常数 M、只有贴边那几片被裁」，
+ *  而「贴不贴边」纯由下标决定 ⇒ 护栏 BE 组用同一批 (W,H) 把两条算路对表钉死。 */
+export declare function rtStitchTileRects(w: number, h: number): RtStitchTileRect[];
+/** 这片瓦片有没有贴原图边界（8×4 ⇒ 32 片里四周那 20 片至少贴一条边；贴边的**那一侧**多切量被裁成 0）。
+ *  拼合侧靠它 + 瓦片自己的像素尺寸还原内缩量 ⇒ 不必知道原图多大。
+ *  ⚠️ 下标拆分必须按 **列数 COLS=8**（`i = r*8+c`），⛔ 不是 ROWS。 */
+export declare function rtStitchTileEdgeClip(i: number): {
+    left: boolean;
+    right: boolean;
+    top: boolean;
+    bottom: boolean;
+};
+/** 拼合时的采样窗口 = 该瓦片纹理的 UV 里「**只留基础格、丢掉多切那一圈**」的那一块，
+ *  返回 `[u0, v0, u1, v1]`（片元里 `mix(vec2(u0,v0), vec2(u1,v1), vUv)`）。
+ *
+ *  `tw/th` = 该瓦片纹理的**实际**像素宽高。内缩比例 = `M / sw`（多切那 M 像素占整片的比例），
+ *  与「文件是不是正好等于标称切片区」无关 ⇒ 编码差 1px 也不会露出邻居的格子。
+ *  贴原图边那一侧内缩 0：那里压根没多切，且那条边界就是全景自己的边（`ClampToEdge` 照旧）。
+ *
+ *  ⚠️ v 方向口径（与 `panoBitmapTexture` 绑死）：瓦片走 `imageOrientation:"flipY"` 预翻 + `texture.flipY=false`
+ *  ⇒ 纹理 **v=0 = 图像下边**，所以图像顶部余量 `mt` 落在 `v1`、底部 `mb` 落在 `v0`。搞反 = 上下颠倒。 */
+export declare function rtStitchTileInset(i: number, tw: number, th: number): [number, number, number, number];
+/**
+ * 「这 `RT_STITCH_SLOT_COUNT`(2) 个纹理槽到底喂哪几个地址」。⚠️ **必须**与 `mktPanoTiledFlag` 同源、同一时机调用：
+ * 只改标记不改地址（或反之）= 用整图 UV 去采一张瓦片 / 用瓦片内 UV 去采整图，画面立刻错乱。
+ * 非 tiled 态（或该点压根没切过片）一律回退成「各槽同为一张整图」。
+ * ⭐ 2026-10-06 晚旨「只支持 32 张（8×4）」：只要有瓦片（1~32 条）一律走拼合器（rt: 虚拟键），
+ *   不足 32 张的位置由拼合器**涂灰**（一眼看出数据不全）；8×8=64 张与 4×4=16 张那两版**都不做兼容**
+ *   （皇上「无须兼容正常使用，有异常我会重传」⇒ 旧存档的 64 条地址超张数被判废、重传即可）。
+ * ⚠️ 返回长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 2 个 rtStitchKey —— 槽数再变会漏改）。
+ */
+export declare function mktPanoTexUrls(url: string, tiles: string[] | undefined, mode?: PanoTexMode): string[];
+/**
+ * 「这 2 个纹理槽是不是真瓦片」的判据 —— **必须**与喂纹理处的回退式（`mktPanoTexUrls`）同源：
+ * `tiles` 有 **任意 1~32 条**地址（不足 32 = 数据不全，缺的格子拼合时涂灰）**且**当前形态选的是 tiled = 是瓦片；
+ * 否则各槽同为一张整图（旧数据 / 种子图 / 用户切整片）。
+ */
+export declare function mktPanoTiledFlag(tiles: string[] | undefined, mode?: PanoTexMode): 0 | 1;
+/**
+ * 写入 uPanoTiled（2026-09-22「交换 / 不交换完全一样」的修复）。
+ *
+ * 单全景材质该 uniform 是标量；融合材质是**每点一个**的数组（不同点来源可能不同），故带 slot。
+ * 材质没有该 uniform（旧材质 / 误传）时静默跳过，不抛错。
+ */
+export declare function setMktPanoTiled(material: ShaderMaterial | null | undefined, tiled: 0 | 1, slot?: number): void;
+/**
+ * 创建 MktMesh 专用的「实例化 + 等距柱状投影全景」着色器材质。
+ * panorama / textureMatrix 由 MktMesh 在运行时按「最近纹理」动态设置。
+ */
+export declare function createMktShaderMaterial(): ShaderMaterial;
+export interface MktFloorBlendOptions {
+    /** 最多参与融合的全景点数（⭐ 10-06 晚旨后每点占左右 **2** 张拼合槽纹理，纹理总数 = maxPano×2，须 ≤ 16），默认 `MKT_PANO_MAX_SLOTS`(=8) ⇒ 8×2 = 16 = 采样器硬顶 */
+    maxPano?: number;
+    /**
+     * 🔬 这一份材质要不要「距离明暗图」（近白远黑）：**不传 = 读 URL 开关 `?panoDist=1`**（发布页 / 预览就该走这条）。
+     * 编辑器三处建材质点显式传 `mktPanoDistEditorOn()`（默认开）⇒ 墙/地板/立方体**同一份源码**、同一张图。
+     * ⚠️ 只能在这里给，⛔ 没有「建完再翻」这条路：这段 GLSL 在 new ShaderMaterial 时一次性拼死。
+     */
+    panoDist?: boolean;
+}
+/** 融合材质的全景点数**上限**：每点占 **2** 张拼合槽纹理（32 片 8×4 → 左右 2 槽，每槽 4×4 格）⇒ **8 × 2 = 16 个 sampler**，再多样本编译不过。
+ *  ⭐ 2026-10-06 晚皇上旨「一次能够展示 8 个全景纹理」：靠的就是「每点从 4 槽降到 2 槽」——
+ *     sampler 总数 16 是硬件硬顶（皇上本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 16，一直没变），
+ *     原来 16 ÷ 4 槽 = 4 个景点，现在 16 ÷ 2 槽 = **8 个景点**，画质与单全景显存**分毫未动**。 */
+export declare const MKT_PANO_MAX_SLOTS = 8;
+/**
+ * 创建「多全景融合」着色器材质：每帧由外部喂入最近 maxPano 个全景点（⭐ 10-06 晚旨后每点 2 张拼合槽纹理）。
+ * 同一份着色器同时服务普通 Mesh（墙/地板）与 InstancedMesh（家具立方体）：
+ * 实例化与否由 three.js 按对象类型自动注入 USE_INSTANCING 宏决定，无需外部传 instanced 开关。
+ * 数组 uniform 在创建时即按 maxPano 长度初始化（占位纹理 + 单位矩阵 + 权重 0），运行时由渲染器每帧改写对应槽位。
+ * ⚠️ 取图口径只有一条（皇上旨 2026-09-25 晚「都要一起改」→ 09-27 晚「取用距离最近的那个全景点的瓦片纹理」定版）：
+ * 地板 / 墙 / 家具**全部**按「水平距离最近的一张」取图（09-24~09-25 的夹角门已整链删除），
+ * 不再有「地板按覆盖度融合」这条路，故也**没有** `pickNearest` 选项（旧的 0/1 分流 uniform 已删）。
+ */
+export declare function createMktFloorBlendShaderMaterial(options?: MktFloorBlendOptions): ShaderMaterial;
+/**
+ * 创建「仅显示选中全景」着色器材质（皇上旨 2026-09-29「三模式三 shader」之三）：仅编辑器使用。
+ * uniform 形状与 blend 工厂同档 ⇒ 喂料复用 feedBlendProjection 槽位指派路零改动；
+ * 本 shader 只读 0 号点槽（GLSL 写死），uFloorCoreRadius/uFloorFadeRange 喂料会写但不读（静默忽略）。
+ */
+export declare function createMktFloorSelectedShaderMaterial(options?: {
+    maxPano?: number;
+}): ShaderMaterial;