three-base 2.0.169 → 2.0.175

package/pass/ssao_pass.ts

@@ -1,134 +1,48 @@
-import { Color, DataTexture, DoubleSide, LinearFilter, Material, MeshBasicMaterial, MeshNormalMaterial, NoBlending, Object3D, RGBAFormat, RawShaderMaterial, RepeatWrapping, Scene, Vector2, Vector3, WebGLRenderTarget, Matrix4, MultiplyBlending, WebGLRenderer, Camera, PerspectiveCamera, OrthographicCamera, DepthTexture, Texture } from "three";
+import { Color, DataTexture, LinearFilter, Material, MeshNormalMaterial, NoBlending, Object3D, RGBAFormat, RawShaderMaterial, RepeatWrapping, Scene, Vector2, Vector3, WebGLRenderTarget, Matrix4, MultiplyBlending, WebGLRenderer, Camera, PerspectiveCamera, OrthographicCamera, DepthTexture, Texture } from "three";
 import fsQuad from "./fsQuad";
 
 // ---------------------------------------------------------------------------
 // AO 数据准备 pass（深度 / 法线）
 // 这些逻辑原本散落在 ThreeBase.render() 里，现收敛到此模块，ThreeBase 只调用下面两个函数。
-// 固定排除两类不参与世界空间 AO 的对象，它们若写进深度/法线图，SSAO 会在其区域算错
-// AO 被乘黑：
-//   1) 非实体表面：sprite 及其子类、线条类（Line / Line2 等 fat-line）、点类（Points）。
-//      - sprite 是广告牌式 UI，不该写世界空间深度，且会错误遮挡身后几何；
-//      - 线条/点类在 MeshNormalMaterial override 下渲染异常（fat-line 实例段属性未处理、
-//        Points 无面法线），法线错乱 → GTAO 算出近 0 AO 被 Multiply 乘黑。
-//   2) 可透视的半透明表面（详见 isSeeThroughSurface）：会让「被它遮挡的区域」发黑。
-// 故在深度/法线 pass 前临时隐藏，pass 后恢复（记录 prev visible 避免误改用户隐藏的 UI）。
-//
-// ⚠️ 地板类半透明（Ground1 等，userData.aoFloor=true）是特例：它既要「作为实体参与 AO」
-// （物体落在它上需要接触 AO），又要「不遮挡透过它看到的物体」（从下方透视时，身后实体
-// 不应被它乘黑）。这两件事在同一张深度图里互斥，故拆成两张图：
-//   - 可见深度（baseDepthTexture，includeFloor=false）：地板按半透明排除 → 描边/辉光/毛玻璃
-//     的遮挡判定里，透过地板看到的物体照常显示（行为与以前一致）；同时它也是"真实可见表面"的参考。
-//   - AO 深度（= normalRenderTarget.depthTexture，法线 pass 顺带写入）：地板保留 → GTAO 能在接触处算出接触 AO。
-// 合成时若"含地板的 AO 深度"比"可见深度"更近（地板挡在真实可见表面之前），说明该像素是
-// 透过半透明地板看到的实体 → 地板算出的接触 AO 作废（=1），即"被遮挡的部分就不要 ssao"。
-// 用 isSprite / isLine / isLine2 / isLineSegments2 / isPoints 属性判断而非 instanceof：
-// 避免 three 子类场景下 instanceof 命中不到（如 SpriteText 等自定义 sprite 子类、
-// Line2 继承自 Mesh 非 Line）。
+// ⭐ 2026-10-18 皇上旨「所有的对象都要进入到深度图里面了，不需要用参数过滤掉了」⇒ 本模块原本的排除
+//   逻辑**整条删除**（含 excludeTransparent 参数、按材质 transparent 的判据、userData.aoFloor /
+//   aoTransparent / aoOpaque 三个标记、sprite/线条/点的无条件排除），两张深度图都收全场景对象。
+//   历史上这些排除是给 AO 兜底的，删掉后已知代价（皇上看过源码依据后确认接受）：
+//   - 半透明面（玻璃、霓虹灯管、光晕、特效载体）也参与 AO → 透过它们看到的实体可能被乘黑；
+//   - sprite / 线条 / 点在 MeshNormalMaterial override 下法线不可信 → 该区域 AO 可能出黑块；
+//   - 地板（Ground1）重新写进可见深度图 → 透过地板看到的实体，其描边/辉光/覆盖色/磨砂会被裁掉。
+//     10-12 旨「装饰地板需要透明」这次只保留**外观**（transparent + 径向 alpha 淡出 + depthWrite），
+//     遮挡侧的 aoFloor 例外随本旨拆除。
+//   出问题时用面板「深度调试 → 全局深度图 / AO深度图」两档定位是哪一侧。护栏：test/depthDebug.test.js J 组。
+// 两张图仍然都存在、不能合并（现在两者渲染范围一致，差别只剩「用什么材质渲染」）：
+//   - 可见深度（renderVisibleDepthPass，用各物体**自身材质**渲染）：自身材质 ⇒ 单面墙只记正面、
+//     alpha 抠图（树叶、带 discard 的自定义 shader）只记真正可见的像素 —— 特效遮挡必须吃这份保真度。
+//   - AO 深度（normalRenderTarget 的 depth attachment，法线 pass 顺带白拿）：override 材质是
+//     DoubleSide 且不做物体自己的 alpha discard，只能配法线给 GTAO 用；合成时靠 outputShader 那条
+//     「AO 侧比可见深度更近 → 作废该像素 AO」的守卫兜住两套渲染结果的错位（别当死代码删）。
 // ---------------------------------------------------------------------------
 
-type HiddenEntry = { obj: Object3D; prev: boolean };
-
-/**
- * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 AO 里充当实体。
- * 让它进入深度/法线图，被它遮挡的区域会发黑，成因分两种：
- *   a) transparent:true + opacity<1（毛玻璃、透明装饰）：深度图与法线图都落在半透明表面上，
- *      GTAO 在其表面算自遮蔽（褶皱、紧贴其它几何的窄缝）→ 这份 AO 被乘到「透过它看到的
- *      实体」上 → 该区域发黑。
- *   b) transparent:true + depthWrite:false（霓虹灯管、光晕、叠加面）：深度图保留身后几何（远），
- *      但法线 pass 用 overrideMaterial（MeshNormalMaterial 默认 depthWrite:true）会强行把它的
- *      法线写进去（近）→ 深度与法线指的不是同一个点 → GTAO 几乎必然算错发黑。
- * 故深度 pass 与法线 pass 统一隐藏：该像素的深度/法线即身后不透明几何，AO 由真实可见几何
- * 决定；身后是背景时深度为 1.0，shader 守卫直接判「无遮蔽」(=1)，不会发黑。
- *
- * 判据只看 material.transparent 本身，不再依赖 opacity / depthWrite（2026-08-30 修正）：
- * 大量半透明是自定义 ShaderMaterial，alpha 由 shader 算出来，而材质的 opacity 仍是默认 1、
- * depthWrite 仍是 true —— 典型如 Ground1 地板（mapColor.a 径向渐变）、聚光灯光斑、
- * effectMaterial1，靠材质属性完全读不出来，会被漏判并继续污染 AO。
- * 代价：Mirror 这类「标了 transparent 但 shader 实际输出 alpha=1.0」的实心反射面会被误排除，
- * 故 Mirror 在构造函数里显式标记 userData.aoOpaque = true 保留（见各 Mirror 实现）。
- * 其余特例同样可用 userData.aoTransparent=true 强制排除 / userData.aoOpaque=true 强制保留。
- *
- * @param includeFloor 是否为「含地板」的 AO 数据准备（GTAO 深度/法线）。
- *   - false（默认，可见深度 / 描边/辉光/毛玻璃遮挡判定）：地板按普通半透明排除。
- *   - true（AO 深度）：标了 userData.aoFloor 的地板保留为实体，参与接触 AO 计算。
- */
-/**
- * 可见深度图的运行时开关：**标了 `userData.aoFloor` 的地板是否参与遮挡判定**。
- *
- * 默认 false = 保持原设计（可透视地板：透过地板看到的物体照常显示，不被地板挡住）。
- * 置 true 后，地板会写进 baseDepthTexture，于是**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
- * 面板「深度调试 → 地板参与遮挡」可一键切换，用于排查"挡不住"是不是地板（如 Ground1）造成的。
- *
- * 只影响 aoFloor 地板这一类；transparent 面的处理不受影响（见 isSeeThroughSurface）。
- */
-export const visibleDepthOptions: { includeFloor: boolean } = { includeFloor: false };
-
-const isSeeThroughSurface = (obj: Object3D, includeFloor = false): boolean => {
-    const o = obj as Object3D & { material?: Material | Material[] };
-    const userData = o.userData as { aoTransparent?: boolean; aoOpaque?: boolean; aoFloor?: boolean } | undefined;
-    if (userData && userData.aoOpaque === true) return false;
-    if (userData && userData.aoTransparent === true) return true;
-    // 地板类半透明：可见深度（includeFloor=false，描边/辉光/毛玻璃/覆盖色遮挡判定用）里排除
-    // → 可透视，透过地板看到的物体照常显示；AO 深度（includeFloor=true）里保留 → 接触 AO。
-    // ⚠️ 例外：visibleDepthOptions.includeFloor=true 时，可见深度里也保留地板 → 地板能挡住特效。
-    if (userData && userData.aoFloor === true) {
-        return includeFloor ? false : !visibleDepthOptions.includeFloor;
-    }
-    const mat = o.material;
-    if (!mat) return false;
-    const list: Material[] = Array.isArray(mat) ? mat : [mat];
-    const transparent = list.some((m) => m !== null && m.transparent === true);
-    // ⚠️ 关键修复（2026-09-06 回归根因）：可见深度（includeFloor=false）必须把"标了
-    // transparent 但实为实心/不透明"的面当作实体参与遮挡——three-base 大量面（玻璃、特效载体、
-    // alpha 贴图实体、半透明墙）都标了 transparent:true；若在此排除，它们就不再遮挡身后特效，
-    // 所有依赖 baseDepthTexture 的深度测试（描边/辉光/毛玻璃/覆盖色）全部失效、一律显示在前面。
-    // 仅 AO 深度（includeFloor=true）需要排除透明面，避免 GTAO 在半透明面上算错发黑（保留原 AO 修复）。
-    return includeFloor && transparent;
-};
-
-const isNonSurface = (obj: Object3D, includeFloor = false): boolean => {
-    const o = obj as { isSprite?: boolean; isLine?: boolean; isLine2?: boolean; isLineSegments2?: boolean; isPoints?: boolean };
-    if (o.isSprite === true || o.isLine === true || o.isLine2 === true || o.isLineSegments2 === true || o.isPoints === true) {
-        return true;
-    }
-    return isSeeThroughSurface(obj, includeFloor);
-};
-
-const hideNonSurface = (scene: Object3D, includeFloor = false): HiddenEntry[] => {
-    const list: HiddenEntry[] = [];
-    scene.traverse((obj: Object3D) => {
-        if (isNonSurface(obj, includeFloor)) {
-            list.push({ obj, prev: obj.visible });
-            obj.visible = false;
-        }
-    });
-    return list;
-};
-
-const restoreVisibility = (list: HiddenEntry[]): void => {
-    list.forEach(({ obj, prev }) => (obj.visible = prev));
-};
-
 /**
- * 深度 pass：固定排除非实体表面后，将场景深度渲染到 depthRenderTarget。
- * depthRenderTarget.depthTexture 即 baseDepthTexture，供 SSAO / 描边 / 发光等后续 pass 复用。
- * 排除的非实体对象（sprite/线条/点）在深度图保留 clear 深度(1.0=远)，与背景一致；排除的
- * 半透明对象则保留其身后不透明几何的深度（身后无几何时同样为 1.0）。均不影响颜色通道渲染。
+ * 可见深度 pass：用**各物体自身的材质**把整个场景的深度渲染到 depthRenderTarget。
+ * depthRenderTarget.depthTexture 即 baseDepthTexture，供描边 / 发光 / 覆盖 / 磨砂的遮挡判定，
+ * 也是 SSAO 合成时「真实可见表面」的参考。
+ * 2026-10-18 起**不排除任何对象**（皇上旨「所有的对象都要进入到深度图里面了，不需要用参数过滤掉了」）：
+ * 场景里所有对象都参与这一趟，只有使用者自己 `visible = false` 的对象除外（那是显隐意图，本 pass 不碰）。
+ * ⚠️ 名字里的 ao 已不适用（2026-10-11 改名自 renderAoDepthPass）：它产出的是**可见深度**，
+ *   AO 自己的深度挂在法线 pass 上（见 renderAoNormalPass）。
  */
-export function renderAoDepthPass(
+export function renderVisibleDepthPass(
     renderer: WebGLRenderer,
     camera: Camera,
     scene: Scene,
-    depthRenderTarget: WebGLRenderTarget,
-    includeFloor = false
+    depthRenderTarget: WebGLRenderTarget
 ): void {
-    const hidden = hideNonSurface(scene, includeFloor);
-    // ⚠️ 深度预通道铁律：必须让所有「未被排除」的可见表面都写入深度，深度图才有真实的几何遮挡信息。
+    // ⚠️ 深度预通道铁律：必须让所有可见表面都写入深度，深度图才有真实的几何遮挡信息。
     // 透明材质（特效载体、半透明墙、alpha 贴图实体等）大多 transparent:true 且 depthWrite:false，
     // 若不强转，它们不会写进 baseDepthTexture → 深度图只剩不透明几何 → 描边/辉光/毛玻璃/覆盖色
-    // 依赖 baseDepthTexture 的遮挡判定全部失效、一律显示在前（即本次回归根因）。
-    // 被排除的半透明面（aoTransparent / aoFloor / Mirror-aoOpaque 等）已在 hideNonSurface 中隐藏，
-    // 此处根本不会触及，故不影响 see-through 设计；其余透明面强制写深度 = 作为实体参与遮挡，符合预期。
+    // 依赖 baseDepthTexture 的遮挡判定全部失效、一律显示在前（即 2026-09-06 那次回归根因）。
+    // 只强转 Mesh：sprite / 线条 / 点的材质默认就是 depthWrite:true，且叠加式光晕一旦强写深度会在
+    // 深度图上打洞、错误遮挡身后特效，故沿用原判据范围，不扩大。
     const depthWriteRestore: { mat: Material; val: boolean }[] = [];
     scene.traverse((obj: Object3D) => {
         const mesh = obj as Object3D & { isMesh?: boolean; material?: Material | Material[] };
@@ -147,91 +61,28 @@ export function renderAoDepthPass(
     renderer.render(scene, camera);
     // 还原 depthWrite，避免污染后续颜色通道渲染的透明混合
     depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
-    restoreVisibility(hidden);
     renderer.setRenderTarget(prevRenderTarget);
 }
 
 /**
- * 调试用：把「被排除出可见深度图」的表面单独渲成红色 mask。
- *
- * 这些面在 renderAoDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
- * 也就永远挡不住描边/辉光/毛玻璃/覆盖色 —— 这正是"深度测试看起来失效"最常见的成因
- * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent、
- * 以及标了 userData.aoFloor 的地板 Ground1）。
- * 面板「深度调试 → 排除面标记」叠加显示：灰=能挡住的真实遮挡面，红=被排除、挡不住任何东西。
- *
- * 只渲染 Mesh：sprite / Line2 / Points 在 MeshBasicMaterial override 下渲染异常（见文件头注释），
- * 且它们数量少、用户关心的遮挡体基本都是 Mesh，故跳过。
- */
-export function renderExcludedMaskPass(
-    renderer: WebGLRenderer,
-    camera: Camera,
-    scene: Scene,
-    maskRenderTarget: WebGLRenderTarget,
-    includeFloor = false
-): void {
-    const maskMaterial = new MeshBasicMaterial({
-        color: 0xff0000,
-        depthTest: false,
-        depthWrite: false,
-        side: DoubleSide,
-    });
-    const prevVisible: HiddenEntry[] = [];
-    scene.traverse((obj: Object3D) => {
-        const isMesh = (obj as Object3D & { isMesh?: boolean }).isMesh === true;
-        prevVisible.push({ obj, prev: obj.visible });
-        // 只显示「被排除的 Mesh」：其余一律隐藏，得到纯黑底 + 红面的 mask
-        obj.visible = isMesh && isNonSurface(obj, includeFloor);
-    });
-
-    const prevOverride = scene.overrideMaterial;
-    const prevTarget = renderer.getRenderTarget();
-    const prevClear = renderer.getClearColor(new Color());
-    const prevAlpha = renderer.getClearAlpha();
-
-    scene.overrideMaterial = maskMaterial;
-    renderer.setRenderTarget(maskRenderTarget);
-    renderer.setClearColor(0x000000, 1);
-    renderer.clear();
-    renderer.render(scene, camera);
-
-    renderer.setClearColor(prevClear, prevAlpha);
-    renderer.setRenderTarget(prevTarget);
-    scene.overrideMaterial = prevOverride;
-    restoreVisibility(prevVisible);
-    maskMaterial.dispose();
-}
-
-/**
- * 法线 pass（仅 SSAO 开启时需要）：固定排除非实体表面后，以中性灰清屏 + normalMaterial
- * override 将视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
- * 排除对象在法线图保留中性灰清屏色 → unpackRGBToNormal(0.5,0.5,0.5)=(0,0,0) →
- * SSAO 退化法线守卫判"无遮蔽"(=1)，避免精灵弹窗被 AO 乘黑。清屏色用后即还原。
+ * 法线 pass（仅 SSAO 开启时需要）：以中性灰清屏 + normalMaterial override 将整个场景的
+ * 视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
+ * 2026-10-18 起同样不排除任何对象（与 renderVisibleDepthPass 一致，见文件头那道旨及其代价清单）。
+ * 深度白拿：normalRenderTarget 挂着 aoDepthTexture 作 depth attachment，这一趟的深度由光栅器
+ * 顺带写入 → 就是 AO 用的深度，无需再单独渲一遍（2026-09-14）。
  */
 export function renderAoNormalPass(
     renderer: WebGLRenderer,
     camera: Camera,
     scene: Scene,
     normalRenderTarget: WebGLRenderTarget,
-    normalMaterial: MeshNormalMaterial,
-    includeFloor = false
+    normalMaterial: MeshNormalMaterial
 ): void {
-    const hidden = hideNonSurface(scene, includeFloor);
-    // ⚠️ 与 renderAoDepthPass 同款「强制写深度」：本 pass 的深度会被当作含地板 AO 深度使用
-    // （normalRenderTarget.depthTexture）。透明面若因 depthWrite:false 不写深度，AO 深度就会漏掉它们，
-    // 与被本 pass 取代的那次独立深度 pass 内容不一致。pass 结束后立即还原。
-    const depthWriteRestore: { mat: Material; val: boolean }[] = [];
-    scene.traverse((obj: Object3D) => {
-        const mesh = obj as Object3D & { isMesh?: boolean; material?: Material | Material[] };
-        if (!mesh.isMesh || !mesh.material) return;
-        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
-        list.forEach((m) => {
-            if (m && (m as Material).depthWrite === false) {
-                depthWriteRestore.push({ mat: m as Material, val: false });
-                (m as Material).depthWrite = true;
-            }
-        });
-    });
+    // ⚠️ 2026-10-11 删掉了这里原有的「强制 depthWrite=true」整段遍历：scene.overrideMaterial 生效后，
+    // three 用的是 **override 材质**的渲染状态（WebGLRenderer.renderObjects：
+    // `material = overrideMaterial === null ? renderItem.material : overrideMaterial`，setDepthState 吃它），
+    // 物体自己材质的 depthWrite 根本读不到 ⇒ 那段是空转。需要强转的是用自身材质渲染的
+    // renderVisibleDepthPass（那边保留）。
     const prevRenderTarget = renderer.getRenderTarget();
     const prevClearColor = new Color();
     renderer.getClearColor(prevClearColor);
@@ -242,8 +93,6 @@ export function renderAoNormalPass(
     scene.overrideMaterial = normalMaterial;
     renderer.render(scene, camera);
     scene.overrideMaterial = null;
-    restoreVisibility(hidden);
-    depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
     renderer.setClearColor(prevClearColor, prevClearAlpha);
     renderer.setRenderTarget(prevRenderTarget);
 }
@@ -721,9 +570,9 @@ const outputShader: RawShaderMaterial = new RawShaderMaterial({
         ssaoTexture: { value: null },
         ssaoStrength: { value: 1.0 },
         debug: { value: 0.0 },
-        // 可见深度（排除地板，= baseDepthTexture）：代表"真实可见表面"的深度。
+        // 可见深度（用自身材质渲染，含地板）= baseDepthTexture：代表"真实可见表面"的深度。
         tColorDepth: { value: null as DepthTexture | null },
-        // AO 深度（含地板，= normalRenderTarget.depthTexture，法线 pass 顺带写入）：GTAO 实际采样的深度。
+        // AO 深度（= normalRenderTarget.depthTexture，法线 pass 顺带写入）。
         tAoDepth: { value: null as DepthTexture | null },
     },
     vertexShader: `
@@ -750,10 +599,15 @@ const outputShader: RawShaderMaterial = new RawShaderMaterial({
     void main() {
       float ssao = texture2D(ssaoTexture, vUv).r;
 
-      // 复合守卫：对数深度越小越近。若"含地板的 AO 深度"比"可见深度"更近，
-      // 说明该像素的真实可见表面位于半透明地板之后（典型的从下方透视地板看身后实体），
-      // 地板算出的接触 AO 不该乘到它身上 → 视为无遮蔽(=1)，即"被遮挡的部分就不要 ssao"。
-      // 仅在最终合成时生效；debug 模式直接看 GTAO 原始 AO 图（含地板接触 AO），便于排查。
+      // 复合守卫：对数深度越小越近。若"AO 深度"比"可见深度"更近，说明该像素上法线趟
+      // （override 材质：DoubleSide、不做物体自己的 alpha discard）记到一个**屏幕上根本不可见**的面
+      // —— 典型如树叶抠图的空隙、单面墙的背面。此时深度与法线指的不是人眼看到的那个点，
+      // GTAO 算出的 AO 不可信 → 视为无遮蔽(=1)。
+      // ⚠️ 2026-10-18：两张图的渲染范围已统一（皇上旨「所有的对象都要进入到深度图里面了」⇒ excludeTransparent
+      //      参数与 aoFloor 特例整条拆除），本守卫不再承担「地板的接触 AO 别乘黑身后实体」这类职责，
+      //      它守的是上面那类 override 材质 / 自身材质两套渲染结果的错位（抠图空隙、单面墙背面、
+      //      DoubleSide 记到背面），别当死代码删。
+      // 仅在最终合成时生效；debug 模式直接看 GTAO 原始 AO 图，便于排查。
       float dColor = texture2D(tColorDepth, vUv).r;
       float dAo = texture2D(tAoDepth, vUv).r;
       if (debug < 0.5 && dAo < dColor - 0.0001) {
@@ -821,17 +675,19 @@ export default function ssao_pass(
     // 覆盖 SSAO 自身的硬边。改动调用顺序时，本 pass 无需修改（输出到"绑定的那个目标"即可）。
     const originRenderTarget = renderer.getRenderTarget();
 
-    // 法线 pass：地板保留（includeFloor=true），接触 AO 需要地板的视图空间法线。
+    // 法线 pass：整个场景都渲（2026-10-18 起不再按 transparent / aoFloor 排除任何面，见文件头那道旨）。
     // ⭐ 深度白拿（2026-09-14 优化）：normalRenderTarget 挂着 aoDepthTexture 作 depth attachment，
-    // 这一次渲染的深度由光栅器顺带写入 → 直接就是「含地板」的 AO 深度，**不再单独渲一遍深度 pass**。
-    // （原先法线 pass 之后还要再渲一遍「含地板深度」——它与法线 pass 的排除集完全相同，
+    // 这一次渲染的深度由光栅器顺带写入 → 直接就是 AO 深度，**不再单独渲一遍深度 pass**。
+    // （原先法线 pass 之后还要再渲一遍「AO 深度」——它与法线 pass 的渲染集完全相同，
     //   属于重复遍历全场景，2026-09-14 已删。）
-    // 前提：renderAoNormalPass 内部已把 depthWrite=false 的透明材质强转 true，保证写入面集合一致。
-    renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial, true);
+    // ⚠️ 这一趟的深度是 override 材质写的（DoubleSide、不做物体自己的 alpha discard），
+    //   所以只能给 AO 用；特效遮挡吃的是下面那张「用自身材质渲染」的可见深度。
+    renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial);
 
-    // 可见深度（地板排除）= baseDepthTexture，既是描边/辉光/毛玻璃的遮挡参考，也是"真实可见表面"参考。
+    // 可见深度（用各物体自身材质渲染，含地板）= baseDepthTexture：描边/辉光/毛玻璃/覆盖色的遮挡参考，
+    // 也是复合守卫里「真实可见表面」的参考。
     const colorDepthTexture = depthRenderTarget.depthTexture as DepthTexture;
-    // AO 深度（含地板）：GTAO 与去噪采样它，能算出物体落在地板上的接触 AO。
+    // AO 深度：GTAO 与去噪采样它（与上面的法线同一次光栅化，深度-法线永远同源）。
     const aoDepthTexture = normalRenderTarget.depthTexture as DepthTexture;
     const normalTexture = normalRenderTarget.texture;
 
@@ -906,8 +762,8 @@ export default function ssao_pass(
 
     renderer.setRenderTarget(originRenderTarget);
     outputShader.uniforms.ssaoTexture.value = blurTextureTarget.texture;
-    // 复合守卫：可见深度（地板排除）与 AO 深度（含地板）两图比对，
-    // 地板挡在真实可见表面之前时作废地板的接触 AO（见 outputShader 注释）。
+    // 复合守卫：可见深度（自身材质渲染）与 AO 深度（override 渲染）两图比对，
+    // AO 侧更近 = 那像素记到屏幕上不可见的面（抠图空隙/单面墙背面）→ 作废该像素 AO（见 outputShader 注释）。
     outputShader.uniforms.tColorDepth.value = colorDepthTexture;
     outputShader.uniforms.tAoDepth.value = aoDepthTexture;
     // 叠加强度：finalOcclusion = mix(1.0, ao, strength)，0 = 完全不叠加 AO，1 = 原始强度，>1 外插加深。

package/pass/stroke_pass.js

@@ -15,23 +15,20 @@ const selectDepthTexture = (() => {
     baseDepthTexture.anisotropy = 16;
     return baseDepthTexture;
 })();
+// ⭐ 2026-10-11 皇上旨「简化渲染，少渲两遍」：selectDepthTexture 直接挂在 mask 目标上当
+// depth attachment —— 深度是光栅器的副产品（零额外代价），mask 那一次渲染顺带把它写进来。
+// 原先还要为同一个对象再单独渲一趟「只出深度」（同材质、同相机、同几何 ⇒ 深度值逐位相同），
+// stroke/glow/cover/bloom 四个 pass 各一遍 ⇒ 每个带特效的对象每帧白渲 4 趟，已整条删除。
 const selectTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，描边边缘锯齿。
     // 边缘抗锯齿统一由 mask 内部 FXAA + 终处理 FXAA 兜底。
 });
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
 const selectDepthTestTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -503,7 +500,6 @@ export default function stroke_pass(renderer, camera, object3d, baseDepthTexture
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 尺寸与全屏 baseDepth 对齐，否则深度比例错位导致描边被错误 discard
     selectDepthTexture.image.width = size.x;
@@ -515,16 +511,14 @@ export default function stroke_pass(renderer, camera, object3d, baseDepthTexture
     selectDepthBlurTmpTextureTarget.setSize(size.x, size.y);
     selectDepthBlurTextureTarget.setSize(size.x, size.y);
     blurDepthTestTextureTarget.setSize(size.x, size.y);
-    // 1. 渲染物体本体 mask（灰度）
+    // 1. 渲染物体本体 mask（灰度）。⭐ 本体深度由同一趟光栅化顺带写进 selectDepthTexture
+    //   （挂在 selectTextureTarget 的 depth attachment 上）—— 原先这里还有第 2 趟「只渲深度」，
+    //   同材质/同相机/同几何 ⇒ 深度逐位相同，纯重复遍历，2026-10-11 皇上旨简化时删除。
+    //   （下面的步骤编号保留 3/4/5…，别处注释按号交叉引用，不随之重排。）
     renderer.setRenderTarget(selectTextureTarget);
     scene.children = [object3d];
     renderer.clear();
     renderer.render(scene, camera);
-    // 2. 渲染物体本体深度（无 MSAA，供 depthTest 判定遮挡）
-    renderer.setRenderTarget(selectDepthTextureTarget);
-    scene.children = [object3d];
-    renderer.clear();
-    renderer.render(scene, camera);
     // 调试：把本次渲染的选区深度记到全局调试状态，供面板「辉光深度比对」读取
     debugDepthState.lastSelectDepth = selectDepthTexture;
     // 3. 深度测试（用本体 mask）：被真实更近物体挡住的「本体描边」部分 discard。
@@ -580,6 +574,9 @@ export default function stroke_pass(renderer, camera, object3d, baseDepthTexture
     depthMinBlurShader.uniforms.tDepth.value = selectDepthBlurTmpTextureTarget.texture;
     renderer.setRenderTarget(selectDepthBlurTextureTarget);
     fsQuad.render(renderer, depthMinBlurShader);
+    // 调试：记录「外扩后的选区深度」，供面板「深度图（分步）」的步骤 5.5 档读取。
+    // 它是 RGBA8 目标、对数深度存在 .r 里（与 DepthTexture 取 .r 的读法一致）。
+    debugDepthState.lastSelectBlurDepth = selectDepthBlurTextureTarget.texture;
     // 5.6 对外扩后的描边判遮挡：被更近几何挡住的外扩环像素 discard。
     //     ⚠️ 输出到独立 target，绝不回写 blur1（历史回归 bug：blur1 被 depthTest 结果覆盖
     //        会导致步骤 6 相减归零、描边全不显示）。

package/pass/stroke_pass.ts

@@ -18,25 +18,21 @@ const selectDepthTexture: DepthTexture = (() => {
     return baseDepthTexture;
 })();
 
+// ⭐ 2026-10-11 皇上旨「简化渲染，少渲两遍」：selectDepthTexture 直接挂在 mask 目标上当
+// depth attachment —— 深度是光栅器的副产品（零额外代价），mask 那一次渲染顺带把它写进来。
+// 原先还要为同一个对象再单独渲一趟「只出深度」（同材质、同相机、同几何 ⇒ 深度值逐位相同），
+// stroke/glow/cover/bloom 四个 pass 各一遍 ⇒ 每个带特效的对象每帧白渲 4 趟，已整条删除。
 const selectTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，描边边缘锯齿。
     // 边缘抗锯齿统一由 mask 内部 FXAA + 终处理 FXAA 兜底。
 });
 
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
-
 const selectDepthTestTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -532,7 +528,6 @@ export default function stroke_pass(
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 尺寸与全屏 baseDepth 对齐，否则深度比例错位导致描边被错误 discard
     selectDepthTexture.image.width = size.x;
@@ -545,17 +540,14 @@ export default function stroke_pass(
     selectDepthBlurTextureTarget.setSize(size.x, size.y);
     blurDepthTestTextureTarget.setSize(size.x, size.y);
 
-    // 1. 渲染物体本体 mask（灰度）
+    // 1. 渲染物体本体 mask（灰度）。⭐ 本体深度由同一趟光栅化顺带写进 selectDepthTexture
+    //   （挂在 selectTextureTarget 的 depth attachment 上）—— 原先这里还有第 2 趟「只渲深度」，
+    //   同材质/同相机/同几何 ⇒ 深度逐位相同，纯重复遍历，2026-10-11 皇上旨简化时删除。
+    //   （下面的步骤编号保留 3/4/5…，别处注释按号交叉引用，不随之重排。）
     renderer.setRenderTarget(selectTextureTarget);
     scene.children = [object3d];
     renderer.clear();
     renderer.render(scene, camera);
-
-    // 2. 渲染物体本体深度（无 MSAA，供 depthTest 判定遮挡）
-    renderer.setRenderTarget(selectDepthTextureTarget);
-    scene.children = [object3d];
-    renderer.clear();
-    renderer.render(scene, camera);
     // 调试：把本次渲染的选区深度记到全局调试状态，供面板「辉光深度比对」读取
     debugDepthState.lastSelectDepth = selectDepthTexture;
 
@@ -616,6 +608,10 @@ export default function stroke_pass(
     renderer.setRenderTarget(selectDepthBlurTextureTarget);
     fsQuad.render(renderer, depthMinBlurShader);
 
+    // 调试：记录「外扩后的选区深度」，供面板「深度图（分步）」的步骤 5.5 档读取。
+    // 它是 RGBA8 目标、对数深度存在 .r 里（与 DepthTexture 取 .r 的读法一致）。
+    debugDepthState.lastSelectBlurDepth = selectDepthBlurTextureTarget.texture;
+
     // 5.6 对外扩后的描边判遮挡：被更近几何挡住的外扩环像素 discard。
     //     ⚠️ 输出到独立 target，绝不回写 blur1（历史回归 bug：blur1 被 depthTest 结果覆盖
     //        会导致步骤 6 相减归零、描边全不显示）。

package/shaders/baseDepthVisShader.d.ts

@@ -2,7 +2,7 @@ import { ShaderMaterial } from "three";
 /**
  * 调试用：把 baseDepthTexture（可见深度图）直接以灰度输出到屏幕。
  * 对数深度：近=0(黑) 远=1(白)。
- *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderAoDepthPass 没把深度写进 baseDepthTexture；
+ *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderVisibleDepthPass 没把深度写进 baseDepthTexture；
  *                 此时所有依赖深度遮挡的后处理(stroke/glow/cover/frosted)都会"一律显示在前"。
  *   - 有灰阶/明暗  → 深度图正常，问题在比对侧(selectDepth / depthTestShader)。
  * 触发：在控制台执行 `window.__BASE_DEPTH_VIS = true` 后画面即切到该视图。

package/shaders/baseDepthVisShader.js

@@ -2,7 +2,7 @@ import { ShaderChunk, ShaderMaterial } from "three";
 /**
  * 调试用：把 baseDepthTexture（可见深度图）直接以灰度输出到屏幕。
  * 对数深度：近=0(黑) 远=1(白)。
- *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderAoDepthPass 没把深度写进 baseDepthTexture；
+ *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderVisibleDepthPass 没把深度写进 baseDepthTexture；
  *                 此时所有依赖深度遮挡的后处理(stroke/glow/cover/frosted)都会"一律显示在前"。
  *   - 有灰阶/明暗  → 深度图正常，问题在比对侧(selectDepth / depthTestShader)。
  * 触发：在控制台执行 `window.__BASE_DEPTH_VIS = true` 后画面即切到该视图。

package/shaders/baseDepthVisShader.ts

@@ -2,7 +2,7 @@ import { ShaderChunk, ShaderMaterial } from "three";
 /**
  * 调试用：把 baseDepthTexture（可见深度图）直接以灰度输出到屏幕。
  * 对数深度：近=0(黑) 远=1(白)。
- *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderAoDepthPass 没把深度写进 baseDepthTexture；
+ *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderVisibleDepthPass 没把深度写进 baseDepthTexture；
  *                 此时所有依赖深度遮挡的后处理(stroke/glow/cover/frosted)都会"一律显示在前"。
  *   - 有灰阶/明暗  → 深度图正常，问题在比对侧(selectDepth / depthTestShader)。
  * 触发：在控制台执行 `window.__BASE_DEPTH_VIS = true` 后画面即切到该视图。

package/shaders/debugDepthCompareShader.d.ts

@@ -2,10 +2,10 @@ import { ShaderMaterial } from "three";
 /**
  * 调试用：把「全局 base 深度」与「最近一次 glow/stroke 选区的 select 深度」并排显示，
  * 用于排查"深度测试全部失效"根因：
- *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   R = 全局 base 深度（baseDepthTexture，2026-10-18 起含全部对象、含地板）
  *   G = 选区自身深度（selectDepthTexture，由 glow_pass/stroke_pass 渲染后写入 debugDepthState）
  * 两路都用 `pow(cameraFar+1, d)-1` 反推到近似线性视深再归一化（背景≈1 → 黄白）。
- *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderAoDepthPass 失效），但选区深度正常；
+ *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderVisibleDepthPass 失效），但选区深度正常；
  *   - R、G 都全白       → 两路深度都没写进；
  *   - R 有灰阶、G 全白   → 选区深度没写进（glow/stroke 自身的深度 pass 失效）；
  *   - R、G 都有灰阶      → 深度正常，问题在 depthTestShader 比对侧。

package/shaders/debugDepthCompareShader.js

@@ -2,10 +2,10 @@ import { ShaderChunk, ShaderMaterial } from "three";
 /**
  * 调试用：把「全局 base 深度」与「最近一次 glow/stroke 选区的 select 深度」并排显示，
  * 用于排查"深度测试全部失效"根因：
- *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   R = 全局 base 深度（baseDepthTexture，2026-10-18 起含全部对象、含地板）
  *   G = 选区自身深度（selectDepthTexture，由 glow_pass/stroke_pass 渲染后写入 debugDepthState）
  * 两路都用 `pow(cameraFar+1, d)-1` 反推到近似线性视深再归一化（背景≈1 → 黄白）。
- *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderAoDepthPass 失效），但选区深度正常；
+ *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderVisibleDepthPass 失效），但选区深度正常；
  *   - R、G 都全白       → 两路深度都没写进；
  *   - R 有灰阶、G 全白   → 选区深度没写进（glow/stroke 自身的深度 pass 失效）；
  *   - R、G 都有灰阶      → 深度正常，问题在 depthTestShader 比对侧。

package/shaders/debugDepthCompareShader.ts

@@ -3,10 +3,10 @@ import { ShaderChunk, ShaderMaterial } from "three";
 /**
  * 调试用：把「全局 base 深度」与「最近一次 glow/stroke 选区的 select 深度」并排显示，
  * 用于排查"深度测试全部失效"根因：
- *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   R = 全局 base 深度（baseDepthTexture，2026-10-18 起含全部对象、含地板）
  *   G = 选区自身深度（selectDepthTexture，由 glow_pass/stroke_pass 渲染后写入 debugDepthState）
  * 两路都用 `pow(cameraFar+1, d)-1` 反推到近似线性视深再归一化（背景≈1 → 黄白）。
- *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderAoDepthPass 失效），但选区深度正常；
+ *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderVisibleDepthPass 失效），但选区深度正常；
  *   - R、G 都全白       → 两路深度都没写进；
  *   - R 有灰阶、G 全白   → 选区深度没写进（glow/stroke 自身的深度 pass 失效）；
  *   - R、G 都有灰阶      → 深度正常，问题在 depthTestShader 比对侧。

package/shaders/debugDepthJudgeShader.d.ts

@@ -3,7 +3,7 @@ import { ShaderMaterial } from "three";
  * 调试用：把「深度测试判定」本身画出来，用于定位"后处理深度测试全部失效"。
  *
  * 通道语义（全部为**原始**深度值，不做对数反解，避免饱和丢信息）：
- *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   R = 全局 base 深度（baseDepthTexture，2026-10-18 起含全部对象、含地板）
  *   G = 选区自身深度（selectDepthTexture，glow/stroke 渲染后写入 debugDepthState）
  *   B = 判定结果：baseD < selD - bias ? 1 : 0
  *       与 stroke_pass 的 depthTestShader 同一判定式（bias = 0.0006）：

package/shaders/debugDepthJudgeShader.js

@@ -4,7 +4,7 @@ import { DEPTH_TEST_BIAS } from "../pass/depthTestBias";
  * 调试用：把「深度测试判定」本身画出来，用于定位"后处理深度测试全部失效"。
  *
  * 通道语义（全部为**原始**深度值，不做对数反解，避免饱和丢信息）：
- *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   R = 全局 base 深度（baseDepthTexture，2026-10-18 起含全部对象、含地板）
  *   G = 选区自身深度（selectDepthTexture，glow/stroke 渲染后写入 debugDepthState）
  *   B = 判定结果：baseD < selD - bias ? 1 : 0
  *       与 stroke_pass 的 depthTestShader 同一判定式（bias = 0.0006）：

package/shaders/debugDepthJudgeShader.ts

@@ -5,7 +5,7 @@ import { DEPTH_TEST_BIAS } from "../pass/depthTestBias";
  * 调试用：把「深度测试判定」本身画出来，用于定位"后处理深度测试全部失效"。
  *
  * 通道语义（全部为**原始**深度值，不做对数反解，避免饱和丢信息）：
- *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   R = 全局 base 深度（baseDepthTexture，2026-10-18 起含全部对象、含地板）
  *   G = 选区自身深度（selectDepthTexture，glow/stroke 渲染后写入 debugDepthState）
  *   B = 判定结果：baseD < selD - bias ? 1 : 0
  *       与 stroke_pass 的 depthTestShader 同一判定式（bias = 0.0006）：