three-base 2.0.169 → 2.0.175

package/ThreeBase.js

@@ -18,17 +18,14 @@ import frosted_glass_pass from "./pass/frosted_glass_pass";
 import { flushLensflareOverlays } from "./lensflare/LensFlare";
 import glow_pass from "./pass/glow_pass";
 import stroke_pass from "./pass/stroke_pass";
-import ssao_pass, { renderAoDepthPass, renderExcludedMaskPass, visibleDepthOptions } from "./pass/ssao_pass";
+import ssao_pass, { renderVisibleDepthPass } from "./pass/ssao_pass";
 import screenBloomPass from "./pass/screen_bloom_pass";
 import copyShader from "./shaders/copyShader";
 import { baseTextureToRenderShader } from "./shaders/baseTextureToRenderShader";
 import baseDepthVisShader from "./shaders/baseDepthVisShader";
 import debugDepthCompareShader from "./shaders/debugDepthCompareShader";
 import debugDepthJudgeShader from "./shaders/debugDepthJudgeShader";
-import debugExcludedShader from "./shaders/debugExcludedShader";
 import { debugDepthState } from "./pass/debugDepthState";
-import { WaterFlow } from "./WaterFlow/WaterFlow";
-import waterFlowPass from "./WaterFlow/waterFlowPass";
 import threeLoader from "./threeLoader";
 import threeUtils from "./threeUtils";
 import fsQuad from "./pass/fsQuad";
@@ -78,21 +75,23 @@ export default class ThreeBase extends EventDispatcher {
     // 全局超采样/分辨率倍率（SSAA）：base / 深度 / 法线 / 效果 mask / 屏幕合成 全部按
     // effectiveRatio × resolution 内部超采样渲染，终处理 FXAA 降采样输出到屏幕。
     // 全链路同倍率 → 各 RT 严格 1:1 对齐：几何锯齿、效果边缘锯齿、辉光漏光（深度 vs mask 错位）、
-    // mask 合成 UV 缩放错位、SSAO 深度错位变黑 一并消除。默认 2 = 每维 2×、总像素 4×；
-    // 代价全链路填充 ×4（base + 深度 + 法线 + 后处理 SSAO/cover/frosted）。要省性能整体降 1
-    // （关超采样，仅 FXAA 兜底，几何硬边锯齿回弹）。历史坑：baseRenderScale/auxRenderScale/
-    // effectRenderScale 三参各自为政，倍率不同步必错位，故统一为单参数 resolution 管全局。
+    // mask 合成 UV 缩放错位、SSAO 深度错位变黑 一并消除。
+    // ⭐ 默认 1（原生分辨率）：2026-10-21 皇上旨「有点卡，分辨率改成 1」。原默认 2 = 每维 2×、
+    // 总像素 4×，全链路填充 ×4 且 35 张 RT 显存约 1.1 GB（1920×1080 画布）。降到 1 后填充与显存
+    // 均降约 75%，几何硬边锯齿由终处理 FXAA 兜底。需要纹理摩尔纹治本时，面板上再调回 2。
+    // 历史坑：baseRenderScale/auxRenderScale/effectRenderScale 三参各自为政，倍率不同步必错位，
+    // 故统一为单参数 resolution 管全局。
     // ⚠️ 必须用 getter/setter，不能是普通字段：所有 RT 尺寸只在 updateRenderTargetSizes()
     // 里按 effectiveRatio × resolution 计算，而该方法过去只被 setSize()（容器尺寸变化）调用
     // → 运行时改 resolution 不会重建任何 RT，画面毫无变化（表现为"调分辨率没感觉"）。
     // 故 setter 里改动倍率后立刻重建全部 RT。
-    _resolution = 2;
+    _resolution = 1;
     get resolution() {
         return this._resolution;
     }
     set resolution(value) {
         // 夹到合理区间：0 或负值会让 RT 尺寸为 0，WebGL 报 framebuffer incomplete
-        const next = Math.min(4, Math.max(0.25, Number.isFinite(value) ? value : 2));
+        const next = Math.min(4, Math.max(0.25, Number.isFinite(value) ? value : 1));
         if (next === this._resolution) {
             return;
         }
@@ -239,19 +238,6 @@ export default class ThreeBase extends EventDispatcher {
         });
         return baseRenderTarget;
     })();
-    /** 可选的屏幕空间水流对象（WaterFlow）。默认 null；调用 enableWaterFlow() 后创建。启用时
-     * 每帧消费 baseRenderTarget/baseDepthTexture，把水面合成进后处理链（不额外渲染主场景）。 */
-    waterFlow = null;
-    _waterFlowLastTime = 0;
-    waterFlowElapsed = 0;
-    // 调试用：被排除面 mask 渲染目标（仅「排除面标记」调试档使用，尺寸随主渲染目标同步）
-    excludedMaskRenderTarget = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-        stencilBuffer: false,
-        depthBuffer: false,
-    });
     // 深度专用渲染目标（无 MSAA，深度值稳定，供后处理深度比对使用）
     depthRenderTarget = new WebGLRenderTarget(128, 128, {
         minFilter: LinearFilter,
@@ -260,12 +246,14 @@ export default class ThreeBase extends EventDispatcher {
         stencilBuffer: false,
         depthTexture: this.baseDepthTexture,
     });
-    // AO 深度纹理（含地板）：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
-    // 法线 pass（renderAoNormalPass，includeFloor=true）渲染时深度由光栅器顺带写入，白拿一张含地板深度。
-    // （2026-09-14 优化：删掉原 ssao_pass 内那次 renderAoDepthPass(true)，每帧省一次全场景遍历。）
-    // SSAO 的 GTAO 采样它（地板保留为实体 → 接触 AO），合成时再与 depthRenderTarget
-    // （地板排除 = 可见深度）比对，作废"透过半透明地板看到的实体"上的地板接触 AO。
-    // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
+    // AO 深度纹理：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
+    // 法线 pass（renderAoNormalPass）渲染时深度由光栅器顺带写入，白拿一张。
+    // （2026-09-14 优化：删掉原 ssao_pass 内那次独立的深度 pass，每帧省一次全场景遍历。）
+    // SSAO 的 GTAO 采样它（与法线同源）；合成时再与 depthRenderTarget（可见深度 = 各物体自身材质渲染）
+    // 比对：AO 侧更近说明那像素记到屏幕上不可见的面（抠图空隙 / 单面墙背面）→ 作废该像素 AO。
+    // ⚠️ 2026-10-18 皇上旨「所有的对象都要进入到深度图里面了，不需要用参数过滤掉了」⇒ 这张 AO 深度
+    //   和 baseDepthTexture 都收全场景对象（含地板、含半透明面、含 sprite/线条/点）；原 excludeTransparent
+    //   参数与 userData.aoFloor 特例整条删除。见 three-base/pass/ssao_pass.ts 文件头（代价清单写在那里）。
     aoDepthTexture = (() => {
         const t = new DepthTexture(4096, 4096);
         t.format = DepthFormat;
@@ -276,29 +264,13 @@ export default class ThreeBase extends EventDispatcher {
     /**
      * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
      *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "global"  ：仅预览可见深度图（baseDepthTexture；2026-10-18 起收全场景对象，含地板）。全白=深度为空→renderVisibleDepthPass 没写进深度。
+     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入）。用于确认深度管线本身是否工作。
      *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
-     *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
-     *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
      * 兼容旧控制台入口：设置 `window.__BASE_DEPTH_VIS = true` 等价于切到 "global"。
      * 通用控制台入口：任意页面都可 `window.__TB_DEBUG_DEPTH = "judge"`（优先级高于面板属性）。
      */
     debugDepthPreview = "none";
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    get baseDepthIncludeFloor() {
-        return visibleDepthOptions.includeFloor;
-    }
-    set baseDepthIncludeFloor(v) {
-        visibleDepthOptions.includeFloor = v;
-        this.needRender = true;
-    }
     // 法线专用渲染目标（无 MSAA，存储视图空间法线，供 GTAO 风格 SSAO 使用真实法线）
     normalRenderTarget = new WebGLRenderTarget(128, 128, {
         minFilter: LinearFilter,
@@ -544,11 +516,8 @@ export default class ThreeBase extends EventDispatcher {
         // 强制同步为 depthRenderTarget 尺寸，下面再手动对齐一次避免首帧抖动。
         this.depthRenderTarget.setSize(w, h);
         this.normalRenderTarget.setSize(w, h);
-        this.excludedMaskRenderTarget.setSize(w, h);
         // 屏幕合成目标：同样跟随 resolution，全链路 1:1 对齐
         this.screenRenderTarget.setSize(w, h);
-        // 水流后处理目标跟随同倍率重建（pass 内部粒子 RT 仍按 scale 降采样，compositeTarget 全分辨率）
-        this.waterFlow?.resize(w, h);
         this.baseDepthTexture.image.width = w;
         this.baseDepthTexture.image.height = h;
         // 立即渲染一帧，避免静态场景下改了倍率却停在旧画面
@@ -620,92 +589,7 @@ export default class ThreeBase extends EventDispatcher {
         return axesHelper;
     })();
     init() {
-        // 屏幕空间水流：?waterflow=1 时自动启用（默认关闭，需显式 enableWaterFlow 或此 URL 参数）。
-        // 创建后每帧消费 base 深度 + 后处理合成画面，把水面合成进后处理链，不自渲染主场景。
-        try {
-            const params = new URLSearchParams(typeof location !== 'undefined' ? location.search : '');
-            if (params.get('waterflow') === '1') {
-                this.enableWaterFlow();
-            }
-        }
-        catch (_e) {
-            // 非浏览器环境（如 Node 测试/SSR）忽略
-        }
-    }
-    /**
-     * 启用屏幕空间水流（GPGPU 粒子流体）。默认关闭，需显式调用或携带 ?waterflow=1。
-     * 创建后每帧自动消费 base 深度 + 当前合成画面，把水面合成进后处理链，不自渲染主场景。
-     * @param options.size   粒子网格边长（size×size 粒子），越大越细腻、越费
-     * @param options.speed  射流初速
-     * @param options.aperture 喷嘴开度
-     * @param options.nozzle 喷流起点坐标 [x,y,z]，默认 [0.58,1.55,0]
-     * @param options.jetDirection 喷流方向（轴向，会被归一化），默认 [1,0,0]（沿 +X）
-     * @param options.collision 是否开启粒子与 basin/地面碰撞回弹，默认 true
-     */
-    enableWaterFlow(options = {}) {
-        if (this.waterFlow) {
-            console.warn('[ThreeBase] WaterFlow 已启用，重复调用无效');
-            return;
-        }
-        const { size = 200, speed = 2.4, aperture = 0.78, nozzle, jetDirection, collision = true, } = options;
-        const waterFlow = new WaterFlow(this.renderer, {
-            size,
-            speed,
-            aperture,
-            nozzle: nozzle ? new Vector3(nozzle[0], nozzle[1], nozzle[2]) : undefined,
-            jetDirection: jetDirection ? new Vector3(jetDirection[0], jetDirection[1], jetDirection[2]) : undefined,
-            collision,
-        });
-        if (!waterFlow.supported) {
-            console.warn('[ThreeBase] 当前环境不支持浮点纹理，WaterFlow 未启用');
-            waterFlow.dispose();
-            return;
-        }
-        // 创建 pass 并注入基础纹理（externalBase 模式）；后续每帧 renderInto 会刷新注入的纹理。
-        // ⚠️ 2026-10-08（WaterFlow 全量 TS 化）：ScreenSpaceFluidPass 内部按透视相机建模
-        //    （setSize 读 camera.fov 算 pointScale、depthMaterial 走 projectionMatrix 重建深度），
-        //    故此处显式窄化。getCamera() 在 cameraType==="orthographicCamera" 时会返回
-        //    OrthographicCamera —— 原 JS 同样会把 fov=undefined 传进去（pointScale 变 NaN），
-        //    本次**只补类型、未改运行时行为**，保持与线上一致。
-        waterFlow.createPass(this.scene, this.getCamera(), {
-            colorTexture: this.baseRenderTarget.texture,
-            depthTexture: this.baseDepthTexture,
-            depthMode: 'logarithmic',
-        });
-        // 首帧按当前容器尺寸对齐（后续 setSize/resolution 变化由 updateRenderTargetSizes 兜底）。
-        const w = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this._resolution));
-        const h = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this._resolution));
-        if (this.size.x > 1 && this.size.y > 1)
-            waterFlow.resize(w, h);
-        this.waterFlow = waterFlow;
-        this._waterFlowLastTime = 0;
-        this.waterFlowElapsed = 0;
-        console.info('[ThreeBase] WaterFlow 已启用');
-    }
-    /** 运行时改喷流起点（喷嘴）坐标（WaterFlow 已启用时有效） */
-    setWaterFlowNozzle(x, y, z) {
-        this.waterFlow?.setNozzle(x, y, z);
-    }
-    /** 运行时改喷流方向（轴向，会被归一化） */
-    setWaterFlowJetDirection(x, y, z) {
-        this.waterFlow?.setJetDirection(x, y, z);
-    }
-    /** 运行时开关粒子与 basin/地面碰撞回弹 */
-    setWaterFlowCollision(enabled) {
-        this.waterFlow?.setCollision(enabled);
-    }
-    /**
-     * 关闭屏幕空间水流并释放其 GPU 资源（enableWaterFlow 的反操作）。
-     * 切走页面时必须调用，否则其它页面 render 仍会合成水面（this.waterFlow 非空）。
-     */
-    disableWaterFlow() {
-        if (!this.waterFlow)
-            return;
-        this.waterFlow.dispose();
-        this.waterFlow = null;
-        this._waterFlowLastTime = 0;
-        this.waterFlowElapsed = 0;
-        console.info('[ThreeBase] WaterFlow 已关闭');
+        // 生命周期钩子：子类重写后调用 super.init()。当前无内置初始化动作。
     }
     // 重置控制器的位置
     resetLookAt({ position = this.perspectiveCamera.position, center = this.controls.target, }) {
@@ -972,17 +856,6 @@ export default class ThreeBase extends EventDispatcher {
             return; // 标识未渲染
         }
         this.needRender = false;
-        // 水流模拟推进：独立于相机控制，按真实帧间隔累计时间推进 GPGPU 粒子模拟。
-        // 默认 this.waterFlow 为 null（关闭），调用 enableWaterFlow() 或 ?waterflow=1 才创建。
-        if (this.waterFlow && this.waterFlow.supported) {
-            const wnow = performance.now();
-            const wdt = this._waterFlowLastTime > 0
-                ? Math.min((wnow - this._waterFlowLastTime) / 1000, 0.05)
-                : 1 / 60;
-            this._waterFlowLastTime = wnow;
-            this.waterFlowElapsed += wdt;
-            this.waterFlow.update(wdt, this.waterFlowElapsed);
-        }
         if (this.controls.enabled) {
             // 让 OrbitControls 始终接管"当前渲染相机"：OrbitControls 构造时只绑定了
             // perspectiveCamera，但渲染相机随 cameraType 切换。若切到正交相机时仍让 OrbitControls
@@ -1019,10 +892,11 @@ export default class ThreeBase extends EventDispatcher {
             this.renderer.setRenderTarget(this.baseRenderTarget);
             this.renderer.clear();
             this.renderer.render(this.scene, camera);
-            // 深度 pass：固定排除非实体表面后渲到 depthRenderTarget（生成 baseDepthTexture）。
+            // 可见深度 pass：用各物体自身材质渲染整个场景（2026-10-18 起不再排除任何对象：含地板、
+            // 含半透明面、含 sprite/线条/点），产出 baseDepthTexture 供描边/发光/覆盖/磨砂做遮挡判定。
             // 必须在 base render 之后、所有依赖深度的特效（描边/发光/覆盖/磨砂）之前更新，
             // 否则这些特效会用到上一帧旧深度 → 遮挡判定错乱。法线 pass 已收进 ssao_pass 内部。
-            renderAoDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
+            renderVisibleDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
             // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
             this.renderer.setRenderTarget(this.baseRenderTarget);
             // 效果 mask 灰度图尺寸 = effectiveRatio × resolution，与 baseRenderTarget / baseDepthTexture 同倍率，
@@ -1069,12 +943,6 @@ export default class ThreeBase extends EventDispatcher {
             }
             // 一次性处理所有支持毛玻璃特效的对象
             frosted_glass_pass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, dpr);
-            // 屏幕空间水流：消费 base 深度 + 当前合成画面（含 ssao/覆盖/磨砂），把水面合成进
-            // screenRenderTarget。插在磨砂之后、screenBloom 之前，使水面高光也能被泛光处理。
-            // 默认关闭（this.waterFlow 为 null 时不产生任何开销）。
-            if (this.waterFlow && this.waterFlow.supported) {
-                waterFlowPass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, this.waterFlow);
-            }
             // 屏幕空间辉光（经典 gaussian bloom）：纯颜色、无深度依赖，把亮度超阈值的部分做
             // 连续高斯模糊后加性叠加回 screenRenderTarget。单分辨率多迭代，柔和均匀、无 mip 分层。
             if (this.bloom.enable) {
@@ -1088,12 +956,16 @@ export default class ThreeBase extends EventDispatcher {
             // 分辨率按实际帧缓冲像素（已乘 dpr）设置，修复高分屏下 FXAA 采样比例偏大失效的问题。
             // ⚠️ 深度调试预览（面板「深度调试」切换，定位"深度测试全部失效"根因）：
             //   旧控制台入口 `window.__BASE_DEPTH_VIS = true` 仍可用，等价于切到 "global"。
-            //   global  → baseDepthTexture 灰度。全白=深度为空(renderAoDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
-            //   ao      → aoDepthTexture 灰度（含地板）。确认深度管线本身是否工作（GTAO 是否拿到正确深度）。
+            //   global  → baseDepthTexture 灰度（含全部对象，含地板）。全白=深度为空(renderVisibleDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
+            //   ao      → aoDepthTexture 灰度（同样含全部对象）。确认深度管线本身是否工作（GTAO 是否拿到正确深度）。
             //   compare → R=全局 base 深度，G=最近一次 glow/stroke 选区的 select 深度。两路任一全白即该侧写入失败。
             //   judge   → R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)。
+            //   strokeSelect     → 【描边步骤 1】选区本体深度（selectDepthTexture），白色=空背景、灰=物体本体。
+            //   strokeSelectBlur → 【描边步骤 5.5】描边外扩后的选区深度（selectDepthBlurTextureTarget），
+            //                      物体轮廓比本体档更胖一圈即外扩生效。
             // 通用控制台入口（任意页面可用，优先级高于面板属性）：
-            //   `window.__TB_DEBUG_DEPTH = "global" | "ao" | "compare" | "judge"`，设回 "none" 恢复。
+            //   `window.__TB_DEBUG_DEPTH = "global" | "ao" | "compare" | "judge" | "strokeSelect" | "strokeSelectBlur"`，
+            //   设回 "none" 恢复。
             const dbgWin = window.__TB_DEBUG_DEPTH;
             const dbgMode = window.__BASE_DEPTH_VIS
                 ? "global"
@@ -1122,12 +994,19 @@ export default class ThreeBase extends EventDispatcher {
                         debugDepthState.lastSelectDepth ?? this.baseDepthTexture;
                     fsQuad.render(this.renderer, debugDepthJudgeShader);
                 }
-                else if (dbgMode === "excluded") {
-                    // 先渲「被排除面 mask」，再与深度图叠加：红=挡不住任何后处理的面
-                    renderExcludedMaskPass(this.renderer, camera, this.scene, this.excludedMaskRenderTarget);
-                    debugExcludedShader.uniforms.tDepth.value = this.baseDepthTexture;
-                    debugExcludedShader.uniforms.tMask.value = this.excludedMaskRenderTarget.texture;
-                    fsQuad.render(this.renderer, debugExcludedShader);
+                else if (dbgMode === "strokeSelect") {
+                    // 描边步骤 1：选区本体深度（selectDepthTexture，挂在 mask 目标上当 depth attachment，
+                    // 由那趟光栅化顺带写入 ⇒ 零额外渲染代价）。
+                    baseDepthVisShader.uniforms.tDepth.value =
+                        debugDepthState.lastSelectDepth ?? this.baseDepthTexture;
+                    fsQuad.render(this.renderer, baseDepthVisShader);
+                }
+                else if (dbgMode === "strokeSelectBlur") {
+                    // 描边步骤 5.5：外扩后的选区深度（RGBA8 目标，对数深度存在 .r 通道）。
+                    // 与本体档对比看：外扩生效时物体轮廓会「胖一圈」，被遮挡的外扩环则被判 discard 后不参与。
+                    baseDepthVisShader.uniforms.tDepth.value =
+                        debugDepthState.lastSelectBlurDepth ?? this.baseDepthTexture;
+                    fsQuad.render(this.renderer, baseDepthVisShader);
                 }
                 flushLensflareOverlays(this.renderer, camera);
                 return;