three-base 2.0.134 → 2.0.142

package/MktMesh/panoTileStitcher.ts

@@ -0,0 +1,616 @@
+/*
+ * @Description: 32 瓦片全景的「离屏拼合器」= **shader 逐格画进 WebGLRenderTarget**（本项目唯一一份拼合实现）。
+ *
+ * 三道旨意叠成现在这一份：
+ *   ① 2026-09-29：一张全景切多片（每片所有 GPU 都装得下），运行时离屏拼回若干张固定尺寸的「槽纹理」，
+ *      仍按「每全景 N 槽」的接口喂 shader ⇒ **着色器零改动**。
+ *   ② 2026-10-06（皇上旨，逐字）：
+ *      「我想的是, 不用 4 片拼合是 canvas 2D 的 drawImage 来拼合, 而是用一个 shader 来一个一个的渲染后的
+ *       RT 上面去才对」
+ *      「把全景重新设计成 8*8 的 64 片的方案, 上传的全景图分割成 8*8=64 片瓦片, 每个 RT 有 4*4=16 片瓦片
+ *       组成, 每一帧同样也是只载入一张新纹理到 GPU 里面去, 如果是已经载入过的纹理, 才可以一次性全部渲染
+ *       到 RT 上面去」
+ *      「canvas 是什么意思, 按照我的想法, 不应该有 canvas 才对啊」⇒ canvas 2D 那一份实现**连同
+ *      `?panoStitch=canvas` 开关整条删除**，两份实现的接口 `PanoStitcher` 也退回成一个类。
+ *   ③ 2026-10-06 晚（皇上旨，逐字）：「目前 shader 里面一次只展示 4 个全景纹理有点少了, 我希望一次能够
+ *      展示 8 个全景纹理, 每个全景纹理由左右 2 个 RT 组成, 每个 RT 由 16 个全景瓦片组成, 所以, 全景图在
+ *      上传的时候, 只需要拆分成 横 8 * 竖 4 = 32 个瓦片图就可以了」
+ *      ⇒ 旨②的 8×8=64 片 / 2×2 四槽 **作废**：改 **8×4=32 片 / 左右 2 槽**（槽纹理跟着变 4096² 正方形）。
+ *      ⭐ 净效果：sampler 总数仍 16（硬顶）⇒ 同屏全景数 **4 → 8**；画质与单全景显存**分毫未动**；
+ *         单全景下载片数 64 → 32（**减半**）。旧存档 64 条地址**不兼容**，皇上「有异常我会重传」。
+ *
+ * ⚠️ **仍然有 canvas，但只在上传切图那一步**（`src/views/MktMeshEdit/panoramaUpload.ts` 用 2D 画布把原图
+ *    切成 32 个 JPEG 传 OSS）—— 那是**离线、一次性、产出的是数据**；运行时这条路上一个 canvas 都没有。
+ *
+ * ── 每帧的三道工序（旨②那两句话逐条落地，顺序固定）────────────────────────────────
+ *   1. `_pumpDownloads()`：补发缺图的下载（每帧 ≤2 张、在册 ≤8、已解码待上传 ≤8）⇒ ⛔ 32 条 XHR 一起炸。
+ *   2. `_drawPass()`：**只画「已经在 GPU 上的」瓦片**，一帧内画多少格都行（旨②「已经载入过的纹理，才可以
+ *      一次性全部渲染到 RT 上面去」）。画完立刻释放那片 ⇒ 显存峰值 = 一格的量。
+ *   3. `_uploadPass()`：**每帧至多一张**新纹理 `initTexture` 进 GPU（旨②「每一帧同样也是只载入一张新纹理
+ *      到 GPU 里面去」）。这一趟**只上传、不画** ⇒ 上传与绘制永不落在同一拍（09-29 那句「两个大头别在同一
+ *      帧」的延续），而且第 2 步天然只能画「上一帧及更早」传上去的图 ⇒ 每帧 = 1 上传 + 1 绘制（稳态）。
+ *
+ * ⚠️ 于是「一帧一片」从最旧版的 16 帧/组变成 **32 帧/组**（30ms/帧 ⇒ 全量到位约 1.0s，最旧版约 0.5s；
+ *    10-06 白天那版 64 片是 64 帧/组 ≈ 1.9s，现砍半）。每格像素 1024²（旧 1024×512）。
+ *    且因为下面那条「先喂 shader」的旨意，第一格画完墙上就有东西了，不必等 16 帧。
+ *
+ * ⭐ 部分就绪就先喂（同日旨「1. 需要先喂给 shader」）：`peek()` 不再等一个槽的 16 格画满，
+ *   **画过 ≥1 格就交出去**。为了保证交出去的那张 RT 里绝无未定义像素，RT 建好后的第一件事是
+ *   整张涂成缺失灰（`_clearRt`）⇒ 观感 = 该象限从左上角起逐格显影，缺数据的格子一直是灰的。
+ *
+ * ── 画质四条（⛔ 改任何一条都是改画质，先请旨）──────────────────────────────
+ *  1. **尺寸 / 格子几何**：槽 `RT_STITCH_SLOT_W/H` = **4096×4096 正方形**、每边 4 格、原图**横 8 × 竖 4** 片，
+ *     全在 `./mktShader`（单一来源）。缩放比 (W/8)/1024 与 16 片时代 (W/4)/2048 **是同一个数**
+ *     ⇒ 这次切细不涨不降清晰度。⛔ 槽必须是正方形：每槽现在覆盖「横 180° × 竖 180°」，
+ *     沿用 4096×2048 会让纵向被压 2 倍（见 `RT_STITCH_SLOT_H` 那条注释）。
+ *  2. **色彩**：瓦片纹理 `colorSpace = SRGBColorSpace` ⇒ WebGL2 内部格式 `SRGB8_ALPHA8`，采样时硬件解码成
+ *     linear；RT 纹理同样标 sRGB ⇒ 写入时硬件再编码回 sRGB。一进一出**逐字节还原**。
+ *     ⚠️ 另一半证据在 three 里：写进非 XR 的 render target 时片元末尾的 `linearToOutputTexel` 恒按
+ *     LinearSRGB（= 不转换），编码完全交给硬件 ⇒ ⛔ 我们的片元绝不 `#include <colorspace_fragment>`，
+ *     也不带 tone mapping 的 chunk（那两处都会再转一遍 ⇒ 画面发白）。
+ *  3. **摩尔纹**：两层都开 mipmap ——
+ *     ① 瓦片纹理 `generateMipmaps` + `LinearMipmapLinearFilter`：一片原图 1488px 缩进 1024px 的格子是
+ *        **缩小**，⛔ 单点双线性会采出锯齿（WebGL2 对 NPOT 也能生成 mipmap，three r163 起只支持 WebGL2）。
+ *     ② 槽 RT 标 `generateMipmaps`：three 每次渲染进 RT 后自己 `glGenerateMipmap`（`WebGLRenderer.js`
+ *        `updateRenderTargetMipmap`）⇒ 与当年 CanvasTexture 上传后生成 mipmap 同一口径。
+ *        ⚠️ 代价：每格一次（旧版每格也是一次），都在 GPU 上、不占主线程。
+ *  4. **接缝**：槽内 4×4 = 16 格 ⇒ 一张槽内部的格子线从 1 横 1 竖变成 3 横 3 竖。治法 = 上传时每片向四边**多切**
+ *     `RT_STITCH_SEAM_MARGIN_PX` 像素、拼合时**只采中间那块**（`uSrcRect`）⇒ 边界插值拿得到真邻居像素，
+ *     不再复制自己的边缘。⛔ 这条不许「顺手简化」成直接铺满格子：几何会挤歪，缝也还在。
+ *     详见 `./mktShader` 里那三个 `rtStitch*` 纯函数 —— **上传侧与拼合侧必须共用同一份几何**。
+ *
+ * 资源账（⚠️ 如实记；10-06 晚改 8×4=32 片 / 左右 2 槽后重算）：
+ *   - 常驻显存：2 槽 × (4096×**4096**×4B + mipmap≈33%) ≈ **170MB/全景** —— 与 16 片、64 片时代**一字不变**
+ *     （合计像素相同，只是从「4 张 4096×2048」变成「2 张 4096×4096」）。
+ *     ⚠️ 但同屏从 4 个全景变 **8 个** ⇒ 同屏 RT 显存 683MB → **1.33GB**；13 个全景全常驻 ≈ 2.2GB
+ *     （上一轮已奉旨取消 LRU 淘汰 ⇒ 这些真会常驻，皇上已知情）。
+ *   - 上传总量：32 片 × ~9.2MB ≈ 292MB/全景 ⇒ 总量不变、**片数减半**（64 片那版每片 4.6MB × 64）。
+ *   - 瓦片纹理画完即弃 ⇒ 同时在册的只有「下载中 + 已解码待上传」那些，上限 8+8 片 ≈ 73MB CPU/拼合器。
+ *
+ * ⚠️ RT 是 GL 上下文私有资源：`pump(renderer)` 换 renderer 时整组作废（`_switchRenderer`），下一帧消费方
+ *   照旧的 `ensure()` 重建（瓦片走浏览器 HTTP 缓存重新下载）。现况是**每个持有者一份拼合器 + 一个 renderer**
+ *   （编辑器 `this.renderer`、库里 `onBeforeRender` 捕获的 `_glRenderer`、预览自建渲染器各一份）⇒ 异常才走到。
+ *
+ * ⭐ 运行中**不淘汰任何组**（10-02 旨「纹理都缓存在 mktmesh / mktdevmesh 对象里面，执行 dispose 时才销毁」）：
+ *   组只在 `dispose()` / `disposeGroup()` 时才销毁 ⇒ 一片瓦片终身只下载、只解码一次。
+ */
+
+import {
+    ClampToEdgeWrapping,
+    DataTexture,
+    LinearFilter,
+    LinearMipmapLinearFilter,
+    Mesh,
+    NoBlending,
+    OrthographicCamera,
+    PlaneGeometry,
+    RGBAFormat,
+    Scene,
+    ShaderMaterial,
+    SRGBColorSpace,
+    Texture,
+    UnsignedByteType,
+    Vector3,
+    Vector4,
+    WebGLRenderTarget,
+    type WebGLRenderer,
+} from "three";
+import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+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 里面去」）*/
+const PANO_STITCH_UPLOADS_PER_FRAME = 1;
+
+/** 每帧最多发起几张下载（32 片一批，⛔ 不加以限制就是一帧甩 32 条 XHR + 32 次解码） */
+const PANO_STITCH_DOWNLOADS_PER_FRAME = 2;
+
+/** 「下载中」的片数上限（跨所有批次） */
+const PANO_STITCH_MAX_INFLIGHT = 8;
+
+/** 「已解码、还没上传进 GPU」的片数上限 ⇒ 也是 CPU 侧位图的峰值内存闸（≈8 × 4.6MB） */
+const PANO_STITCH_MAX_DECODED_AHEAD = 8;
+
+/** 瓦片纹理的实际像素宽高（`loadPanoTexture` 交回来的是 `ImageBitmap`，尺寸就是切片区）。
+ *  内缩比例按**实际尺寸**算 ⇒ 编码差 1px 也不会露出邻居格子的像素。拿不到尺寸时退回下面那个兜底边长。 */
+function texW(tex: Texture): number {
+    const img = tex.image as { width?: number } | null | undefined;
+    return (img && img.width) || TEX_DIM_FALLBACK;
+}
+function texH(tex: Texture): number {
+    const img = tex.image as { height?: number } | null | undefined;
+    return (img && img.height) || TEX_DIM_FALLBACK;
+}
+/** 尺寸问不到时的兜底边长：给一个足够大的数 ⇒ 内缩比例趋 0 ⇒ 最坏退化成「不内缩」（= 加边距之前的老行为），
+ *  而不是把画面按比例挤歪。 */
+const TEX_DIM_FALLBACK = 100000;
+
+/** 缺格涂灰（09-29 晚旨）：地址与 shader 那一路同一个常量，这里换成「sRGB 0~1 三分量」喂给 shader，
+ *  片元里 sRGB→linear，再由硬件写 RT 时编码回同一字节 ⇒ 与 `uFaceMissingColor` 的观感对齐。 */
+function grayToSrgbVec3(hex: string): Vector3 {
+    const s = hex.replace("#", "");
+    const byte = (i: number) => parseInt(s.slice(i, i + 2), 16) / 255;
+    return new Vector3(byte(0), byte(2), byte(4));
+}
+
+/** 全屏 quad 的片元：只干「把一片瓦片的**中间那块**原样搬进 RT 的一格」。
+ *  ⛔ 不加色彩转换、不加 tone mapping（见文件头画质第 2 条）。 */
+const STITCH_VERT = /* glsl */ `
+varying vec2 vUv;
+void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+}
+`;
+
+const STITCH_FRAG = /* glsl */ `
+uniform sampler2D uMap;
+uniform float uMissing;
+uniform vec3 uMissingSrgb;
+uniform vec4 uSrcRect;   // xy = 采样窗口左下、zw = 右上（该瓦片纹理的 UV）；窗口外那圈就是多切的接缝余量
+varying vec2 vUv;
+void main() {
+    if ( uMissing > 0.5 ) {
+        vec3 c = ( uMissingSrgb + 0.055 ) / 1.055;
+        gl_FragColor = vec4( pow( c, vec3( 2.4 ) ), 1.0 );
+        return;
+    }
+    vec2 suv = mix( uSrcRect.xy, uSrcRect.zw, vUv );
+    gl_FragColor = vec4( texture2D( uMap, suv ).rgb, 1.0 );
+}
+`;
+
+/** 一片瓦片的在册状态（`_texs` 的条目）。`tex = null` ⇒ 还在下载/解码。 */
+interface TileRec {
+    tex: Texture | null;
+    /** 已 `renderer.initTexture` 过 ⇒ 画它不会再顺手触发 `texImage2D`（`_drawPass` 的唯一准入判据） */
+    uploaded: boolean;
+}
+
+/** 一个 32 瓦片批次（= 一个全景点）的拼合组 */
+interface StitchGroup {
+    /** 32 张瓦片地址（原图 **横 8 × 竖 4 行优先**、图像左上起；不足 32 条补空串占位 ⇒ 缺格涂灰） */
+    urls: string[];
+    /** `RT_STITCH_SLOT_COUNT`(2) 个槽的渲染目标（懒建；`rt.texture` 就是交给 shader 的那张槽纹理） */
+    rts: (WebGLRenderTarget | null)[];
+    /** 每槽一个 16 位掩码：bit `cell` = 1 ⇒ 这一格已画进 RT（**允许跳着画**：谁先到就上谁） */
+    drawn: number[];
+    /** 每槽已画格数（= 掩码的 popcount，省得每帧数） */
+    drawnCount: number[];
+    /** 还剩几槽没画满 */
+    pending: number;
+}
+
+/**
+ * 拼合器对外接口（消费方 `MktMesh` / 编辑器渲染器 / 预览只认这一个类）。
+ * 10-06 之前它是「两份实现共用一份接口」里的 canvas 那一份 ⇒ 那份已奉旨删除，接口留在原地当文档。
+ */
+export interface PanoStitcher {
+    /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做） */
+    ensure(urls: string[]): void;
+    /** 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）；没画过 / 没这组返回 null。 */
+    peek(batch: string, slot: number): Texture | null;
+    /** 每帧驱动（消费方每帧只调一次）。`renderer` = 调用方当前的 WebGLRenderer，还没捕获到就传 null
+     *  ⇒ 这一帧什么都不画（⛔ 不打假读数，也⛔ 不退回任何 CPU 拼合路径）。 */
+    pump(renderer: WebGLRenderer | null): void;
+    /** 这张槽纹理是否**已经在 GPU 上**（RT 版恒 true）：消费方据此跳过「每 tick 一张」预上传闸。
+     *  ⚠️ 返回 true 的纹理绝不能喂给 `renderer.initTexture` —— 它不是普通纹理，是 three 自己管的渲染目标附件。 */
+    resident(tex: Texture): boolean;
+    /** 该批次是否已在册（诊断/测试用） */
+    has(batch: string): boolean;
+    /** 该批次已画进 RT 的格数（0~32）⇒ 编辑器按需渲染的「指纹」用它判断拼合还在推进 */
+    cellsDrawn(batch: string): number;
+    /** 全局推进计数（画一格 / 传一张 / 建组 / 拆组都 +1）⇒ 上面那个指纹的单调哨兵，无需知道批次名 */
+    progressStamp(): number;
+    /** 释放一整组（含它的 GPU 资源） */
+    disposeGroup(batch: string): void;
+    /** 释放全部 */
+    dispose(): void;
+}
+
+export class PanoTileStitcher implements PanoStitcher {
+    /** 批次组（键 = 32 张瓦片的第一张**非空**地址，与消费方同一个 `rtStitchBatchOf`） */
+    private _groups: Map<string, StitchGroup> = new Map();
+    /** 瓦片纹理（url → `{tex, uploaded}`）。画进自己那一格就立刻释放 ⇒ 只在册期间占显存/内存。 */
+    private _texs: Map<string, TileRec> = new Map();
+    /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
+    private _wanted: Set<string> = new Set();
+    /** 加载失败退避（url → 最早可重试时间戳）/ 失败计数 / 死链 */
+    private _retryAt: Map<string, number> = new Map();
+    private _fails: Map<string, number> = new Map();
+    private _dead: Set<string> = new Set();
+    /** 建 RT 时用的渲染器（换 renderer ⇒ 在册组全清，见文件头） */
+    private _renderer: WebGLRenderer | null = null;
+    /** 推进计数（`progressStamp`）*/
+    private _stamp = 0;
+
+    // 拼合用的那一套极小的 scene（所有组共用：一个正交相机把 [-1,1]² 铺满整张 RT，一个 quad 摆到目标格子）
+    private _scene: Scene = new Scene();
+    private _camera: OrthographicCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    private _mat: ShaderMaterial = new ShaderMaterial({
+        vertexShader: STITCH_VERT,
+        fragmentShader: STITCH_FRAG,
+        uniforms: {
+            uMap: { value: null },
+            uMissing: { value: 0 },
+            uMissingSrgb: { value: grayToSrgbVec3(MISSING_TILE_GRAY) },
+            uSrcRect: { value: new Vector4(0, 0, 1, 1) },
+        },
+        depthTest: false,
+        depthWrite: false,
+        blending: NoBlending,
+    });
+    /** 几何是 2×2（铺满正交相机的 [-1,1]²），每格只把它缩到 1/4 再挪过去 ⇒ 一格 = 槽的 1/16 */
+    private _quad: Mesh<PlaneGeometry, ShaderMaterial> = new Mesh(new PlaneGeometry(2, 2), this._mat);
+    /** 缺格那一路 `uMap` 也要有个合法纹理可绑（1×1，从不真采样） */
+    private _blank: DataTexture = new DataTexture(new Uint8Array([0, 0, 0, 255]), 1, 1);
+    /** 本拼合器发出去的槽纹理 = RT 附件（`resident()` 认它）；⛔ 不许喂给 `renderer.initTexture` */
+    private _rtTextures: WeakSet<Texture> = new WeakSet();
+
+    constructor() {
+        this._quad.frustumCulled = false; // 正交相机 + 手工摆位，⛔ 别按包围球把格子剔没了
+        this._scene.add(this._quad);
+        this._blank.needsUpdate = true;
+    }
+
+    /** 确保批次已建组、加载已发起。幂等：同批已在册 ⇒ 直接返回（一片瓦片终身只下载、只解码一次）。
+     *  ⭐ 09-29 晚旨「不足的涂灰」+ 10-06 晚旨「8×4 = 32 片」：1~32 条皆可入组，内部补空串占位到 32；
+     *  空串 / 死链的格子拼合时涂灰（一眼看出该全景数据不全）。
+     *  ⛔ 旧版 16 条（4×4）与 64 条（8×8）的数据**都不做兼容**（皇上「无须兼容正常使用, 有异常我会重传」）：
+     *  64 条会在上一行被判超限直接丢弃；真喂进来的短数据只占前几格 + 其余涂灰，那是**故意**让数据不全看得见。
+     *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null,null,null]` —— 槽数再变会漏改）。 */
+    ensure(urls: string[]): void {
+        if (!urls || urls.length === 0 || urls.length > RT_STITCH_TILES_PER_BATCH) return;
+        const u = urls.slice();
+        while (u.length < RT_STITCH_TILES_PER_BATCH) u.push("");
+        const batch = rtStitchBatchOf(u);
+        if (this._groups.has(batch)) return; // ⭐ 已建组：什么都不做（绝不重建 ⇒ 永不二次解码）
+        this._groups.set(batch, {
+            urls: u,
+            rts: Array.from({ length: RT_STITCH_SLOT_COUNT }, () => null),
+            drawn: Array.from({ length: RT_STITCH_SLOT_COUNT }, () => 0),
+            drawnCount: Array.from({ length: RT_STITCH_SLOT_COUNT }, () => 0),
+            pending: RT_STITCH_SLOT_COUNT,
+        });
+        this._stamp++;
+    }
+
+    /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
+     *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
+    peek(batch: string, slot: number): Texture | null {
+        const g = this._groups.get(batch);
+        if (!g || !g.drawnCount[slot]) return null;
+        const rt = g.rts[slot];
+        return rt ? rt.texture : null;
+    }
+
+    /** ⭐ 这条路交出去的槽纹理本来就是 GL 渲染目标的附件 —— 像素已经在显存里，没有「上传」这一步。
+     *  消费方（`MktMesh._peekTileAt` / 编辑器 `_peekTileAt`）据此**跳过**「每 tick 一张 `initTexture`」那道闸。 */
+    resident(tex: Texture): boolean {
+        return this._rtTextures.has(tex);
+    }
+
+    has(batch: string): boolean {
+        return this._groups.has(batch);
+    }
+
+    cellsDrawn(batch: string): number {
+        const g = this._groups.get(batch);
+        if (!g) return 0;
+        return g.drawnCount.reduce((s, n) => s + n, 0);
+    }
+
+    progressStamp(): number {
+        return this._stamp;
+    }
+
+    /** 每帧驱动（三道工序，顺序固定：补下载 → 画已进 GPU 的 → 再传一张新的）。 */
+    pump(renderer: WebGLRenderer | null): void {
+        this._pumpRetries();
+        this._pumpDownloads();
+        if (!renderer) return;
+        if (this._renderer !== renderer) this._switchRenderer(renderer);
+        this._drawPass(renderer);
+        this._uploadPass(renderer);
+    }
+
+    /** 释放整组（2 张 RT + 该组还没画掉的瓦片纹理） */
+    disposeGroup(batch: string): void {
+        const g = this._groups.get(batch);
+        if (!g) return;
+        this._dropGroupGpu(g);
+        this._groups.delete(batch);
+        this._stamp++;
+    }
+
+    /** 释放全部（持有者 `dispose()` 时调用）；共享的那套 quad/材质/空白纹理一并退掉 */
+    dispose(): void {
+        for (const batch of [...this._groups.keys()]) this.disposeGroup(batch);
+        this._texs.clear();
+        this._wanted.clear();
+        this._retryAt.clear();
+        this._fails.clear();
+        this._dead.clear();
+        this._quad.geometry.dispose();
+        this._mat.dispose();
+        this._blank.dispose();
+        this._scene.remove(this._quad);
+    }
+
+    // ───────────────────────── 内部：每帧三道工序 ─────────────────────────
+
+    private _now(): number {
+        return typeof performance !== "undefined" ? performance.now() : Date.now();
+    }
+
+    /** 工序 1：按「槽 0 格 0 → 槽 3 格 15」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 /
+     *  下载中 ≤8 / 已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。 */
+    private _pumpDownloads(): void {
+        let inflight = 0;
+        let decoded = 0;
+        for (const rec of this._texs.values()) {
+            if (rec.tex) decoded++;
+            else inflight++;
+        }
+        let budget = PANO_STITCH_DOWNLOADS_PER_FRAME;
+        for (const g of this._groups.values()) {
+            if (budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
+            for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
+                const ids = RT_STITCH_SLOT_TILES[slot];
+                for (let cell = 0; cell < RT_STITCH_CELLS_PER_SLOT; cell++) {
+                    if (g.drawn[slot] & (1 << cell)) continue; // 画过的格子那片早释放了，不用再来
+                    const url = g.urls[ids[cell]];
+                    if (!url || this._dead.has(url)) continue; // 缺格 / 死链：涂灰那一路，不需要纹理
+                    if (this._texs.has(url)) continue; // 已在册（下载中或已解码）⇒ ⛔ 发第二遍
+                    this._loadTile(url);
+                    inflight++;
+                    if (--budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
+                }
+            }
+        }
+    }
+
+    /** 工序 2：把所有「已进 GPU 且还没画」的格子画进各自的 RT —— 一帧画多少格都行（旨②）。
+     *  ⛔ 准入只看一件事：`uploaded`。没上传过的纹理当场画 = `texImage2D` 藏进 `render()` 里
+     *  = 每帧一张新纹理那道闸形同虚设（这正是本轮要治的卡顿本体）。 */
+    private _drawPass(renderer: WebGLRenderer): void {
+        for (const g of this._groups.values()) {
+            if (g.pending <= 0) continue;
+            for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
+                if (g.drawnCount[slot] >= RT_STITCH_CELLS_PER_SLOT) continue;
+                const ids = RT_STITCH_SLOT_TILES[slot];
+                for (let cell = 0; cell < RT_STITCH_CELLS_PER_SLOT; cell++) {
+                    if (g.drawn[slot] & (1 << cell)) continue;
+                    const url = g.urls[ids[cell]];
+                    if (!url || this._dead.has(url)) {
+                        this._stitchCell(renderer, g, slot, cell, null); // 缺格：涂灰，不占任何预算
+                        continue;
+                    }
+                    const rec = this._texs.get(url);
+                    if (!rec || !rec.tex || !rec.uploaded) continue; // 还没上 GPU：等下一帧（工序 3 会排它）
+                    this._stitchCell(renderer, g, slot, cell, rec.tex);
+                    this._dropTile(url); // 一格只用这一片 ⇒ 画完即弃（显存峰值 = 一格）
+                }
+            }
+        }
+    }
+
+    /** 工序 3：每帧至多把**一张**新纹理传进 GPU（旨②），这一趟只上传、不画。
+     *  按「槽 0 格 0 → …」的顺序挑第一张已解码没上传的 ⇒ RT 从左上角起逐格显影，观感可预期。 */
+    private _uploadPass(renderer: WebGLRenderer): void {
+        let budget = PANO_STITCH_UPLOADS_PER_FRAME;
+        for (const g of this._groups.values()) {
+            if (g.pending <= 0) continue;
+            for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
+                const ids = RT_STITCH_SLOT_TILES[slot];
+                for (let cell = 0; cell < RT_STITCH_CELLS_PER_SLOT; cell++) {
+                    if (g.drawn[slot] & (1 << cell)) continue;
+                    const url = g.urls[ids[cell]];
+                    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; // 旨②「每一帧只载入一张新纹理」⇒ 这一趟到此为止
+                }
+            }
+        }
+    }
+
+    /** 上传一片瓦片的纹理（`texImage2D` + mipmap 才是那一下贵的，所以单独成工序）。
+     *  ⚠️ 成败都记 `uploaded`：不记 ⇒ 那一格永远进不了 `_drawPass` ⇒ 该槽永远画不满、每帧白烧一个预算，
+     *  比「那一帧没错峰」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
+     *  （与 `MktMesh._uploadTileTexture` 同一口径，皇上旨 2026-09-25「队列里只放上传那一句」。） */
+    private _uploadTile(rec: TileRec): void {
+        const renderer = this._renderer;
+        if (!renderer || !rec.tex) return;
+        try {
+            renderer.initTexture(rec.tex);
+        } catch (e) {
+            console.warn("[PanoTileStitcher] 瓦片预上传失败，交给绘制那一帧自己上传：", e);
+        }
+        rec.uploaded = true;
+        this._stamp++;
+    }
+
+    // ───────────────────────── 内部：单格绘制 ─────────────────────────
+
+    /** 画一格：把那片瓦片的**中间那块**铺进该槽第 `cell` 格（16 格里的一格）。
+     *  ⚠️⚠️ `autoClear` 必须关掉：three 每次 `render()` 默认清屏，而这里**同一张 RT 要连画 16 帧**，
+     *     清一次就把前面画好的格子抹了 ⇒ 槽纹理只剩最后一格。清屏交给我们自己（见 `_clearRt`）。 */
+    private _stitchCell(renderer: WebGLRenderer, g: StitchGroup, slot: number, cell: number, tex: Texture | null): void {
+        const rt = this._ensureRt(renderer, g, slot);
+        const tileIdx = RT_STITCH_SLOT_TILES[slot][cell];
+        const [cc, rr] = rtStitchCellPos(cell);
+        // 正交相机铺满 [-1,1]²：quad 缩到 1/4 ⇒ 占一格；`rtStitchCellPos` 是**图像方向**的 [列, 行]，
+        // GL 的 y 向上 ⇒ 图像第一行落在 RT 的上半（v=1），故 y 取反。
+        this._quad.scale.set(1 / RT_STITCH_SLOT_GRID, 1 / RT_STITCH_SLOT_GRID, 1);
+        this._quad.position.set(
+            (2 * cc + 1) / RT_STITCH_SLOT_GRID - 1,
+            1 - (2 * rr + 1) / RT_STITCH_SLOT_GRID,
+            0,
+        );
+        this._mat.uniforms.uMap.value = tex ?? this._blank;
+        this._mat.uniforms.uMissing.value = tex ? 0 : 1;
+        const rect = tex ? rtStitchTileInset(tileIdx, texW(tex), texH(tex)) : null;
+        const uv = this._mat.uniforms.uSrcRect.value as Vector4;
+        if (rect) uv.set(rect[0], rect[1], rect[2], rect[3]);
+        else uv.set(0, 0, 1, 1);
+        this._renderQuad(renderer, rt);
+        g.drawn[slot] |= 1 << cell;
+        g.drawnCount[slot]++;
+        this._stamp++;
+        if (g.drawnCount[slot] >= RT_STITCH_CELLS_PER_SLOT) g.pending--;
+        if (g.pending <= 0) this._releaseGroupWanted(g);
+    }
+
+    /** 把整张 RT 涂成缺失灰：RT 建好后的第一件事 ⇒ 保证「画不满也先喂给 shader」时**没有未定义像素**。
+     *  走的是与缺格同一条 shader 路径（同一个 sRGB→linear→硬件编码回 sRGB）⇒ 灰度字节与涂灰格子完全相同。 */
+    private _clearRt(renderer: WebGLRenderer, rt: WebGLRenderTarget): void {
+        this._quad.scale.set(1, 1, 1);
+        this._quad.position.set(0, 0, 0);
+        this._mat.uniforms.uMap.value = this._blank;
+        this._mat.uniforms.uMissing.value = 1;
+        (this._mat.uniforms.uSrcRect.value as Vector4).set(0, 0, 1, 1);
+        this._renderQuad(renderer, rt);
+    }
+
+    /** 唯一碰 `renderer` 状态的那一句：存现场 → 关掉自动清屏 → 画 → 还原。 */
+    private _renderQuad(renderer: WebGLRenderer, rt: WebGLRenderTarget): void {
+        const prevTarget = renderer.getRenderTarget();
+        const prevAutoClear = renderer.autoClear;
+        renderer.autoClear = false;
+        renderer.setRenderTarget(rt);
+        renderer.render(this._scene, this._camera);
+        renderer.setRenderTarget(prevTarget);
+        renderer.autoClear = prevAutoClear;
+    }
+
+    // ───────────────────────── 内部：瓦片加载 ─────────────────────────
+
+    /** 发起一片瓦片的下载 + 异步解码（`loadPanoTexture` ⇒ 解码在工作线程，主线程只拿结果）。
+     *  幂等；失败记 3s 退避重发，累计 3 次判死链 ⇒ 那一格涂灰，一眼看出该全景数据不全。 */
+    private _loadTile(url: string): void {
+        if (!url || this._texs.has(url) || this._retryAt.has(url) || this._dead.has(url)) return;
+        this._wanted.add(url);
+        this._texs.set(url, { tex: null, uploaded: false });
+        loadPanoTexture(url).then(
+            (tex) => {
+                // 与消费方那两条（`MktMesh.ensureTileTexture` / 编辑器 `ensureFloorTexture`）同一套纹理参数
+                tex.colorSpace = SRGBColorSpace;
+                tex.minFilter = LinearMipmapLinearFilter; // 缩小进格子要 mipmap，⛔ 单点双线性出锯齿
+                tex.magFilter = LinearFilter;
+                tex.generateMipmaps = true;
+                tex.wrapS = ClampToEdgeWrapping;
+                tex.wrapT = ClampToEdgeWrapping;
+                tex.needsUpdate = true;
+                const rec = this._texs.get(url);
+                if (!this._wanted.has(url) || !rec) {
+                    // 迟到的回调：这一组已经作废（换 renderer / dispose）⇒ 当场释放，别留一份没人认领的显存 + 位图
+                    releasePanoTexture(tex);
+                    return;
+                }
+                this._retryAt.delete(url);
+                this._fails.delete(url);
+                rec.tex = tex; // uploaded 仍 false ⇒ 下一帧的工序 2/3 才轮得到它
+            },
+            () => this._failTile(url),
+        );
+    }
+
+    /** 加载失败：摘掉「加载中」占位；3 次判死链，否则 3s 退避由 `_pumpRetries` 重发 */
+    private _failTile(url: string): void {
+        this._texs.delete(url);
+        this._wanted.delete(url);
+        const n = (this._fails.get(url) || 0) + 1;
+        this._fails.set(url, n);
+        if (n >= 3) {
+            this._retryAt.delete(url);
+            this._dead.add(url);
+        } else {
+            this._retryAt.set(url, this._now() + 3000);
+        }
+    }
+
+    /** 到点的失败重发（每帧最多 2 个，防风暴） */
+    private _pumpRetries(): void {
+        if (this._retryAt.size === 0) return;
+        let budget = 2;
+        const now = this._now();
+        for (const [url, at] of [...this._retryAt]) {
+            if (budget <= 0) break;
+            if (now < at) continue;
+            this._retryAt.delete(url);
+            this._loadTile(url);
+            budget--;
+        }
+    }
+
+    /** 换 renderer：RT 是旧上下文的私有资源，留着既画不了也释放不掉 ⇒ 在册组整份作废，
+     *  靠消费方每帧照旧的 `ensure()` 重建（瓦片走浏览器 HTTP 缓存，不重新编码）。 */
+    private _switchRenderer(renderer: WebGLRenderer): void {
+        this._renderer = renderer;
+        for (const batch of [...this._groups.keys()]) this.disposeGroup(batch);
+        this._texs.clear();
+        this._wanted.clear();
+        this._retryAt.clear();
+        this._fails.clear();
+        this._dead.clear();
+    }
+
+    /** 懒建某槽的渲染目标：4096×4096 RGBA8 + sRGB + mipmap，并**立刻整张涂缺失灰**
+     *  （⛔ 未定义像素不许进 shader：`peek()` 现在画过 1 格就交出去）。 */
+    private _ensureRt(renderer: WebGLRenderer, g: StitchGroup, slot: number): WebGLRenderTarget {
+        const exist = g.rts[slot];
+        if (exist) return exist;
+        const rt = new WebGLRenderTarget(RT_STITCH_SLOT_W, RT_STITCH_SLOT_H, {
+            wrapS: ClampToEdgeWrapping,
+            wrapT: ClampToEdgeWrapping,
+            minFilter: LinearMipmapLinearFilter,
+            magFilter: LinearFilter,
+            format: RGBAFormat,
+            type: UnsignedByteType,
+            colorSpace: SRGBColorSpace,
+            generateMipmaps: true,
+            depthBuffer: false,
+            stencilBuffer: false,
+        });
+        g.rts[slot] = rt;
+        this._rtTextures.add(rt.texture);
+        this._clearRt(renderer, rt);
+        return rt;
+    }
+
+    /** 释放一片瓦片的纹理 + ImageBitmap（它只属于一格，画完即弃 ⇒ 显存峰值 = 一格） */
+    private _dropTile(url: string): void {
+        const rec = this._texs.get(url);
+        if (rec && rec.tex) releasePanoTexture(rec.tex);
+        this._texs.delete(url);
+        this._wanted.delete(url);
+    }
+
+    /** 整组拼完：该组已无在册地址（瓦片逐片释放过了），清 `_wanted` 让迟到回调自己收尾 */
+    private _releaseGroupWanted(g: StitchGroup): void {
+        for (const u of g.urls) this._wanted.delete(u);
+    }
+
+    /** 释放一组的全部 GPU 资源：2 张 RT + 还没画掉的瓦片纹理 */
+    private _dropGroupGpu(g: StitchGroup): void {
+        for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
+            const rt = g.rts[slot];
+            if (rt) rt.dispose();
+            g.rts[slot] = null;
+        }
+        for (const u of g.urls) if (u) this._dropTile(u);
+    }
+}