three-base 2.0.142 → 2.0.166

package/pass/screen_bloom_pass.d.ts

@@ -1,11 +1,11 @@
-import { WebGLRenderTarget, WebGLRenderer } from "three";
-interface ScreenBloomConfig {
-    /** 叠加强度 */
-    strength: number;
-    /** 模糊扩散（0~1）：映射高斯偏移步长，越大越柔 */
-    radius: number;
-    /** 亮部软阈值（0~1）：仅亮度高于此值的像素参与辉光 */
-    threshold: number;
-}
-export default function screenBloomPass(renderer: WebGLRenderer, sourceRenderTarget: WebGLRenderTarget, config: ScreenBloomConfig): void;
-export {};
+import { WebGLRenderTarget, WebGLRenderer } from "three";
+interface ScreenBloomConfig {
+    /** 叠加强度 */
+    strength: number;
+    /** 模糊扩散（0~1）：映射高斯偏移步长，越大越柔 */
+    radius: number;
+    /** 亮部软阈值（0~1）：仅亮度高于此值的像素参与辉光 */
+    threshold: number;
+}
+export default function screenBloomPass(renderer: WebGLRenderer, sourceRenderTarget: WebGLRenderTarget, config: ScreenBloomConfig): void;
+export {};

package/pass/screen_bloom_pass.js

@@ -1,37 +1,37 @@
-/*
- * @Author: xiaosihan / WorkBuddy
- * @Description: 屏幕空间辉光（经典 gaussian bloom）。
- *   替代 three 自带的 UnrealBloomPass——后者用 5 级离散 mip（1/2…1/32）各自模糊后直接相加，
- *   级与级覆盖范围跳跃，strength 偏高时暴露成同心亮环（"一层一层"）。
- *   本实现改用「亮部提取(soft-knee 防硬边) → 半分辨率多次可分离高斯模糊迭代(单分辨率连续扩散) → 加性叠加」，
- *   模糊是连续平滑的，与 glow_pass / bloom_pass 的发光风格一致，边缘柔和、无分层。
- *   依赖 renderer.autoClear=false（ThreeBase 第 236 行），故 composite 在 screenRenderTarget 上做加性叠加不会清空原图。
- */
-import { AdditiveBlending, LinearFilter, NoBlending, RawShaderMaterial, RGBAFormat, Vector2, WebGLRenderTarget } from "three";
-import fsQuad from "./fsQuad";
-const halfSize = new Vector2(1, 1);
-const highPassTarget = new WebGLRenderTarget(1, 1, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-});
-const blurTargetA = new WebGLRenderTarget(1, 1, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-});
-const blurTargetB = new WebGLRenderTarget(1, 1, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-});
-// 亮部提取：带 soft-knee 软过渡，避免阈值硬截断产生硬边（硬边会被后续模糊放大成可见光环）
-const highPassShader = new RawShaderMaterial({
-    uniforms: {
-        tDiffuse: { value: null },
-        threshold: { value: 0.85 },
-        knee: { value: 0.1 },
-    },
+/*
+ * @Author: xiaosihan / WorkBuddy
+ * @Description: 屏幕空间辉光（经典 gaussian bloom）。
+ *   替代 three 自带的 UnrealBloomPass——后者用 5 级离散 mip（1/2…1/32）各自模糊后直接相加，
+ *   级与级覆盖范围跳跃，strength 偏高时暴露成同心亮环（"一层一层"）。
+ *   本实现改用「亮部提取(soft-knee 防硬边) → 半分辨率多次可分离高斯模糊迭代(单分辨率连续扩散) → 加性叠加」，
+ *   模糊是连续平滑的，与 glow_pass / bloom_pass 的发光风格一致，边缘柔和、无分层。
+ *   依赖 renderer.autoClear=false（ThreeBase 第 236 行），故 composite 在 screenRenderTarget 上做加性叠加不会清空原图。
+ */
+import { AdditiveBlending, LinearFilter, NoBlending, RawShaderMaterial, RGBAFormat, Vector2, WebGLRenderTarget } from "three";
+import fsQuad from "./fsQuad";
+const halfSize = new Vector2(1, 1);
+const highPassTarget = new WebGLRenderTarget(1, 1, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+});
+const blurTargetA = new WebGLRenderTarget(1, 1, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+});
+const blurTargetB = new WebGLRenderTarget(1, 1, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+});
+// 亮部提取：带 soft-knee 软过渡，避免阈值硬截断产生硬边（硬边会被后续模糊放大成可见光环）
+const highPassShader = new RawShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        threshold: { value: 0.85 },
+        knee: { value: 0.1 },
+    },
     vertexShader: `
         attribute vec3 position;
         attribute vec2 uv;
@@ -39,7 +39,7 @@ const highPassShader = new RawShaderMaterial({
         void main() {
             vUv = uv;
             gl_Position = vec4(position, 1.0);
-        }`,
+        }`,
     fragmentShader: `
         #ifdef GL_ES
             precision highp float;
@@ -55,21 +55,21 @@ const highPassShader = new RawShaderMaterial({
             float soft = clamp((lum - threshold + knee) / (2.0 * knee), 0.0, 1.0);
             float contrib = max(soft * soft, lum - threshold) / max(lum, 1e-4);
             gl_FragColor = vec4(texel.rgb * contrib, 1.0);
-        }`,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-// 可分离高斯模糊（H / V），与 glow_pass 同结构：21-tap 固定，radius 控制偏移步长，sigma 控制权重形状。
-// 多迭代后在单分辨率上等价一个大半径高斯，过渡完全连续 —— 这是均匀、无分层的根本。
-const gaussianBlurHShader = new RawShaderMaterial({
-    uniforms: {
-        tDiffuse: { value: null },
-        resolution: { value: new Vector2(1 / 512, 1 / 512) },
-        radius: { value: 1.0 },
-        sigma: { value: 1.0 },
-    },
+        }`,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+// 可分离高斯模糊（H / V），与 glow_pass 同结构：21-tap 固定，radius 控制偏移步长，sigma 控制权重形状。
+// 多迭代后在单分辨率上等价一个大半径高斯，过渡完全连续 —— 这是均匀、无分层的根本。
+const gaussianBlurHShader = new RawShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        resolution: { value: new Vector2(1 / 512, 1 / 512) },
+        radius: { value: 1.0 },
+        sigma: { value: 1.0 },
+    },
     vertexShader: `
         attribute vec3 position;
         attribute vec2 uv;
@@ -77,7 +77,7 @@ const gaussianBlurHShader = new RawShaderMaterial({
         void main() {
             vUv = uv;
             gl_Position = vec4(position, 1.0);
-        }`,
+        }`,
     fragmentShader: `
         #ifdef GL_ES
             precision highp float;
@@ -101,19 +101,19 @@ const gaussianBlurHShader = new RawShaderMaterial({
                 totalWeight += weight;
             }
             gl_FragColor = color / totalWeight;
-        }`,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-const gaussianBlurVShader = new RawShaderMaterial({
-    uniforms: {
-        tDiffuse: { value: null },
-        resolution: { value: new Vector2(1 / 512, 1 / 512) },
-        radius: { value: 1.0 },
-        sigma: { value: 1.0 },
-    },
+        }`,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+const gaussianBlurVShader = new RawShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        resolution: { value: new Vector2(1 / 512, 1 / 512) },
+        radius: { value: 1.0 },
+        sigma: { value: 1.0 },
+    },
     vertexShader: `
         attribute vec3 position;
         attribute vec2 uv;
@@ -121,7 +121,7 @@ const gaussianBlurVShader = new RawShaderMaterial({
         void main() {
             vUv = uv;
             gl_Position = vec4(position, 1.0);
-        }`,
+        }`,
     fragmentShader: `
         #ifdef GL_ES
             precision highp float;
@@ -145,18 +145,18 @@ const gaussianBlurVShader = new RawShaderMaterial({
                 totalWeight += weight;
             }
             gl_FragColor = color / totalWeight;
-        }`,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-// 加性合成：把模糊后的泛光按强度叠加回屏幕合成目标（autoClear=false，不清空原图）
-const compositeShader = new RawShaderMaterial({
-    uniforms: {
-        tDiffuse: { value: null },
-        strength: { value: 1.0 },
-    },
+        }`,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+// 加性合成：把模糊后的泛光按强度叠加回屏幕合成目标（autoClear=false，不清空原图）
+const compositeShader = new RawShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        strength: { value: 1.0 },
+    },
     vertexShader: `
         attribute vec3 position;
         attribute vec2 uv;
@@ -164,7 +164,7 @@ const compositeShader = new RawShaderMaterial({
         void main() {
             vUv = uv;
             gl_Position = vec4(position, 1.0);
-        }`,
+        }`,
     fragmentShader: `
         #ifdef GL_ES
             precision highp float;
@@ -175,61 +175,61 @@ const compositeShader = new RawShaderMaterial({
         void main() {
             vec4 texel = texture2D(tDiffuse, vUv);
             gl_FragColor = vec4(texel.rgb * strength, 1.0);
-        }`,
-    blending: AdditiveBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-export default function screenBloomPass(renderer, sourceRenderTarget, config) {
-    const { strength, radius, threshold } = config;
-    if (strength <= 0) {
-        return;
-    }
-    // 半分辨率：降采样既提速，又让扩散更平滑自然（避免全分辨率下模糊核偏硬）
-    const w = Math.max(1, sourceRenderTarget.width >> 1);
-    const h = Math.max(1, sourceRenderTarget.height >> 1);
-    halfSize.set(w, h);
-    highPassTarget.setSize(w, h);
-    blurTargetA.setSize(w, h);
-    blurTargetB.setSize(w, h);
-    // 1) 亮部提取
-    renderer.setRenderTarget(highPassTarget);
-    renderer.clear();
-    highPassShader.uniforms.tDiffuse.value = sourceRenderTarget.texture;
-    highPassShader.uniforms.threshold.value = threshold;
-    fsQuad.render(renderer, highPassShader);
-    // 2) 多次可分离高斯模糊迭代：单分辨率连续扩散，无 mip 分层
-    const blurRadius = 1.0 + radius * 8.0; // radius 0~1 → 偏移 1~9 像素（half 分辨率下已足够大）
-    gaussianBlurHShader.uniforms.resolution.value.set(1 / w, 1 / h);
-    gaussianBlurVShader.uniforms.resolution.value.set(1 / w, 1 / h);
-    gaussianBlurHShader.uniforms.radius.value = blurRadius;
-    gaussianBlurVShader.uniforms.radius.value = blurRadius;
-    gaussianBlurHShader.uniforms.sigma.value = 1.0;
-    gaussianBlurVShader.uniforms.sigma.value = 1.0;
-    renderer.setRenderTarget(blurTargetA);
-    renderer.clear();
-    gaussianBlurHShader.uniforms.tDiffuse.value = highPassTarget.texture;
-    fsQuad.render(renderer, gaussianBlurHShader);
-    renderer.setRenderTarget(blurTargetB);
-    renderer.clear();
-    gaussianBlurVShader.uniforms.tDiffuse.value = blurTargetA.texture;
-    fsQuad.render(renderer, gaussianBlurVShader);
-    // 反复 H/V 迭代，扩散越大、越均匀。共 6 趟（H+V 各 6 次）已非常平滑。
-    const passes = 6;
-    for (let i = 1; i < passes; i++) {
-        renderer.setRenderTarget(blurTargetA);
-        renderer.clear();
-        gaussianBlurHShader.uniforms.tDiffuse.value = blurTargetB.texture;
-        fsQuad.render(renderer, gaussianBlurHShader);
-        renderer.setRenderTarget(blurTargetB);
-        renderer.clear();
-        gaussianBlurVShader.uniforms.tDiffuse.value = blurTargetA.texture;
-        fsQuad.render(renderer, gaussianBlurVShader);
-    }
-    // 3) 加性合成回屏幕合成目标（不 clear，叠加在已有合成图上）
-    renderer.setRenderTarget(sourceRenderTarget);
-    compositeShader.uniforms.tDiffuse.value = blurTargetB.texture;
-    compositeShader.uniforms.strength.value = strength;
-    fsQuad.render(renderer, compositeShader);
-}
+        }`,
+    blending: AdditiveBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default function screenBloomPass(renderer, sourceRenderTarget, config) {
+    const { strength, radius, threshold } = config;
+    if (strength <= 0) {
+        return;
+    }
+    // 半分辨率：降采样既提速，又让扩散更平滑自然（避免全分辨率下模糊核偏硬）
+    const w = Math.max(1, sourceRenderTarget.width >> 1);
+    const h = Math.max(1, sourceRenderTarget.height >> 1);
+    halfSize.set(w, h);
+    highPassTarget.setSize(w, h);
+    blurTargetA.setSize(w, h);
+    blurTargetB.setSize(w, h);
+    // 1) 亮部提取
+    renderer.setRenderTarget(highPassTarget);
+    renderer.clear();
+    highPassShader.uniforms.tDiffuse.value = sourceRenderTarget.texture;
+    highPassShader.uniforms.threshold.value = threshold;
+    fsQuad.render(renderer, highPassShader);
+    // 2) 多次可分离高斯模糊迭代：单分辨率连续扩散，无 mip 分层
+    const blurRadius = 1.0 + radius * 8.0; // radius 0~1 → 偏移 1~9 像素（half 分辨率下已足够大）
+    gaussianBlurHShader.uniforms.resolution.value.set(1 / w, 1 / h);
+    gaussianBlurVShader.uniforms.resolution.value.set(1 / w, 1 / h);
+    gaussianBlurHShader.uniforms.radius.value = blurRadius;
+    gaussianBlurVShader.uniforms.radius.value = blurRadius;
+    gaussianBlurHShader.uniforms.sigma.value = 1.0;
+    gaussianBlurVShader.uniforms.sigma.value = 1.0;
+    renderer.setRenderTarget(blurTargetA);
+    renderer.clear();
+    gaussianBlurHShader.uniforms.tDiffuse.value = highPassTarget.texture;
+    fsQuad.render(renderer, gaussianBlurHShader);
+    renderer.setRenderTarget(blurTargetB);
+    renderer.clear();
+    gaussianBlurVShader.uniforms.tDiffuse.value = blurTargetA.texture;
+    fsQuad.render(renderer, gaussianBlurVShader);
+    // 反复 H/V 迭代，扩散越大、越均匀。共 6 趟（H+V 各 6 次）已非常平滑。
+    const passes = 6;
+    for (let i = 1; i < passes; i++) {
+        renderer.setRenderTarget(blurTargetA);
+        renderer.clear();
+        gaussianBlurHShader.uniforms.tDiffuse.value = blurTargetB.texture;
+        fsQuad.render(renderer, gaussianBlurHShader);
+        renderer.setRenderTarget(blurTargetB);
+        renderer.clear();
+        gaussianBlurVShader.uniforms.tDiffuse.value = blurTargetA.texture;
+        fsQuad.render(renderer, gaussianBlurVShader);
+    }
+    // 3) 加性合成回屏幕合成目标（不 clear，叠加在已有合成图上）
+    renderer.setRenderTarget(sourceRenderTarget);
+    compositeShader.uniforms.tDiffuse.value = blurTargetB.texture;
+    compositeShader.uniforms.strength.value = strength;
+    fsQuad.render(renderer, compositeShader);
+}

package/pass/ssao_pass.d.ts

@@ -1,88 +1,88 @@
-import { MeshNormalMaterial, Scene, WebGLRenderTarget, WebGLRenderer, Camera } from "three";
-/**
- * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 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 declare const visibleDepthOptions: {
-    includeFloor: boolean;
-};
-/**
- * 深度 pass：固定排除非实体表面后，将场景深度渲染到 depthRenderTarget。
- * depthRenderTarget.depthTexture 即 baseDepthTexture，供 SSAO / 描边 / 发光等后续 pass 复用。
- * 排除的非实体对象（sprite/线条/点）在深度图保留 clear 深度(1.0=远)，与背景一致；排除的
- * 半透明对象则保留其身后不透明几何的深度（身后无几何时同样为 1.0）。均不影响颜色通道渲染。
- */
-export declare function renderAoDepthPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, depthRenderTarget: WebGLRenderTarget, includeFloor?: boolean): void;
-/**
- * 调试用：把「被排除出可见深度图」的表面单独渲成红色 mask。
- *
- * 这些面在 renderAoDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
- * 也就永远挡不住描边/辉光/毛玻璃/覆盖色 —— 这正是"深度测试看起来失效"最常见的成因
- * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent、
- * 以及标了 userData.aoFloor 的地板 Ground1）。
- * 面板「深度调试 → 排除面标记」叠加显示：灰=能挡住的真实遮挡面，红=被排除、挡不住任何东西。
- *
- * 只渲染 Mesh：sprite / Line2 / Points 在 MeshBasicMaterial override 下渲染异常（见文件头注释），
- * 且它们数量少、用户关心的遮挡体基本都是 Mesh，故跳过。
- */
-export declare function renderExcludedMaskPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, maskRenderTarget: WebGLRenderTarget, includeFloor?: boolean): void;
-/**
- * 法线 pass（仅 SSAO 开启时需要）：固定排除非实体表面后，以中性灰清屏 + normalMaterial
- * override 将视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
- * 排除对象在法线图保留中性灰清屏色 → unpackRGBToNormal(0.5,0.5,0.5)=(0,0,0) →
- * SSAO 退化法线守卫判"无遮蔽"(=1)，避免精灵弹窗被 AO 乘黑。清屏色用后即还原。
- */
-export declare function renderAoNormalPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, normalRenderTarget: WebGLRenderTarget, normalMaterial: MeshNormalMaterial, includeFloor?: boolean): void;
-export interface SsaoOptions {
-    enable: boolean;
-    debug?: boolean;
-    radius?: number;
-    falloff?: number;
-    /** 旧版螺旋采样用到的切面距离阈值，GTAO 算法不再使用，保留字段仅作兼容 */
-    bias?: number;
-    /** 映射为 GTAO 的 scale（AO 次幂 / gamma 校正），控制 AO 对比强度，默认 1.0 */
-    intensity?: number;
-    /** 采样总数（编译期常量，改变会触发 shader 重新编译），默认 16 */
-    sampleCount?: number;
-    blurRadius?: number;
-    strength?: number;
-    cameraFar?: number;
-    /** SSAO 计算分辨率缩放比例，默认 0.5（半分辨率计算，性能更好） */
-    resolutionScale?: number;
-    /** GTAO 地平线积分：采样点沿半径分布的幂次，默认 1.0 */
-    distanceExponent?: number;
-    /** GTAO 地平线积分：距离衰减混合系数，默认 1.0 */
-    distanceFallOff?: number;
-    /** AO 次幂（gamma 校正），默认 1.0（与 intensity 共享语义时可只调其一） */
-    scale?: number;
-}
-export default function ssao_pass(renderer: WebGLRenderer, camera: Camera, scene: Scene, depthRenderTarget: WebGLRenderTarget, normalRenderTarget: WebGLRenderTarget, normalMaterial: MeshNormalMaterial, devicePixelRatio: number, options: SsaoOptions): void;
+import { MeshNormalMaterial, Scene, WebGLRenderTarget, WebGLRenderer, Camera } from "three";
+/**
+ * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 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 declare const visibleDepthOptions: {
+    includeFloor: boolean;
+};
+/**
+ * 深度 pass：固定排除非实体表面后，将场景深度渲染到 depthRenderTarget。
+ * depthRenderTarget.depthTexture 即 baseDepthTexture，供 SSAO / 描边 / 发光等后续 pass 复用。
+ * 排除的非实体对象（sprite/线条/点）在深度图保留 clear 深度(1.0=远)，与背景一致；排除的
+ * 半透明对象则保留其身后不透明几何的深度（身后无几何时同样为 1.0）。均不影响颜色通道渲染。
+ */
+export declare function renderAoDepthPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, depthRenderTarget: WebGLRenderTarget, includeFloor?: boolean): void;
+/**
+ * 调试用：把「被排除出可见深度图」的表面单独渲成红色 mask。
+ *
+ * 这些面在 renderAoDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
+ * 也就永远挡不住描边/辉光/毛玻璃/覆盖色 —— 这正是"深度测试看起来失效"最常见的成因
+ * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent、
+ * 以及标了 userData.aoFloor 的地板 Ground1）。
+ * 面板「深度调试 → 排除面标记」叠加显示：灰=能挡住的真实遮挡面，红=被排除、挡不住任何东西。
+ *
+ * 只渲染 Mesh：sprite / Line2 / Points 在 MeshBasicMaterial override 下渲染异常（见文件头注释），
+ * 且它们数量少、用户关心的遮挡体基本都是 Mesh，故跳过。
+ */
+export declare function renderExcludedMaskPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, maskRenderTarget: WebGLRenderTarget, includeFloor?: boolean): void;
+/**
+ * 法线 pass（仅 SSAO 开启时需要）：固定排除非实体表面后，以中性灰清屏 + normalMaterial
+ * override 将视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
+ * 排除对象在法线图保留中性灰清屏色 → unpackRGBToNormal(0.5,0.5,0.5)=(0,0,0) →
+ * SSAO 退化法线守卫判"无遮蔽"(=1)，避免精灵弹窗被 AO 乘黑。清屏色用后即还原。
+ */
+export declare function renderAoNormalPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, normalRenderTarget: WebGLRenderTarget, normalMaterial: MeshNormalMaterial, includeFloor?: boolean): void;
+export interface SsaoOptions {
+    enable: boolean;
+    debug?: boolean;
+    radius?: number;
+    falloff?: number;
+    /** 旧版螺旋采样用到的切面距离阈值，GTAO 算法不再使用，保留字段仅作兼容 */
+    bias?: number;
+    /** 映射为 GTAO 的 scale（AO 次幂 / gamma 校正），控制 AO 对比强度，默认 1.0 */
+    intensity?: number;
+    /** 采样总数（编译期常量，改变会触发 shader 重新编译），默认 16 */
+    sampleCount?: number;
+    blurRadius?: number;
+    strength?: number;
+    cameraFar?: number;
+    /** SSAO 计算分辨率缩放比例，默认 0.5（半分辨率计算，性能更好） */
+    resolutionScale?: number;
+    /** GTAO 地平线积分：采样点沿半径分布的幂次，默认 1.0 */
+    distanceExponent?: number;
+    /** GTAO 地平线积分：距离衰减混合系数，默认 1.0 */
+    distanceFallOff?: number;
+    /** AO 次幂（gamma 校正），默认 1.0（与 intensity 共享语义时可只调其一） */
+    scale?: number;
+}
+export default function ssao_pass(renderer: WebGLRenderer, camera: Camera, scene: Scene, depthRenderTarget: WebGLRenderTarget, normalRenderTarget: WebGLRenderTarget, normalMaterial: MeshNormalMaterial, devicePixelRatio: number, options: SsaoOptions): void;