three-base 2.0.137 → 2.0.145

package/pass/cover_pass.ts

@@ -0,0 +1,182 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-09-23 21:07:06
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2025-01-28 04:01:58
+ */
+/*
+ * @Author: xiaosihan
+ * @Date: 2023-05-09 00:35:17
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2023-05-09 02:33:28
+ */
+import { Color, DepthFormat, DepthTexture, LinearFilter, RGBAFormat, Scene, ShaderChunk, ShaderMaterial, UnsignedIntType, Vector2, WebGLRenderTarget, WebGLRenderer, Camera, PerspectiveCamera, Object3D } from "three";
+import fsQuad from "./fsQuad";
+import { EffectUserData } from "./effectUserData";
+import { debugDepthState } from "./debugDepthState";
+
+const selectDepthTexture: DepthTexture = (() => {
+    const baseDepthTexture = new DepthTexture(1024, 1024);
+    baseDepthTexture.format = DepthFormat;
+    baseDepthTexture.type = UnsignedIntType;
+    baseDepthTexture.anisotropy = 16;
+    return baseDepthTexture;
+})();
+
+const selectTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+    anisotropy: 16,
+    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，覆盖边缘锯齿。
+    // 边缘抗锯齿统一由终处理 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,
+    format: RGBAFormat,
+    anisotropy: 16,
+    // 无 MSAA：深度测试 mask 无需抗锯齿，去掉以提速
+});
+
+const blur1TextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+});
+
+const size: Vector2 = new Vector2();
+
+const depthTestShader: ShaderMaterial = new ShaderMaterial({
+    uniforms: {
+        color: { value: new Color("#440000") },
+        opacity: { value: 1 },
+        depthTest: { value: true },
+        baseDepth: { value: null },
+        selectDepth: { value: null },
+        cameraFar: { value: 1000.0 },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform vec3 color;
+        uniform float opacity;
+        uniform bool depthTest;
+        uniform sampler2D baseDepth;
+        uniform sampler2D selectDepth;
+        uniform float cameraFar;
+        varying vec2 vUv;
+        void main() {
+            if( depthTest ){
+                float coverBaseD = texture2D(baseDepth, vUv).r;
+                float coverSelD = texture2D(selectDepth, vUv).r;
+                // 对数深度反解成线性视图深度，线性空间做遮挡判定。
+                float zBase = pow(cameraFar + 1.0, coverBaseD) - 1.0;
+                float zSel  = pow(cameraFar + 1.0, coverSelD) - 1.0;
+                float bias = max(zSel, 1.0) * 0.0015;
+                // 该像素没有覆盖对象（selectDepth 仍是清屏值 1.0 → zSel == cameraFar）→ 不参与合成。
+                // ⚠️ 旧实现让背景像素「直接保留覆盖色」，导致没有对象的像素同样输出覆盖色
+                // → 整个场景被覆盖色染一层（与 frosted_glass / bloom 是同一个模板 bug）。
+                // 语义与下方 depthTest=false 分支的「selectDepth < 1.0 才输出」保持一致。
+                if (zSel >= cameraFar) {
+                    discard;
+                }
+                // 仅丢弃被更近场景几何遮挡的部分
+                if (zBase < zSel - bias) {
+                    discard;
+                }
+                gl_FragColor = vec4(color, opacity);
+            }else{
+               if(texture2D(selectDepth, vUv).r < 1.0){
+                    gl_FragColor = vec4(color, opacity);
+               }else{
+                   discard;
+               }
+            }
+
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: true,
+    depthWrite: true,
+    transparent: true,
+});
+
+const scene: Scene = new Scene();
+
+export default function cover_pass(
+    renderer: WebGLRenderer,
+    camera: Camera,
+    object3d: Object3D,
+    baseDepthTexture: DepthTexture,
+    devicePixelRatio: number
+): void {
+    const {
+        cover_enable = false,
+        cover_color = "#04fa12",
+        cover_opacity = 1,
+        cover_depth_test = true,
+    } = object3d.userData as EffectUserData;
+
+    if (!cover_enable || cover_opacity === 0) {
+        return;
+    }
+
+    const originRenderTarget = renderer.getRenderTarget();
+
+    // 灰度图渲染目标跟随主画面尺寸（= width × effectiveRatio），与 baseRenderTarget 完全一致，
+    // 消除灰度图与主画面尺寸不一致导致的放大重采样摩尔纹
+    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;
+    selectDepthTexture.image.height = size.y;
+    selectDepthTexture.needsUpdate = true;
+    selectDepthTestTextureTarget.setSize(size.x, size.y);
+    blur1TextureTarget.setSize(size.x, size.y);
+    renderer.setRenderTarget(selectTextureTarget);
+    scene.children = [object3d];
+    renderer.clear();
+    renderer.render(scene, camera);
+
+    // 单独渲染对象深度到无 MSAA 目标，供 depthTestShader 做遮挡判定
+    renderer.setRenderTarget(selectDepthTextureTarget);
+    scene.children = [object3d];
+    renderer.clear();
+    renderer.render(scene, camera);
+    // 调试：记录选区深度，供面板「深度判定图 / 辉光深度比对」排查 cover 的遮挡判定
+    debugDepthState.lastSelectDepth = selectDepthTexture;
+
+    renderer.setRenderTarget(originRenderTarget);
+    renderer.clearDepth();
+    depthTestShader.uniforms.color.value.set(cover_color);
+    depthTestShader.uniforms.opacity.value = cover_opacity;
+    depthTestShader.uniforms.depthTest.value = cover_depth_test;
+    depthTestShader.uniforms.baseDepth.value = baseDepthTexture;
+    depthTestShader.uniforms.selectDepth.value = selectDepthTexture;
+    depthTestShader.uniforms.cameraFar.value = (camera as PerspectiveCamera).far;
+    fsQuad.render(renderer, depthTestShader);
+}

package/pass/debugDepthState.d.ts

@@ -0,0 +1,20 @@
+import type { DepthTexture } from "three";
+/**
+ * 深度调试预览模式（面板按钮与控制台 `window.__TB_DEBUG_DEPTH` 共用同一枚举）：
+ *   - "none"    ：正常渲染（默认）
+ *   - "global"  ：全局深度图（baseDepthTexture，排除地板）
+ *   - "ao"      ：AO 深度图（aoDepthTexture，含地板）
+ *   - "compare" ：R=base 深度、G=选区 select 深度（对数反解后归一化）
+ *   - "judge"   ：R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)
+ *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=挡不住任何后处理）
+ */
+export type DebugDepthMode = "none" | "global" | "ao" | "compare" | "judge" | "excluded";
+/**
+ * 调试用全局状态：记录最近一次 glow_pass / stroke_pass 渲染的「选区自身深度图」(selectDepth)。
+ * 供 ThreeBase 渲染末尾的「辉光深度比对」调试视图读取（R=全局 base 深度，G=选区 select 深度），
+ * 让用户一眼看出到底是「全局 base 深度没写进」还是「选区自身深度没写进」。
+ * 由各 pass 在渲染完 selectDepth 后写入；每帧会被最后一个被处理的可见对象覆盖（调试够用）。
+ */
+export declare const debugDepthState: {
+    lastSelectDepth: DepthTexture | null;
+};

package/pass/debugDepthState.js

@@ -0,0 +1,9 @@
+/**
+ * 调试用全局状态：记录最近一次 glow_pass / stroke_pass 渲染的「选区自身深度图」(selectDepth)。
+ * 供 ThreeBase 渲染末尾的「辉光深度比对」调试视图读取（R=全局 base 深度，G=选区 select 深度），
+ * 让用户一眼看出到底是「全局 base 深度没写进」还是「选区自身深度没写进」。
+ * 由各 pass 在渲染完 selectDepth 后写入；每帧会被最后一个被处理的可见对象覆盖（调试够用）。
+ */
+export const debugDepthState = {
+    lastSelectDepth: null,
+};

package/pass/debugDepthState.ts

@@ -0,0 +1,22 @@
+import type { DepthTexture } from "three";
+
+/**
+ * 深度调试预览模式（面板按钮与控制台 `window.__TB_DEBUG_DEPTH` 共用同一枚举）：
+ *   - "none"    ：正常渲染（默认）
+ *   - "global"  ：全局深度图（baseDepthTexture，排除地板）
+ *   - "ao"      ：AO 深度图（aoDepthTexture，含地板）
+ *   - "compare" ：R=base 深度、G=选区 select 深度（对数反解后归一化）
+ *   - "judge"   ：R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)
+ *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=挡不住任何后处理）
+ */
+export type DebugDepthMode = "none" | "global" | "ao" | "compare" | "judge" | "excluded";
+
+/**
+ * 调试用全局状态：记录最近一次 glow_pass / stroke_pass 渲染的「选区自身深度图」(selectDepth)。
+ * 供 ThreeBase 渲染末尾的「辉光深度比对」调试视图读取（R=全局 base 深度，G=选区 select 深度），
+ * 让用户一眼看出到底是「全局 base 深度没写进」还是「选区自身深度没写进」。
+ * 由各 pass 在渲染完 selectDepth 后写入；每帧会被最后一个被处理的可见对象覆盖（调试够用）。
+ */
+export const debugDepthState: { lastSelectDepth: DepthTexture | null } = {
+    lastSelectDepth: null,
+};

package/pass/depthTestBias.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 深度遮挡判定容差（对数深度空间）—— 单一常量源。
+ *
+ * 语义：`baseD < selD - DEPTH_TEST_BIAS` 时判定「该像素被更近的真实几何挡住」→ discard。
+ * （DepthTexture 存的是对数深度，值越小越近。）
+ *
+ * ⚠️ 必须单一源：stroke_pass 的 depthTestShader 与调试用的 debugDepthJudgeShader
+ * 都依赖它。若两边各写一份字面量，改一边忘另一边 → 调试视图与真实判定不一致，
+ * 排查时会得出完全错误的结论（本次深度排查已踩过这类"两处漂移"的坑）。
+ * 护栏见 test/depthDebug.test.js C 组。
+ */
+export declare const DEPTH_TEST_BIAS = 0.0006;

package/pass/depthTestBias.js

@@ -0,0 +1,12 @@
+/**
+ * 深度遮挡判定容差（对数深度空间）—— 单一常量源。
+ *
+ * 语义：`baseD < selD - DEPTH_TEST_BIAS` 时判定「该像素被更近的真实几何挡住」→ discard。
+ * （DepthTexture 存的是对数深度，值越小越近。）
+ *
+ * ⚠️ 必须单一源：stroke_pass 的 depthTestShader 与调试用的 debugDepthJudgeShader
+ * 都依赖它。若两边各写一份字面量，改一边忘另一边 → 调试视图与真实判定不一致，
+ * 排查时会得出完全错误的结论（本次深度排查已踩过这类"两处漂移"的坑）。
+ * 护栏见 test/depthDebug.test.js C 组。
+ */
+export const DEPTH_TEST_BIAS = 0.0006;

package/pass/depthTestBias.ts

@@ -0,0 +1,12 @@
+/**
+ * 深度遮挡判定容差（对数深度空间）—— 单一常量源。
+ *
+ * 语义：`baseD < selD - DEPTH_TEST_BIAS` 时判定「该像素被更近的真实几何挡住」→ discard。
+ * （DepthTexture 存的是对数深度，值越小越近。）
+ *
+ * ⚠️ 必须单一源：stroke_pass 的 depthTestShader 与调试用的 debugDepthJudgeShader
+ * 都依赖它。若两边各写一份字面量，改一边忘另一边 → 调试视图与真实判定不一致，
+ * 排查时会得出完全错误的结论（本次深度排查已踩过这类"两处漂移"的坑）。
+ * 护栏见 test/depthDebug.test.js C 组。
+ */
+export const DEPTH_TEST_BIAS = 0.0006;

package/pass/effectUserData.d.ts

@@ -0,0 +1,27 @@
+/** 特效与鼠标事件共用的 userData 字段 */
+export interface EffectUserData {
+    stroke_enable?: boolean;
+    stroke_color?: string;
+    stroke_width?: number;
+    glow_enable?: boolean;
+    glow_color?: string;
+    glow_width?: number;
+    glow_opacity?: number;
+    glow_sigma?: number;
+    glow_threshold?: number;
+    glow_iterations?: number;
+    glow_intensity?: number;
+    glow_additive?: boolean;
+    glow_highlight_width?: number;
+    cover_enable?: boolean;
+    cover_color?: string;
+    cover_opacity?: number;
+    cover_depth_test?: boolean;
+    bloom_enable?: boolean;
+    bloom_threshold?: number;
+    bloom_strength?: number;
+    bloom_radius?: number;
+    frosted_glass_enable?: boolean;
+    cursor?: string;
+    enableEvent?: boolean;
+}

package/pass/effectUserData.js

@@ -0,0 +1 @@
+export {};

package/pass/effectUserData.ts

@@ -0,0 +1,46 @@
+/*
+ * @Author: software-engineer（寇豆码）
+ * @Description: 特效相关 userData 字段的统一类型定义。
+ * 覆盖 stroke / glow / cover / bloom / frosted_glass 等 pass 读取的全部开关字段，
+ * 以及 ThreeMouse 事件开关（cursor / enableEvent），供各 pass 用 `as EffectUserData`
+ * 取代各自内联的 `as { ... }`，避免类型散落与漂移。
+ */
+/** 特效与鼠标事件共用的 userData 字段 */
+export interface EffectUserData {
+    // ── stroke（描边）──
+    stroke_enable?: boolean;
+    stroke_color?: string;
+    stroke_width?: number;
+
+    // ── glow（辉光）──
+    glow_enable?: boolean;
+    glow_color?: string;
+    glow_width?: number;
+    glow_opacity?: number;
+    glow_sigma?: number;
+    glow_threshold?: number;
+    glow_iterations?: number;
+    glow_intensity?: number;   // 亮度倍增，可 >1 让光晕很亮（配合 glow_additive 发光叠加更明显）
+    glow_additive?: boolean;   // true=加性混合（发光叠加到画面），false=普通半透明覆盖（默认）
+    glow_highlight_width?: number; // 薄高亮层粗细（像素，默认 2）；始终绘制（=0 时扩张宽为 0、无可见环），无开关参数。
+                                   // 薄高亮层是 glow 的默认行为（贴物体边缘一圈更亮的细线），无需开启参数。
+
+    // ── cover（覆盖）──
+    cover_enable?: boolean;
+    cover_color?: string;
+    cover_opacity?: number;
+    cover_depth_test?: boolean;
+
+    // ── bloom（泛光）──
+    bloom_enable?: boolean;
+    bloom_threshold?: number;
+    bloom_strength?: number;
+    bloom_radius?: number;
+
+    // ── frosted glass（毛玻璃）──
+    frosted_glass_enable?: boolean;
+
+    // ── 鼠标事件开关（ThreeMouse）──
+    cursor?: string;
+    enableEvent?: boolean;
+}

package/pass/frosted_glass_pass.d.ts

@@ -1,2 +1,2 @@
-import { Camera, DepthTexture, Scene, WebGLRenderTarget, WebGLRenderer } from "three";
+import { DepthTexture, Scene, WebGLRenderTarget, WebGLRenderer, Camera } from "three";
 export default function frosted_glass_pass(renderer: WebGLRenderer, camera: Camera, scene: Scene, baseRenderTarget: WebGLRenderTarget, baseDepthTexture: DepthTexture, devicePixelRatio: number): void;

package/pass/frosted_glass_pass.js

@@ -4,31 +4,41 @@
  * @Last Modified by: xiaosihan
  * @Last Modified time: 2026-04-21 00:00:00
  */
-import { DepthFormat, DepthTexture, LinearFilter, RGBAFormat, Scene, ShaderChunk, ShaderMaterial, UnsignedShortType, Vector2, WebGLRenderTarget } from "three";
+import { DepthFormat, DepthTexture, LinearFilter, RGBAFormat, Scene, ShaderChunk, ShaderMaterial, UnsignedIntType, Vector2, WebGLRenderTarget } from "three";
 import fsQuad from "./fsQuad";
-// 深度测试后的毛玻璃遮罩纹理
-const maskTextureTarget = new WebGLRenderTarget(512, 512, {
+import { debugDepthState } from "./debugDepthState";
+const maskTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
     anisotropy: 16,
 });
-// 模糊后的纹理
 const blurTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
     anisotropy: 16,
 });
-// 临时模糊纹理（用于两阶段模糊）
 const tempBlurTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
     anisotropy: 16,
 });
+// 选中对象的遮罩渲染目标 + 配套深度纹理 + 临时场景：模块级复用，避免每帧 new/dispose 造成 GC 抖动与
+// GPU 资源反复创建销毁（原先在函数内每帧 new 一个 WebGLRenderTarget + DepthTexture + Scene，开销大且不稳）。
+const selectDepthTexture = new DepthTexture(1024, 1024);
+selectDepthTexture.format = DepthFormat;
+selectDepthTexture.type = UnsignedIntType;
+const selectTextureTarget = new WebGLRenderTarget(1024, 1024, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+    depthTexture: selectDepthTexture,
+});
+// 临时场景：仅用于把「毛玻璃对象」单独渲进 selectTextureTarget 做遮罩，常驻复用（不每帧 new）。
+const tempScene = new Scene();
 const size = new Vector2();
-// 水平模糊着色器（使用 three.js 风格的高斯模糊）
 const horizontalBlurShader = new ShaderMaterial({
     uniforms: {
         tDiffuse: { value: null },
@@ -63,7 +73,6 @@ const horizontalBlurShader = new ShaderMaterial({
     depthWrite: false,
     transparent: true,
 });
-// 垂直模糊着色器（使用 three.js 风格的高斯模糊）
 const verticalBlurShader = new ShaderMaterial({
     uniforms: {
         tDiffuse: { value: null },
@@ -98,11 +107,11 @@ const verticalBlurShader = new ShaderMaterial({
     depthWrite: false,
     transparent: true,
 });
-// 深度测试着色器（渲染毛玻璃对象，通过深度对比生成遮罩）
 const depthTestShader = new ShaderMaterial({
     uniforms: {
-        baseDepth: { value: null }, // 整个场景的深度纹理
-        selectDepth: { value: null }, // 毛玻璃对象的深度纹理
+        baseDepth: { value: null },
+        selectDepth: { value: null },
+        cameraFar: { value: 1000.0 },
     },
     vertexShader: `
         ${ShaderChunk.common}
@@ -118,22 +127,26 @@ const depthTestShader = new ShaderMaterial({
         ${ShaderChunk.logdepthbuf_pars_fragment}
         uniform sampler2D baseDepth;
         uniform sampler2D selectDepth;
+        uniform float cameraFar;
         varying vec2 vUv;
         void main() {
-            // 毛玻璃对象深度
             float selectDepthValue = texture2D(selectDepth, vUv).r;
-            // 场景深度
             float baseDepthValue = texture2D(baseDepth, vUv).r;
-
-            // 背景是空的时候丢弃（没有场景物体可模糊）
-            if(baseDepthValue >= 1.0){
+            // 对数深度反解为线性视图深度。
+            float zSel = pow(cameraFar + 1.0, selectDepthValue) - 1.0;
+            float zBase = pow(cameraFar + 1.0, baseDepthValue) - 1.0;
+            float bias = max(zSel, 1.0) * 0.0015;
+            // 该像素没有毛玻璃对象（selectDepth 仍是清屏值 1.0 → zSel == cameraFar）→ 不参与合成。
+            // ⚠️ 旧实现让背景像素「直接保留毛玻璃」，导致没有对象的像素同样写白 mask；
+            // 而 frostedGlassShader 是全屏 fsQuad，只要 mask.a>=0.01 就输出 blurTexture
+            // → 整个场景被糊一层（表现为"开启毛玻璃后全场景变模糊"）。
+            if (zSel >= cameraFar) {
                 discard;
             }
-            // 毛玻璃对象深度远于场景深度时丢弃（被场景物体遮挡的部分不显示）
-            if(selectDepthValue > baseDepthValue){
+            // 毛玻璃为实体：丢弃被更近场景几何遮挡的部分
+            if (zSel > zBase + bias) {
                 discard;
             }
-            // 输出白色遮罩，alpha=1
             gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
             ${ShaderChunk.logdepthbuf_fragment}
         }
@@ -142,11 +155,10 @@ const depthTestShader = new ShaderMaterial({
     depthWrite: true,
     transparent: true,
 });
-// 毛玻璃合成着色器（用遮罩纹理裁剪模糊区域）
 const frostedGlassShader = new ShaderMaterial({
     uniforms: {
-        blurTexture: { value: null }, // 高斯模糊后的全场景纹理
-        maskTexture: { value: null }, // 深度遮罩纹理
+        blurTexture: { value: null },
+        maskTexture: { value: null },
     },
     vertexShader: `
         varying vec2 vUv;
@@ -161,25 +173,24 @@ const frostedGlassShader = new ShaderMaterial({
         varying vec2 vUv;
 
         void main() {
-            // 采样遮罩纹理
             vec4 mask = texture2D(maskTexture, vUv);
 
-            // 遮罩区域为空时丢弃（非毛玻璃区域）
             if(mask.a < 0.01){
                 discard;
             }
 
-            // 在遮罩区域使用模糊后的纹理
-            gl_FragColor = sRGBTransferOETF(texture2D(blurTexture, vUv));
+            // 后处理全程在线性空间处理：blurTexture 来自 baseRenderTarget（线性格式，RawShaderMaterial
+            // 采样即为原始线性值，three 不会自动解码/编码），模糊混合后直接输出线性值写入线性目标，
+            // 由终处理 baseTextureToRenderShader 统一做唯一的 sRGB 编码。切勿在此手动 sRGBTransferOETF，
+            // 否则线性值被编码两次 sRGB，毛玻璃区域整体发白，与 screenCopy 的无损拷贝颜色空间不一致。
+            gl_FragColor = texture2D(blurTexture, vUv);
         }
     `,
     depthTest: true,
     depthWrite: true,
     transparent: false,
 });
-// 毛玻璃后处理通道
 export default function frosted_glass_pass(renderer, camera, scene, baseRenderTarget, baseDepthTexture, devicePixelRatio) {
-    // 收集所有启用了毛玻璃特效的 Mesh 对象
     const enabledObjects = [];
     scene.traverseVisible((obj) => {
         if (obj.userData.frosted_glass_enable && obj.isMesh) {
@@ -189,87 +200,57 @@ export default function frosted_glass_pass(renderer, camera, scene, baseRenderTa
     if (enabledObjects.length === 0) {
         return;
     }
-    // 保存原帧缓冲区
     const originRenderTarget = renderer.getRenderTarget();
-    // 按实际渲染尺寸调整所有 RenderTarget
+    // 灰度图渲染目标跟随主画面尺寸（= width × effectiveRatio），与 baseRenderTarget 完全一致，
+    // 消除灰度图与主画面尺寸不一致导致的放大重采样摩尔纹
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     maskTextureTarget.setSize(size.x, size.y);
     blurTextureTarget.setSize(size.x, size.y);
     tempBlurTextureTarget.setSize(size.x, size.y);
-    // ========== 第一步：对全场景纹理做高斯模糊（两遍，增强模糊效果） ==========
-    // 1. 第一阶段水平模糊
+    selectTextureTarget.setSize(size.x, size.y);
     renderer.setRenderTarget(tempBlurTextureTarget);
     renderer.clear();
     horizontalBlurShader.uniforms.tDiffuse.value = baseRenderTarget.texture;
     horizontalBlurShader.uniforms.h.value = 2.5 / size.x;
     fsQuad.render(renderer, horizontalBlurShader);
-    // 2. 第一阶段垂直模糊
     renderer.setRenderTarget(blurTextureTarget);
     renderer.clear();
     verticalBlurShader.uniforms.tDiffuse.value = tempBlurTextureTarget.texture;
     verticalBlurShader.uniforms.v.value = 2.5 / size.y;
     fsQuad.render(renderer, verticalBlurShader);
-    // 3. 第二阶段水平模糊
     renderer.setRenderTarget(tempBlurTextureTarget);
     renderer.clear();
     horizontalBlurShader.uniforms.tDiffuse.value = blurTextureTarget.texture;
     horizontalBlurShader.uniforms.h.value = 2.0 / size.x;
     fsQuad.render(renderer, horizontalBlurShader);
-    // 4. 第二阶段垂直模糊
     renderer.setRenderTarget(blurTextureTarget);
     renderer.clear();
     verticalBlurShader.uniforms.tDiffuse.value = tempBlurTextureTarget.texture;
     verticalBlurShader.uniforms.v.value = 2.0 / size.y;
     fsQuad.render(renderer, verticalBlurShader);
-    // ========== 第二步：渲染毛玻璃对象，提取深度遮罩 ==========
-    // 记录原始 parent，渲染完恢复
     const parents = enabledObjects.map(obj => obj.parent);
-    // 临时 RenderTarget 用于渲染毛玻璃对象（需要深度纹理）
-    const selectDepthTexture = new DepthTexture(Math.round(size.x), Math.round(size.y));
-    selectDepthTexture.format = DepthFormat;
-    selectDepthTexture.type = UnsignedShortType;
-    const selectTextureTarget = new WebGLRenderTarget(Math.round(size.x), Math.round(size.y), {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-        depthTexture: selectDepthTexture,
-    });
-    const tempScene = new Scene();
+    // selectTextureTarget / selectDepthTexture / tempScene 已在模块级复用，仅跟随主画面尺寸 resize，不每帧 new。
     enabledObjects.forEach(obj => tempScene.add(obj));
     renderer.setRenderTarget(selectTextureTarget);
     renderer.clear();
     renderer.render(tempScene, camera);
-    // 用深度测试 shader 生成遮罩
+    // 调试：记录选区深度，供面板「深度判定图 / 辉光深度比对」排查 frosted 的遮挡判定
+    debugDepthState.lastSelectDepth = selectDepthTexture;
     renderer.setRenderTarget(maskTextureTarget);
     renderer.clear();
     depthTestShader.uniforms.baseDepth.value = baseDepthTexture;
     depthTestShader.uniforms.selectDepth.value = selectTextureTarget.depthTexture;
+    depthTestShader.uniforms.cameraFar.value = camera.far;
     fsQuad.render(renderer, depthTestShader);
-    // 恢复所有对象的 parent
     enabledObjects.forEach((obj, i) => {
         if (parents[i]) {
             parents[i].add(obj);
         }
     });
-    // 释放临时的 RenderTarget
-    selectTextureTarget.dispose();
-    // ========== 第三步：合成毛玻璃效果 ==========
     renderer.setRenderTarget(originRenderTarget);
     renderer.clearDepth();
     frostedGlassShader.uniforms.blurTexture.value = blurTextureTarget.texture;
     frostedGlassShader.uniforms.maskTexture.value = maskTextureTarget.texture;
     fsQuad.render(renderer, frostedGlassShader);
-    // 调试代码：直接输出模糊纹理
-    // renderer.setRenderTarget(originRenderTarget);
-    // renderer.clear();
-    // baseTextureToRenderShader.uniforms.tDiffuse.value = blurTextureTarget.texture;
-    // fsQuad.render(renderer, baseTextureToRenderShader);
-    // return;
-    // 调试代码：直接输出遮罩纹理
-    // renderer.setRenderTarget(originRenderTarget);
-    // renderer.clear();
-    // baseTextureToRenderShader.uniforms.tDiffuse.value = maskTextureTarget.texture;
-    // fsQuad.render(renderer, baseTextureToRenderShader);
-    // return;
 }