three-base 2.0.166 → 2.0.169

package/MktMesh/MktMesh.js

@@ -24,7 +24,8 @@
  * 同一时刻只激活名册 0 号槽（中心）那一个纹理（全局共享单激活方案）。
  */
 import { BufferGeometry, BackSide, Float32BufferAttribute, Matrix4, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, } from "three";
-import { createPlaceholderTexture, MKT_PANO_MAX_SLOTS, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT } from "./mktShader";
+import { createPlaceholderTexture, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT } from "./mktShader";
+import { MKT_PANO_MAX_SLOTS } from "./mktMappingShader";
 import { createMktFloorMappingShaderMaterial } from "./mktMappingShader";
 // ⭐ 皇上旨 2026-10-06：拼合 = shader 逐格画进 WebGLRenderTarget，**一份实现**（canvas 2D 那一份连同
 //    `?panoStitch=canvas` 开关整条删除）
@@ -794,7 +795,10 @@ export default class MktMesh extends Mesh {
             const p = rtStitchKeyParts(key);
             if (!p)
                 return null;
-            const tex = this._stitcher.peek(p.batch, p.slot);
+            // ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：透传 renderer,
+            //   新全景还没画进格时 peek 会**先把 RT 建出来（已涂缺失灰）并交出** ⇒ 这一帧拿到深灰底，
+            //   而非 null（null 会被 panoSlotBind 判成「判不齐」⇒ 沿用上一批 ⇒ 墙上闪上一个全景）。
+            const tex = this._stitcher.peek(p.batch, p.slot, this._glRenderer);
             if (!tex)
                 return null;
             // ⭐ 皇上旨 09-29「两个大头别在同一帧」：普通瓦片不许在 render 首绑现场 texSubImage2D ⇒ 走

package/MktMesh/MktMesh.ts

@@ -41,7 +41,8 @@ import {
     Vector3,
 } from "three";
 import type { WebGLRenderer } from "three";
-import { createPlaceholderTexture, MKT_PANO_MAX_SLOTS, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT, type PanoTexMode } from "./mktShader";
+import { createPlaceholderTexture, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT, type PanoTexMode } from "./mktShader";
+import { MKT_PANO_MAX_SLOTS } from "./mktMappingShader";
 import { createMktFloorMappingShaderMaterial } from "./mktMappingShader";
 // ⭐ 皇上旨 2026-10-06：拼合 = shader 逐格画进 WebGLRenderTarget，**一份实现**（canvas 2D 那一份连同
 //    `?panoStitch=canvas` 开关整条删除）
@@ -825,7 +826,10 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         if (isRtStitchKey(key)) {
             const p = rtStitchKeyParts(key);
             if (!p) return null;
-            const tex = this._stitcher.peek(p.batch, p.slot);
+            // ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：透传 renderer,
+            //   新全景还没画进格时 peek 会**先把 RT 建出来（已涂缺失灰）并交出** ⇒ 这一帧拿到深灰底，
+            //   而非 null（null 会被 panoSlotBind 判成「判不齐」⇒ 沿用上一批 ⇒ 墙上闪上一个全景）。
+            const tex = this._stitcher.peek(p.batch, p.slot, this._glRenderer);
             if (!tex) return null;
             // ⭐ 皇上旨 09-29「两个大头别在同一帧」：普通瓦片不许在 render 首绑现场 texSubImage2D ⇒ 走
             //    「每 tick 一张」预上传队列；没排到的帧返回 null，自动推迟绑定 ⇒ render 里从此没有首绑上传。

package/MktMesh/mktMappingShader.d.ts

@@ -1,4 +1,13 @@
 import { ShaderMaterial } from "three";
+/**
+ * ⭐ 融合材质的全景点数**上限**（皇上旨 10-06「一次能够展示 8 个全景纹理」）：每点占 **2** 张拼合槽纹理
+ *   （32 片 8×4 → 左右 2 槽，每槽 4×4 格）⇒ **8 × 2 = 16 个 sampler**，再多样本编译不过。
+ *   （sampler 总数 16 是硬件硬顶，本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 16。）
+ *
+ * ⭐⭐ 2026-10-09 皇上旨「MktMesh 只有映射一种，blend/selected 归编辑器」⇒ 该常量从 `mktShader.ts`
+ *   **搬到这里**（映射材质的所在地）。它同时是库与编辑器那份 blend 的**共同上限**，两边必须同值。
+ */
+export declare const MKT_PANO_MAX_SLOTS = 8;
 /**
  * 创建「全景序号直取」着色器材质（皇上旨 2026-09-29「三模式三 shader」之二）：
  * 编辑器「映射设置模式」的墙材质 + **基类 MktMesh（发布/预览）的固定墙材质**

package/MktMesh/mktMappingShader.js

@@ -6,7 +6,16 @@
  * 与 blend / selected 共用同一份 floorVertexShader 与同一套采样口径（改采样两处同改）。
  */
 import { BackSide, Matrix4, ShaderMaterial, Vector3 } from "three";
-import { createPlaceholderTexture, floorVertexShader, MKT_PANO_MAX_SLOTS, RT_STITCH_SLOT_COUNT } from "./mktShader";
+import { createPlaceholderTexture, floorVertexShader, RT_STITCH_SLOT_COUNT } from "./mktShader";
+/**
+ * ⭐ 融合材质的全景点数**上限**（皇上旨 10-06「一次能够展示 8 个全景纹理」）：每点占 **2** 张拼合槽纹理
+ *   （32 片 8×4 → 左右 2 槽，每槽 4×4 格）⇒ **8 × 2 = 16 个 sampler**，再多样本编译不过。
+ *   （sampler 总数 16 是硬件硬顶，本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 16。）
+ *
+ * ⭐⭐ 2026-10-09 皇上旨「MktMesh 只有映射一种，blend/selected 归编辑器」⇒ 该常量从 `mktShader.ts`
+ *   **搬到这里**（映射材质的所在地）。它同时是库与编辑器那份 blend 的**共同上限**，两边必须同值。
+ */
+export const MKT_PANO_MAX_SLOTS = 8;
 /**
  * 序号直取片元（皇上旨 2026-09-29「三模式三 shader」之二）：
  * 按三角面 aPanoIndex 在 panoIndices 槽里找对应全景纹理 —— **不看距离、不看夹角**（blend 那套打分/归约整段没有）。

package/MktMesh/mktMappingShader.ts

@@ -6,7 +6,17 @@
  * 与 blend / selected 共用同一份 floorVertexShader 与同一套采样口径（改采样两处同改）。
  */
 import { BackSide, Matrix4, ShaderMaterial, Vector3 } from "three";
-import { createPlaceholderTexture, floorVertexShader, MKT_PANO_MAX_SLOTS, RT_STITCH_SLOT_COUNT } from "./mktShader";
+import { createPlaceholderTexture, floorVertexShader, RT_STITCH_SLOT_COUNT } from "./mktShader";
+
+/**
+ * ⭐ 融合材质的全景点数**上限**（皇上旨 10-06「一次能够展示 8 个全景纹理」）：每点占 **2** 张拼合槽纹理
+ *   （32 片 8×4 → 左右 2 槽，每槽 4×4 格）⇒ **8 × 2 = 16 个 sampler**，再多样本编译不过。
+ *   （sampler 总数 16 是硬件硬顶，本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 16。）
+ *
+ * ⭐⭐ 2026-10-09 皇上旨「MktMesh 只有映射一种，blend/selected 归编辑器」⇒ 该常量从 `mktShader.ts`
+ *   **搬到这里**（映射材质的所在地）。它同时是库与编辑器那份 blend 的**共同上限**，两边必须同值。
+ */
+export const MKT_PANO_MAX_SLOTS = 8;
 
 /**
  * 序号直取片元（皇上旨 2026-09-29「三模式三 shader」之二）：

package/MktMesh/mktShader.d.ts

@@ -1,6 +1,55 @@
 import { DataTexture, Matrix4, ShaderMaterial } from "three";
+/** ⭐ 2026-10-09 随blend 材质搬去编辑器，故改为导出（那边拼片元 GLSL 时要用）。 */
+export declare const TILE_DEBUG_GLSL: string;
 /** 诊断配色是否开启（应用层据此把全景点标记染成同色板，两边对得上） */
 export declare const MKT_PANO_TINT_ON: boolean;
+/**
+ * 🔬 诊断色的**叠加强度**（0~1）：`mix(原画面色, 染色, 本值)`。1 = 整块换成色相（09-25 初版，墙上只剩明暗，
+ * 照片本身看不清）；皇上旨 2026-09-26 晚「叠加的颜色比例少一点」⇒ 取 **0.5**：色相仍是主色、一眼分得出归属，
+ * 但底下那张全景图的明暗与颜色能同时读出来。两份材质（融合 / 单全景）**共用这一个值**。
+ */
+/** ⭐ 2026-10-09 同上：随 blend 材质搬去编辑器，故改为导出。 */
+export declare const PANO_TINT_MIX = 0.5;
+/**
+ * 🔬 **距离明暗诊断图**（皇上旨 2026-09-26 晚「你计一下每个点距离最近的一个全景点的距离, 然后距离越小颜色就是白色,
+ *      越远颜色就是黑色」）。
+ *
+ * 用法：分两条路，**各自独立**，谁也不靠谁：
+ *      · **编辑器（MktMeshEdit）= 建材质时显式传 `panoDist: mktPanoDistEditorOn()`** ⇒ 默认关、地址里写 `panoDist=1` 才开
+ *        （皇上旨 2026-09-27 晚「把颜色换成纹理，全景的纹理」—— 灰阶诊断让位给真投影，诊断图按需开）。
+ *      · **库侧（发布页 / 预览弹窗）= 不传 ⇒ 读 URL 的 `PANO_DIST_ON`，默认关** ⇒ 正常渲染路径零影响。
+ *      开了之后片元算完最终颜色，按**这面这点到「它实际用的那张全景」的投影中心的水平距离**涂明暗：
+ *      **贴到球脚下 = 白，远到房间最远角 = 黑**。
+ *      与归属配色的分工：`panoTint` 回答「这块归哪个球」（分家线），`panoDist` 回答「这点离自己的球到底有多远」——
+ *      后者能把「整墙一个色」那面墙上的**连续渐变**照出来，距离判据是不是真在起作用一眼可辨（恒白/恒黑才是坏的）。
+ * ⚠️ 距离口径与取图那条**同一个**：水平（xz）距离、候选 = 存活槽、门优先兜底不限门 ⇒ 白色区域就是那一张覆盖到的地方。
+ * ⚠️ 黑端（多远算全黑）= 应用层每次喂的 `uPanoDistMax`，取**墙体上最远处到自己最近景点的那段水平距离**
+ *    （`_panoDistRange()`，皇上那间约 12m）⇒「黑」就是这间房可能出现的最大距离，跨面可比（不是每面各自归一化）。
+ *    ⛔ 别拿地板尺寸当尺子：默认地板盘 `FLOOR_SIZE_DEFAULT = 80`（远超房间），对角线 113m 会把整面墙的灰阶压平
+ *    （09-26 实测横扫三个点亮度 222/223/224，等于没有渐变）。
+ * ⚠️ 明暗曲线 = **线性**（`1 − d/D`，皇上旨 2026-09-27「要，改成线性渐变」）。09-26 那版 `pow(…, 2.2)` 的动机是
+ *    「着色器里是线性色，不补感知伽马会中间偏亮」—— 代价实测更糟：6m 处灰阶只剩 0.22 ⇒ 渐变几乎全压在景点脚下，
+ *    他数不出圆。线性后同一点 0.50 中灰，整间房的远近一眼读得出。
+ * ⚠️ 强度**不沿用** `PANO_TINT_MIX` 而是自己的 `PANO_DIST_MIX = 1`（整块换成灰阶）：皇上要的是「近=白、远=黑」这张**距离图**本身，
+ *    09-26 实测按 0.5 混 ⇒ 一面墙横扫过去只有 135→151（19 级）的差别，肉眼仍是「一片灰」；归属配色那条 0.5 的旨意针对的是
+ *    「色叠加把照片盖住了」，与本图无关（要看照片本来颜色就把 `?panoDist` 关掉）。
+ * ⚠️ 两道诊断**同时开**时本图后上色 ⇒ 明暗图盖住色相（要同时看归属与距离请分开截两张）。
+ * ⚠️ 开关口径历经三版：① 初版「默认关、URL `?panoDist=1` 才开」⇒ 皇上第二天地址栏里只剩 `panoTint=1`，
+ *      看到的又是实拍照片，误判「代码被改回去了」（09-26 实测线上包里 panoDist 一段俱在，纯为开关没跟上）。
+ *    ② 皇上同日晚旨「继续改成 距离越近越白、越远越黑的模式」⇒ 改成**编辑器这一页默认开**：写法是在 renderer
+ *      模块顶层调 `mktPanoDistEditorDefaultOn()` 翻全局开关。09-26 实测线上打印当场暴露它是**半张图**：
+ *      「墙 / 地板 / 家具三份材质的片元着色器不是同一份」—— 立方体那份是 `static material = create…()`，
+ *      在**模块求值期**就建好了，永远早于任何应用层模块体里的语句 ⇒ 墙/地板黑了白了，立方体仍是实拍。
+ *    ③ 现行（本次定论）：**开关不再靠语句先后**，而是建材质时把这一份材质要不要这张图**显式说清楚**
+ *      （融合工厂的 `panoDist` 选项）。⇒ 编辑器三处建材质点同传一个纯函数，预览/发布页不传 ⇒ 天然关。
+ *    ④ 09-27 晚皇上旨「把颜色换成纹理，全景的纹理」⇒ 编辑器这一页翻回**默认关**（`mktPanoDistEditorOn()`
+ *      = `panoDebugOn("panoDist")`），灰阶诊断按需 `?panoDist=1` 再看。口径机制不变，只翻默认值。
+ *    ⛔ 不许再回到「模块顶层翻全局变量」那一路：那份 GLSL 是建材质时一次性拼出来的，谁先谁后取决于 import 顺序，
+ *      改一次 import 就悄悄漏一面（且 `统一性检查` 会当场报不是同一份源码）。
+ */
+/** ⭐ 2026-10-09 皇上旨「MktMesh 只有映射一种，blend/selected 归编辑器」⇒ 本常量改为导出：
+ *  编辑器那份 `mktMeshFloorBlendShader.ts` 要用它当默认值。库内的映射材质仍照常用。 */
+export declare const PANO_DIST_ON: boolean;
 /**
  * 🔬 **编辑器这一页**该不该有近白远黑图：**默认关**（皇上旨 2026-09-27 晚「把颜色换成纹理，全景的纹理」——
  *      灰阶诊断盖住了真投影，默认让位给全景纹理；要看诊断图 URL 显式写 `panoDist=1`，`#` 前后都认）。
@@ -9,6 +58,16 @@ export declare const MKT_PANO_TINT_ON: boolean;
  * ⚠️ URL 解析只留库侧这一处（与 `panoDebugOn` 同族口径），⛔ 应用层不许再各解一遍。
  */
 export declare function mktPanoDistEditorOn(): boolean;
+/**
+ * 🔬 距离明暗图的「求最近景点」那一段 —— **真循环**版（皇上旨 2026-09-27 晚「那就更不对了，我一开始的需求就是
+ * 把 4 个全景点的坐标传给 shader，按最近取用」+ 看过代码后点头要这版）。
+ * 语义与他原话逐字对齐：每个像素遍历 `uPanoPoints[0..N-1]`，只留最小水平距离。
+ * ⚠️ 09-27 晚起取图与明暗图**同把尺**（皇上「取用距离最近的那个全景点的瓦片纹理」定版）：取图那条的夹角门
+ *    已整链删除 ⇒ 两边都是「纯水平距离最近」，圆与图永远一致。⛔ 本函数只动颜色，不动取图。
+ * ⚠️ 动态下标只碰普通 uniform 数组（`vec4[]`），不碰 sampler ⇒ ANGLE 那条「sampler 必须常量下标」的限制管不到这里。
+ */
+/** ⭐ 2026-10-09 同上：随 blend 材质一起搬去编辑器，故改为导出（那边拼片元 GLSL 时要用）。 */
+export declare function panoDistLoopGlsl(colorVar: string, maxPano: number): string;
 /** 末尾 4 色（红/绿/蓝/黄）：景点数 > 20 时循环取用 */
 export declare const MKT_PANO_TINT_HEX: readonly number[];
 /** 「第 i 个**景点**」的诊断色（按景点序号，不是槽位）：0~19 各一色，>=20 循环末尾 4 色 */
@@ -228,36 +287,19 @@ export declare function setMktPanoTiled(material: ShaderMaterial | null | undefi
  * 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 喂料会写但不读（静默忽略）。
+ * 多全景融合着色器：把「最近最多 maxPano 个全景」以数组传入，每个片元对这些张各自做等距柱状投射，
+ * 再取**唯一一条**口径（皇上旨 2026-09-25 晚「都要一起改」→ 2026-09-27 晚「取用距离最近的那个全景点的瓦片纹理」定版）：
+ * - **候选里只取水平距离最近的那一张，满权重**（地板 / 墙 / 家具立方体**同一份、同一条**，
+ *   旧的「地板按覆盖度加权融合、交界渐隐」那一路已按旨删除 ⇒ 面上不再有渐隐带，也不再有中央露灰）。
+ * - ⚠️ 09-24~09-25 的「夹角门（点在面正面侧才合格）+ 全不合格兜底」已按 09-27 晚旨**整链删除**：
+ *   它是「明暗圆对、纹理不对」的第二来源（墙背后更近的点被门否掉，纹理落到正面侧的远槽）；
+ *   纯距离口径下墙背后的全景也会投过来，皇上知情选定。
+ * - 候选池按「槽里有没有全景」筛，**不按覆盖半径（c>0）筛**，否则两个景点距离一远就变成
+ *   「各占一片互不相干的 territory、交界处整条露灰底」，距离判据压根轮不到（实测 bothCandidates=0）。
+ * - ⚠️ 代价（已向皇上报过并获批）：`uFloorCoreRadius` / `uFloorFadeRange` 两根覆盖半径旋钮**从此对任何面都不参与取图**。
+ *   控件与 uniform 暂未删（未奉旨），删与不删等皇上下结论。
+ * - panoramas[i]      : 第 i 张全景纹理
+ * - textureMatrices[i]: 第 i 张全景的世界矩阵（位置=投影中心，旋转=朝向）
+ * - weights[i]        : 第 i 张是否活着（camW，0 = 该槽未绑全景 ⇒ 不进候选池）
  */
-export declare function createMktFloorSelectedShaderMaterial(options?: {
-    maxPano?: number;
-}): ShaderMaterial;