three-base 2.0.166 → 2.0.169

package/MktMesh/panoTileStitcher.js

@@ -76,8 +76,15 @@
  */
 import { ClampToEdgeWrapping, DataTexture, LinearFilter, LinearMipmapLinearFilter, Mesh, NoBlending, OrthographicCamera, PlaneGeometry, RGBAFormat, Scene, ShaderMaterial, SRGBColorSpace, UnsignedByteType, Vector3, Vector4, WebGLRenderTarget, } from "three";
 import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+// ⭐ 2026-10-09 皇上旨「上传也走 threeUtils.addWork 队列」：上传节流改为挂公共队列，见 `_uploadPass`。
+import threeUtils from "../threeUtils";
 import { MISSING_TILE_GRAY, RT_STITCH_CELLS_PER_SLOT, RT_STITCH_SLOT_COUNT, RT_STITCH_SLOT_H, RT_STITCH_SLOT_TILES, RT_STITCH_SLOT_W, RT_STITCH_SLOT_GRID, RT_STITCH_TILES_PER_BATCH, rtStitchBatchOf, rtStitchCellPos, rtStitchTileInset, } from "./mktShader";
-/** 每帧最多几张**新**纹理进 GPU（旨②「每一帧同样也是只载入一张新纹理到 GPU 里面去」）*/
+/**
+ * ⛔⛔ 2026-10-09 皇上旨：「每帧最多几张新纹理进 GPU」这条**节流已不再由此常量实现**，改由
+ *   `threeUtils.addWork` 队列承担（见 `_uploadPass`）—— 因为函数内局部 budget 管不住「一帧多次 pump」。
+ *   此常量保留仅作**文档锚点**，标出「一帧一张」这个不可回退的设计承诺（改队列实现前先看这里）。
+ *   ⛔ 别再拿它去写 budget 循环：那正是「一帧上传 2 张」的根因（消费方 onBeforeRender 里 pump 了两次）。
+ */
 const PANO_STITCH_UPLOADS_PER_FRAME = 1;
 /** 每帧最多发起几张下载（32 片一批，⛔ 不加以限制就是一帧甩 32 条 XHR + 32 次解码） */
 const PANO_STITCH_DOWNLOADS_PER_FRAME = 2;
@@ -141,6 +148,12 @@ export class PanoTileStitcher {
     _retryAt = new Map();
     _fails = new Map();
     _dead = new Set();
+    /** 已排进 `threeUtils.addWork` 队列、等着「只干上传那一句」的瓦片（皇上 2026-10-09 旨：上传走公共队列）。
+     *  ⛔ 必须自备：`addWork` 用 `workList.includes(work)` 判重，而每次排的都是**新闭包** ⇒ 它判不出来。
+     *  这个 Set 兼作「作废哨兵」：`_uploadTile` 开头 `if (!this._uploadQueued.delete(rec)) return;`
+     *  —— 该瓦片若已先被 `_dropTile`/`_switchRenderer`清掉（dispose 过），这一项就作废，
+     *  否则会对已释放的纹理 `initTexture` ⇒ 凭空建显存且无人回收。 */
+    _uploadQueued = new Set();
     /** 建 RT 时用的渲染器（换 renderer ⇒ 在册组全清，见文件头） */
     _renderer = null;
     /** 推进计数（`progressStamp`）*/
@@ -198,10 +211,24 @@ export class PanoTileStitcher {
     }
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
-    peek(batch, slot) {
+    peek(batch, slot, renderer) {
         const g = this._groups.get(batch);
-        if (!g || !g.drawnCount[slot])
+        if (!g)
             return null;
+        if (!g.drawnCount[slot]) {
+            // ⭐ 皇上 2026-10-09 旨「切换全景时上一个全景的内容要渲染成深灰」：
+            //   换批次的瞬间新全景还没画进任何格，若此处照旧返回 null，消费方 `panoSlotBind` 会
+            //   **沿用上一批的 RT 纹理** ⇒ 墙上继续显示上一个全景（皇上报的现象）。
+            //   这里改为：只要调用方给了 renderer，就**先把这张 RT 建出来**（`_ensureRt` 建完立刻
+            //   整张涂 `MISSING_TILE_GRAY` 缺失灰）并交出去 ⇒ 切换瞬间该象限就是**深灰底**，
+            //   随后随`pump` 逐格显影。观感 = 深灰 → 逐格填图，不再闪上一个全景的内容。
+            //   ⛔ 没给 renderer（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+            if (!renderer)
+                return null;
+            if (!this._renderer)
+                return null;
+            return this._ensureRt(this._renderer, g, slot).texture;
+        }
         const rt = g.rts[slot];
         return rt ? rt.texture : null;
     }
@@ -247,6 +274,7 @@ export class PanoTileStitcher {
         for (const batch of [...this._groups.keys()])
             this.disposeGroup(batch);
         this._texs.clear();
+        this._uploadQueued.clear(); // ⭐ 2026-10-09 旨：同上，连队列里那批未执行的项一并作废
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -323,8 +351,28 @@ export class PanoTileStitcher {
     }
     /** 工序 3：每帧至多把**一张**新纹理传进 GPU（旨②），这一趟只上传、不画。
      *  按「槽 0 格 0 → …」的顺序挑第一张已解码没上传的 ⇒ RT 从左上角起逐格显影，观感可预期。 */
+    /**
+     * 工序 3：**只入队一张**，真正上传交给 `threeUtils.addWork`（皇上 2026-10-09 旨）。
+     *
+     * ⚠️⛔ 为什么不用「函数内局部 budget」了：那个 `budget` 每次调用都重新初始化为 1，
+     *   只管得住「**本次 pump 内**≤1 张」，管不住「一帧被 pump 多次」——
+     *   而消费方 `MktMesh.onBeforeRender` 里 `updateTexture` 与 `feedFaceMapping` **各调了一次 pump**
+     *   （两处注释都以为对方在驱动，实际各驱动一次）⇒ 实际每帧上传 2 张，
+     *   违背本文件头「每一帧同样也是只载入一张新纹理」的承诺（实测 Performance 面板一帧看到多次 initTexture）。
+     *
+     * ⭐ 改挂`threeUtils.addWork` 的三个好处：
+     *   ① 节流**跨调用天然成立** —— 队列每帧只`splice(0,1)` 取一项，无论 pump 调几次都只上传一张；
+     *   ② 与库内既有范式同口径（`MktMesh._commitTileToShader` 就是这么排的），上传路径全走同一条队列；
+     *   ③ 保留皇上 10-05 旨的「占一格」手法（下面 `addWork(() => {})`）⇒ 真活晚一帧执行，
+     *      与 `_drawPass` 天然错开（上传与绘制不落同一拍，正是 09-29「两个大头别在同一帧」的延续）。
+     */
     _uploadPass(renderer) {
-        let budget = PANO_STITCH_UPLOADS_PER_FRAME;
+        // ⛔⛔ 队列里已有待上传项 ⇒ **本次直接不排**。
+        //   这一句是本改法的关键闸门：若只靠下面 `has(rec)` 跳过「同一片」，遍历会**继续往下找下一片**
+        //   于是 pump 几次就把多张全排进队列（13 全景 × 32 片 = 416 项 ⇒ workList 膨胀、`includes` 退化成 O(n)、
+        //   队尾那张要等几百帧才传完）。先判「队列非空就收手」⇒ 队列恒 ≤2 项（一占位+一真活），延迟最低。
+        if (this._uploadQueued.size > 0)
+            return;
         for (const g of this._groups.values()) {
             if (g.pending <= 0)
                 continue;
@@ -339,18 +387,25 @@ export class PanoTileStitcher {
                     const rec = this._texs.get(url);
                     if (!rec || !rec.tex || rec.uploaded)
                         continue;
-                    this._uploadTile(rec);
-                    if (--budget <= 0)
-                        return; // 旨②「每一帧只载入一张新纹理」⇒ 这一趟到此为止
+                    // ⛔ 已在队列里 ⇒ 跳过（`addWork` 按引用判重对「新闭包」无效 ⇒ 必须自备 Set，见 `_uploadQueued`）
+                    if (this._uploadQueued.has(rec))
+                        continue;
+                    this._uploadQueued.add(rec);
+                    threeUtils.addWork(() => { }); // 占一格（什么都不干），把真活推到下一个 tick
+                    threeUtils.addWork(() => this._uploadTile(rec));
+                    return; // ⛔ 本次 pump 只排一张：其余名额留给下一帧的队列，绝不在这一帧再排第二张
                 }
             }
         }
     }
-    /** 上传一片瓦片的纹理（`texImage2D` + mipmap 才是那一下贵的，所以单独成工序）。
-     *  ⚠️ 成败都记 `uploaded`：不记 ⇒ 那一格永远进不了 `_drawPass` ⇒ 该槽永远画不满、每帧白烧一个预算，
-     *  比「那一帧没错峰」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
-     *  （与 `MktMesh._uploadTileTexture` 同一口径，皇上旨 2026-09-25「队列里只放上传那一句」。） */
+    /** 队列回调的全部内容：把这**一片**瓦片的纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的）。
+     *  ⚠️ 开头那句判空是**作废闸**（皇上 2026-10-09 旨加）：本项在队列里等tick 期间，
+     *   那片瓦片可能已被 `_dropTile`（画完即弃）/ `_switchRenderer` 清掉并 dispose ⇒ 此时必须作废，
+     *   否则会对已释放纹理 `initTexture` ⇒ 凭空把显存建回来且无人回收。
+     *   （与 `MktMesh._uploadTileTexture` 的「排上队之后已被清掉 ⇒ 本项作废」同一口径。） */
     _uploadTile(rec) {
+        if (!this._uploadQueued.delete(rec))
+            return;
         const renderer = this._renderer;
         if (!renderer || !rec.tex)
             return;
@@ -477,6 +532,8 @@ export class PanoTileStitcher {
         for (const batch of [...this._groups.keys()])
             this.disposeGroup(batch);
         this._texs.clear();
+        // ⭐ 2026-10-09 旨：在册组整份作废 ⇒ 上传队列里那些项的 rec 也一并作废（否则会拿旧 renderer 上传）
+        this._uploadQueued.clear();
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -510,6 +567,9 @@ export class PanoTileStitcher {
         const rec = this._texs.get(url);
         if (rec && rec.tex)
             releasePanoTexture(rec.tex);
+        // ⭐ 2026-10-09 旨：已排进上传队列的那一片也要**作废**（否则队列回调会对已释放纹理 initTexture）
+        if (rec)
+            this._uploadQueued.delete(rec);
         this._texs.delete(url);
         this._wanted.delete(url);
     }

package/MktMesh/panoTileStitcher.ts

@@ -96,6 +96,8 @@ import {
     type WebGLRenderer,
 } from "three";
 import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+// ⭐ 2026-10-09 皇上旨「上传也走 threeUtils.addWork 队列」：上传节流改为挂公共队列，见 `_uploadPass`。
+import threeUtils from "../threeUtils";
 import {
     MISSING_TILE_GRAY,
     RT_STITCH_CELLS_PER_SLOT,
@@ -110,7 +112,12 @@ import {
     rtStitchTileInset,
 } from "./mktShader";
 
-/** 每帧最多几张**新**纹理进 GPU（旨②「每一帧同样也是只载入一张新纹理到 GPU 里面去」）*/
+/**
+ * ⛔⛔ 2026-10-09 皇上旨：「每帧最多几张新纹理进 GPU」这条**节流已不再由此常量实现**，改由
+ *   `threeUtils.addWork` 队列承担（见 `_uploadPass`）—— 因为函数内局部 budget 管不住「一帧多次 pump」。
+ *   此常量保留仅作**文档锚点**，标出「一帧一张」这个不可回退的设计承诺（改队列实现前先看这里）。
+ *   ⛔ 别再拿它去写 budget 循环：那正是「一帧上传 2 张」的根因（消费方 onBeforeRender 里 pump 了两次）。
+ */
 const PANO_STITCH_UPLOADS_PER_FRAME = 1;
 
 /** 每帧最多发起几张下载（32 片一批，⛔ 不加以限制就是一帧甩 32 条 XHR + 32 次解码） */
@@ -199,8 +206,14 @@ interface StitchGroup {
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做） */
     ensure(urls: string[]): void;
-    /** 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）；没画过 / 没这组返回 null。 */
-    peek(batch: string, slot: number): Texture | null;
+    /**
+     * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
+     * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
+     *   先把 RT 建出来（建完即整张涂 `MISSING_TILE_GRAY` 缺失灰）并返回它** ⇒ 调用方切批次的那一帧
+     *   拿到的就是**深灰底**而非 null（null 会让它沿用上一批 ⇒ 墙上闪上一个全景）。
+     *   ⛔ 没传 `renderer`（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+     */
+    peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;
     /** 每帧驱动（消费方每帧只调一次）。`renderer` = 调用方当前的 WebGLRenderer，还没捕获到就传 null
      *  ⇒ 这一帧什么都不画（⛔ 不打假读数，也⛔ 不退回任何 CPU 拼合路径）。 */
     pump(renderer: WebGLRenderer | null): void;
@@ -230,6 +243,12 @@ export class PanoTileStitcher implements PanoStitcher {
     private _retryAt: Map<string, number> = new Map();
     private _fails: Map<string, number> = new Map();
     private _dead: Set<string> = new Set();
+    /** 已排进 `threeUtils.addWork` 队列、等着「只干上传那一句」的瓦片（皇上 2026-10-09 旨：上传走公共队列）。
+     *  ⛔ 必须自备：`addWork` 用 `workList.includes(work)` 判重，而每次排的都是**新闭包** ⇒ 它判不出来。
+     *  这个 Set 兼作「作废哨兵」：`_uploadTile` 开头 `if (!this._uploadQueued.delete(rec)) return;`
+     *  —— 该瓦片若已先被 `_dropTile`/`_switchRenderer`清掉（dispose 过），这一项就作废，
+     *  否则会对已释放的纹理 `initTexture` ⇒ 凭空建显存且无人回收。 */
+private _uploadQueued: Set<TileRec> = new Set();
     /** 建 RT 时用的渲染器（换 renderer ⇒ 在册组全清，见文件头） */
     private _renderer: WebGLRenderer | null = null;
     /** 推进计数（`progressStamp`）*/
@@ -288,9 +307,21 @@ export class PanoTileStitcher implements PanoStitcher {
 
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
-    peek(batch: string, slot: number): Texture | null {
+    peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {
         const g = this._groups.get(batch);
-        if (!g || !g.drawnCount[slot]) return null;
+        if (!g) return null;
+        if (!g.drawnCount[slot]) {
+            // ⭐ 皇上 2026-10-09 旨「切换全景时上一个全景的内容要渲染成深灰」：
+            //   换批次的瞬间新全景还没画进任何格，若此处照旧返回 null，消费方 `panoSlotBind` 会
+            //   **沿用上一批的 RT 纹理** ⇒ 墙上继续显示上一个全景（皇上报的现象）。
+            //   这里改为：只要调用方给了 renderer，就**先把这张 RT 建出来**（`_ensureRt` 建完立刻
+            //   整张涂 `MISSING_TILE_GRAY` 缺失灰）并交出去 ⇒ 切换瞬间该象限就是**深灰底**，
+            //   随后随`pump` 逐格显影。观感 = 深灰 → 逐格填图，不再闪上一个全景的内容。
+            //   ⛔ 没给 renderer（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+            if (!renderer) return null;
+            if (!this._renderer) return null;
+            return this._ensureRt(this._renderer, g, slot).texture;
+        }
         const rt = g.rts[slot];
         return rt ? rt.texture : null;
     }
@@ -338,6 +369,7 @@ export class PanoTileStitcher implements PanoStitcher {
     dispose(): void {
         for (const batch of [...this._groups.keys()]) this.disposeGroup(batch);
         this._texs.clear();
+        this._uploadQueued.clear(); // ⭐ 2026-10-09 旨：同上，连队列里那批未执行的项一并作废
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -408,8 +440,27 @@ export class PanoTileStitcher implements PanoStitcher {
 
     /** 工序 3：每帧至多把**一张**新纹理传进 GPU（旨②），这一趟只上传、不画。
      *  按「槽 0 格 0 → …」的顺序挑第一张已解码没上传的 ⇒ RT 从左上角起逐格显影，观感可预期。 */
+    /**
+     * 工序 3：**只入队一张**，真正上传交给 `threeUtils.addWork`（皇上 2026-10-09 旨）。
+     *
+     * ⚠️⛔ 为什么不用「函数内局部 budget」了：那个 `budget` 每次调用都重新初始化为 1，
+     *   只管得住「**本次 pump 内**≤1 张」，管不住「一帧被 pump 多次」——
+     *   而消费方 `MktMesh.onBeforeRender` 里 `updateTexture` 与 `feedFaceMapping` **各调了一次 pump**
+     *   （两处注释都以为对方在驱动，实际各驱动一次）⇒ 实际每帧上传 2 张，
+     *   违背本文件头「每一帧同样也是只载入一张新纹理」的承诺（实测 Performance 面板一帧看到多次 initTexture）。
+     *
+     * ⭐ 改挂`threeUtils.addWork` 的三个好处：
+     *   ① 节流**跨调用天然成立** —— 队列每帧只`splice(0,1)` 取一项，无论 pump 调几次都只上传一张；
+     *   ② 与库内既有范式同口径（`MktMesh._commitTileToShader` 就是这么排的），上传路径全走同一条队列；
+     *   ③ 保留皇上 10-05 旨的「占一格」手法（下面 `addWork(() => {})`）⇒ 真活晚一帧执行，
+     *      与 `_drawPass` 天然错开（上传与绘制不落同一拍，正是 09-29「两个大头别在同一帧」的延续）。
+     */
     private _uploadPass(renderer: WebGLRenderer): void {
-        let budget = PANO_STITCH_UPLOADS_PER_FRAME;
+        // ⛔⛔ 队列里已有待上传项 ⇒ **本次直接不排**。
+        //   这一句是本改法的关键闸门：若只靠下面 `has(rec)` 跳过「同一片」，遍历会**继续往下找下一片**
+        //   于是 pump 几次就把多张全排进队列（13 全景 × 32 片 = 416 项 ⇒ workList 膨胀、`includes` 退化成 O(n)、
+        //   队尾那张要等几百帧才传完）。先判「队列非空就收手」⇒ 队列恒 ≤2 项（一占位+一真活），延迟最低。
+        if (this._uploadQueued.size > 0) return;
         for (const g of this._groups.values()) {
             if (g.pending <= 0) continue;
             for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
@@ -420,18 +471,24 @@ export class PanoTileStitcher implements PanoStitcher {
                     if (!url || this._dead.has(url)) continue;
                     const rec = this._texs.get(url);
                     if (!rec || !rec.tex || rec.uploaded) continue;
-                    this._uploadTile(rec);
-                    if (--budget <= 0) return; // 旨②「每一帧只载入一张新纹理」⇒ 这一趟到此为止
+                    // ⛔ 已在队列里 ⇒ 跳过（`addWork` 按引用判重对「新闭包」无效 ⇒ 必须自备 Set，见 `_uploadQueued`）
+                    if (this._uploadQueued.has(rec)) continue;
+                    this._uploadQueued.add(rec);
+                    threeUtils.addWork(() => {}); // 占一格（什么都不干），把真活推到下一个 tick
+                    threeUtils.addWork(() => this._uploadTile(rec));
+                    return; // ⛔ 本次 pump 只排一张：其余名额留给下一帧的队列，绝不在这一帧再排第二张
                 }
             }
         }
     }
 
-    /** 上传一片瓦片的纹理（`texImage2D` + mipmap 才是那一下贵的，所以单独成工序）。
-     *  ⚠️ 成败都记 `uploaded`：不记 ⇒ 那一格永远进不了 `_drawPass` ⇒ 该槽永远画不满、每帧白烧一个预算，
-     *  比「那一帧没错峰」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
-     *  （与 `MktMesh._uploadTileTexture` 同一口径，皇上旨 2026-09-25「队列里只放上传那一句」。） */
+    /** 队列回调的全部内容：把这**一片**瓦片的纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的）。
+     *  ⚠️ 开头那句判空是**作废闸**（皇上 2026-10-09 旨加）：本项在队列里等tick 期间，
+     *   那片瓦片可能已被 `_dropTile`（画完即弃）/ `_switchRenderer` 清掉并 dispose ⇒ 此时必须作废，
+     *   否则会对已释放纹理 `initTexture` ⇒ 凭空把显存建回来且无人回收。
+     *   （与 `MktMesh._uploadTileTexture` 的「排上队之后已被清掉 ⇒ 本项作废」同一口径。） */
     private _uploadTile(rec: TileRec): void {
+        if (!this._uploadQueued.delete(rec)) return;
         const renderer = this._renderer;
         if (!renderer || !rec.tex) return;
         try {
@@ -562,6 +619,8 @@ export class PanoTileStitcher implements PanoStitcher {
         this._renderer = renderer;
         for (const batch of [...this._groups.keys()]) this.disposeGroup(batch);
         this._texs.clear();
+        // ⭐ 2026-10-09 旨：在册组整份作废 ⇒ 上传队列里那些项的 rec 也一并作废（否则会拿旧 renderer 上传）
+        this._uploadQueued.clear();
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -595,6 +654,8 @@ export class PanoTileStitcher implements PanoStitcher {
     private _dropTile(url: string): void {
         const rec = this._texs.get(url);
         if (rec && rec.tex) releasePanoTexture(rec.tex);
+        // ⭐ 2026-10-09 旨：已排进上传队列的那一片也要**作废**（否则队列回调会对已释放纹理 initTexture）
+        if (rec) this._uploadQueued.delete(rec);
         this._texs.delete(url);
         this._wanted.delete(url);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.166",
+  "version": "2.0.169",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {