three-base 2.0.134 → 2.0.142

package/ThreeBase.d.ts

@@ -1,97 +1,248 @@
-import { AxesHelper, DepthTexture, EventDispatcher, GridHelper, Object3D, OrthographicCamera, PerspectiveCamera, Scene, Texture, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
-import ThreeMouse from "./ThreeMouse";
-import Transition from "./Transition";
-export default class ThreeBase extends EventDispatcher {
-    constructor();
-    minDevicePixelRatio: number;
-    baseDepthTexture: DepthTexture;
-    baseRenderTarget: WebGLRenderTarget<Texture>;
-    depthRenderTarget: WebGLRenderTarget<Texture>;
-    renderTarget: WebGLRenderTarget<Texture>;
-    renderTarget2: WebGLRenderTarget<Texture>;
-    tempVector2: Vector2;
-    tempVector3: Vector3;
-    size: Vector2;
-    rendererLost: boolean;
-    renderer: WebGLRenderer;
-    perspectiveCamera: PerspectiveCamera;
-    orthographicCamera: OrthographicCamera;
-    cameraType: "perspectiveCamera" | "orthographicCamera";
-    setCameraType(cameraType: "perspectiveCamera" | "orthographicCamera"): void;
-    getCamera(): PerspectiveCamera | OrthographicCamera;
-    scene: Scene;
-    add(...object: Object3D[]): this;
-    threeMouse: ThreeMouse;
-    controls: any;
-    setContainer(div: HTMLDivElement | null): Promise<void>;
-    setSize(width: number, height: number): void;
-    controlsDistanceTransition: Transition<{
-        distance: number;
-    }, "distance">;
-    controlsYTransition: Transition<{
-        y: number;
-    }, "y">;
-    controlsXZTransition: Transition<{
-        x: number;
-        z: number;
-    }, "x" | "z">;
-    controlsCenter: Transition<{
-        x: number;
-        y: number;
-        z: number;
-    }, "x" | "y" | "z">;
-    controlsPosition: Transition<{
-        x: number;
-        y: number;
-        z: number;
-    }, "x" | "y" | "z">;
-    gridHelper: GridHelper;
-    axesHelper: AxesHelper;
-    frame: number;
-    init(): void;
-    resetLookAt({ position, center, }: {
-        position: Vector3;
-        center: Vector3;
-    }): void;
-    setLookAt({ position, center, duration, }: {
-        position: Vector3;
-        center: Vector3;
-        duration?: number;
-    }): Promise<void>;
-    getLookAt(): {
-        center: Vector3;
-        position: Vector3;
-        centerPosition: string;
-    };
-    lookatObjects({ objects, duration, direction, offset, distance, }: {
-        objects: Array<Object3D>;
-        duration?: number;
-        direction?: Vector3;
-        offset?: Vector3;
-        distance?: number;
-    }): void;
-    v3tov2(v3: Vector3): Vector2;
-    controlType: "OrbitControls" | "MapControls";
-    originScreenSpacePanning: boolean;
-    setControlType(controlType: "OrbitControls" | "MapControls"): void;
-    autoRender: boolean;
-    needRender: boolean;
-    ssao: {
-        enable: boolean;
-        radius: number;
-        bias: number;
-        intensity: number;
-        sampleCount: number;
-        blurRadius: number;
-        strength: number;
-    };
-    stopRender(): void;
-    render(): void;
-    private renderBindThis;
-    getThumbBlob(): Promise<Blob>;
-    getThumbBase64(): string;
-    getThumbFile(): Promise<File>;
-    download(fileName?: string): Promise<void>;
-    renderRendererTarget(renderTarget: WebGLRenderTarget): void;
-    renderTexture(texture: Texture, alpha?: boolean): void;
-}
+import { AxesHelper, DepthTexture, EventDispatcher, GridHelper, MeshNormalMaterial, Object3D, OrthographicCamera, PerspectiveCamera, Scene, Texture, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+import ThreeMouse from "./ThreeMouse";
+import InstancedGroup from "./instanced/InstancedGroup";
+import Transition from "./Transition";
+import { type DebugDepthMode } from "./pass/debugDepthState";
+import { WaterFlow } from "./WaterFlow/WaterFlow";
+import type { ThreeBaseEventTypeMap } from "./EventMap";
+type CameraType = "perspectiveCamera" | "orthographicCamera";
+type ControlType = "OrbitControls" | "MapControls";
+interface SSAOConfig {
+    enable: boolean;
+    debug: boolean;
+    radius: number;
+    falloff: number;
+    bias: number;
+    /** AO 叠加强度：finalOcclusion = mix(1.0, ao, intensity)。0 = 不叠加，1 = 原始强度，>1 外插加深。默认 1.0 */
+    intensity: number;
+    sampleCount: number;
+    /** 去噪（模糊）最大采样半径，单位 = 像素，默认 4。1 = 几乎不去噪 */
+    blurRadius: number;
+    /** 与 intensity 同义的备用名，两者都设时以 strength 为准 */
+    strength: number;
+    /** SSAO 计算分辨率缩放比例，默认 0.5（半分辨率计算，性能更好） */
+    resolutionScale?: number;
+    /** GTAO 地平线积分：采样点沿半径分布的幂次，默认 1.0 */
+    distanceExponent?: number;
+    /** GTAO 地平线积分：距离衰减混合系数，默认 1.0 */
+    distanceFallOff?: number;
+    /** AO 次幂（gamma 校正），默认 1.0 */
+    scale?: number;
+}
+interface BloomConfig {
+    enable: boolean;
+    /** 辉光强度，默认 0.6 */
+    strength: number;
+    /** 辉光半径，默认 0.4 */
+    radius: number;
+    /** 亮度阈值（高于该值的像素才参与辉光），默认 0.85 */
+    threshold: number;
+}
+export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
+    constructor();
+    minDevicePixelRatio: number;
+    maxPixelRatio: number;
+    renderScale: number;
+    private _resolution;
+    get resolution(): number;
+    set resolution(value: number);
+    /**
+     * 终处理抖动强度（消除 8bit 输出量化的色带，见 baseTextureToRenderShader）。
+     * 1.0 = 标准 ±0.5 LSB（默认，肉眼无感但能打散色带）；0 = 完全关闭。
+     * ⚠️ 若某处柔和渐变（外辉光/天空）看着"发脏/有颗粒"，先把它设 0 做 A/B 对比：
+     *    0 时若色带回来，说明抖动是必需的，应调小到 0.5 而不是关掉。
+     */
+    get ditherStrength(): number;
+    set ditherStrength(value: number);
+    /**
+     * 渲染目标(RT)底层配置（运行时可调，改即重建 base / screen 两个主颜色 RT）。
+     * 皇上要的「RT 上面的配置」= type / format / colorSpace / filter；
+     * 默认与原始硬编码一致（HalfFloatType + RGBAFormat + 线性 NoColorSpace + Linear 滤波）。
+     * 调这些能直观复现/消除典型问题：
+     *   - type=UnsignedByteType(8bit 线性)：柔和渐变被压成 3~6 色阶 → 同心环色带（banding）
+     *   - colorSpace=SRGBColorSpace：RT 已按 sRGB 编码 + 终处理再编一次 → 双重编码发白
+     *   - filter=NearestFilter：颜色插值变最近邻 → 边缘像素化/糊
+     */
+    private _rtOptions;
+    /** 面板/代码里的字符串名 → THREE 常量（单一映射点，避免散落硬编码数字） */
+    private static rtNameToConstant;
+    /**
+     * 运行时改 RT 底层配置：更新 _rtOptions 后重建 base / screen 两个主颜色 RT（保留当前尺寸）。
+     * 必须在已布局（size>0）后才重建；否则等下次 setSize 自然带新选项。
+     * 仅重建主颜色 RT（base/screen）；深度/法线/aoDepth 是辅助通道，其 type 由对应 depthTexture 决定，
+     * 不在面板暴露，避免破坏深度比对 / SSAO 深度黑。
+     */
+    applyRenderTargetOption(key: "type" | "colorSpace" | "format" | "filter", name: string): void;
+    private rebuildRenderTargets;
+    effectMaxPixelRatio: number;
+    get effectiveRatio(): number;
+    baseDepthTexture: DepthTexture;
+    baseRenderTarget: WebGLRenderTarget<Texture>;
+    /** 可选的屏幕空间水流对象（WaterFlow）。默认 null；调用 enableWaterFlow() 后创建。启用时
+     * 每帧消费 baseRenderTarget/baseDepthTexture，把水面合成进后处理链（不额外渲染主场景）。 */
+    waterFlow: WaterFlow | null;
+    private _waterFlowLastTime;
+    waterFlowElapsed: number;
+    excludedMaskRenderTarget: WebGLRenderTarget<Texture>;
+    depthRenderTarget: WebGLRenderTarget<Texture>;
+    aoDepthTexture: DepthTexture;
+    /**
+     * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
+     *   - "none"    ：正常渲染（默认）
+     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
+     *   - "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: DebugDepthMode;
+    /**
+     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
+     *
+     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
+     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
+     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
+     */
+    get baseDepthIncludeFloor(): boolean;
+    set baseDepthIncludeFloor(v: boolean);
+    normalRenderTarget: WebGLRenderTarget<Texture>;
+    screenRenderTarget: WebGLRenderTarget<Texture>;
+    screenCopyShader: import("three").ShaderMaterial;
+    normalMaterial: MeshNormalMaterial;
+    renderTarget: WebGLRenderTarget<Texture>;
+    renderTarget2: WebGLRenderTarget<Texture>;
+    tempVector2: Vector2;
+    tempVector3: Vector3;
+    size: Vector2;
+    rendererLost: boolean;
+    renderer: WebGLRenderer;
+    perspectiveCamera: PerspectiveCamera;
+    orthographicCamera: OrthographicCamera;
+    cameraType: CameraType;
+    setCameraType(cameraType: CameraType): void;
+    getCamera(): PerspectiveCamera | OrthographicCamera;
+    scene: Scene;
+    add(...object: Object3D[]): this;
+    threeMouse: ThreeMouse;
+    controls: OrbitControls;
+    private _lastControlsTime;
+    instancedGroup: InstancedGroup;
+    /**
+     * 自定义描边目标：不在 scene 内的独立对象（如 InstancedChild 的"选择代理"），
+     * 渲染循环在效果阶段单独对其调用 stroke_pass，使其获得与普通 Mesh 一致的描边，
+     * 且不会被正常 base pass 重复绘制（因为它不在 scene 树内）。
+     * 典型用途：InstancedChild / 一组 InstancedChild 没有自身几何，无法直接描边，
+     * 用 buildSelectProxy 重建其几何代理后再注册到这里即可。
+     */
+    private _strokeObjects;
+    /** 注册一个自定义描边对象（效果阶段对其描边） */
+    addStrokeObject(object: Object3D): this;
+    /** 移除自定义描边对象 */
+    removeStrokeObject(object: Object3D): this;
+    setContainer(div: HTMLDivElement | null): Promise<void>;
+    setSize(width: number, height: number): void;
+    /**
+     * 按「容器尺寸 × effectiveRatio × resolution」重建所有渲染目标尺寸。
+     * 由 setSize()（容器尺寸变化）与 resolution setter（运行时调倍率）共用 ——
+     * 关键：resolution 是运行时可调的性能/质量旋钮，改完必须立刻重建 RT，
+     * 否则倍率变了而 RT 尺寸没变，画面毫无变化（历史坑："调分辨率没感觉"）。
+     */
+    private updateRenderTargetSizes;
+    controlsDistanceTransition: Transition<{
+        distance: number;
+    }, "distance">;
+    controlsYTransition: Transition<{
+        y: number;
+    }, "y">;
+    controlsXZTransition: Transition<{
+        x: number;
+        z: number;
+    }, "x" | "z">;
+    controlsCenter: Transition<{
+        x: number;
+        y: number;
+        z: number;
+    }, "x" | "y" | "z">;
+    controlsPosition: Transition<{
+        x: number;
+        y: number;
+        z: number;
+    }, "x" | "y" | "z">;
+    gridHelper: GridHelper;
+    axesHelper: AxesHelper;
+    init(): void;
+    /**
+     * 启用屏幕空间水流（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?: {
+        size?: number;
+        speed?: number;
+        aperture?: number;
+        nozzle?: [number, number, number];
+        jetDirection?: [number, number, number];
+        collision?: boolean;
+    }): void;
+    /** 运行时改喷流起点（喷嘴）坐标（WaterFlow 已启用时有效） */
+    setWaterFlowNozzle(x: number, y: number, z: number): void;
+    /** 运行时改喷流方向（轴向，会被归一化） */
+    setWaterFlowJetDirection(x: number, y: number, z: number): void;
+    /** 运行时开关粒子与 basin/地面碰撞回弹 */
+    setWaterFlowCollision(enabled: boolean): void;
+    /**
+     * 关闭屏幕空间水流并释放其 GPU 资源（enableWaterFlow 的反操作）。
+     * 切走页面时必须调用，否则其它页面 render 仍会合成水面（this.waterFlow 非空）。
+     */
+    disableWaterFlow(): void;
+    resetLookAt({ position, center, }: {
+        position: Vector3;
+        center: Vector3;
+    }): void;
+    setLookAt({ position, center, duration, }: {
+        position: Vector3;
+        center: Vector3;
+        duration?: number;
+    }): Promise<void>;
+    getLookAt(): {
+        center: Vector3;
+        position: Vector3;
+        centerPosition: string;
+    };
+    lookatObjects({ objects, duration, direction, offset, distance, }: {
+        objects: Array<Object3D>;
+        duration?: number;
+        direction?: Vector3;
+        offset?: Vector3;
+        distance?: number;
+    }): void;
+    v3tov2(v3: Vector3): Vector2;
+    controlType: ControlType;
+    originScreenSpacePanning: boolean;
+    setControlType(controlType: ControlType): void;
+    autoRender: boolean;
+    needRender: boolean;
+    ssao: SSAOConfig;
+    bloom: BloomConfig;
+    stopRender(): void;
+    dispose(): void;
+    /** 释放单个材质及其引用的纹理（遍历材质属性找 Texture 并 dispose） */
+    private _disposeMaterial;
+    render(): void;
+    private renderBindThis;
+    getThumbBlob(): Promise<Blob>;
+    getThumbBase64(): string;
+    getThumbFile(): Promise<File>;
+    download(fileName?: string): Promise<void>;
+    renderRendererTarget(renderTarget: WebGLRenderTarget): void;
+    renderTexture(texture: Texture, alpha?: boolean): void;
+}
+export {};