three-base 2.0.142 → 2.0.145

package/WaterFlow/WaterFlow.ts

@@ -1,219 +1,219 @@
-import * as THREE from 'three';
-import { GPUFluidSimulation } from './GPUFluidSimulation';
-import { ScreenSpaceFluidPass } from './ScreenSpaceFluidPass';
-import type {
-  BasinConfig,
-  FluidParameters,
-  FluidQuality,
-  ReservoirState,
-  WaterFlowBaseTextures,
-  WaterFlowOptions,
-  WaterFlowRenderOptions,
-} from './types';
-
-/**
- * WaterFlow —— 可独立使用的水流对象封装。
- *
- * 把「GPGPU 粒子流体模拟」与「屏幕空间流体后处理」打包成一个对象：
- * 对外只暴露 update / 参数 setter / createPass，调用方无需关心 GPU ping-pong、
- * SPH 场、深度重建等内部细节。
- *
- * 两种渲染模式：
- *  A. 自渲染模式（默认）：createPass(scene, camera) 不传 base 纹理。pass 内部
- *     自己把主场景渲到带深度的缓冲，再与粒子深度合成。需要作为后处理链一环。
- *  B. 注入基础纹理模式：createPass(scene, camera, baseTextures)，其中
- *     baseTextures = { colorTexture, depthTexture, depthMode }。pass 直接消费
- *     调用方已有的基础颜色/深度纹理，不再自渲染主场景 —— 与 three-base「共用
- *     base 纹理 / base 深度图」的后处理方案完全契合，省掉一遍主场景渲染。
- *     depthMode: 'standard'（默认，普通透视深度）| 'logarithmic'
- *     （three-base 开 logarithmicDepthBuffer 时，与 frosted_glass_pass 解码对齐）。
- *
- * 集成到 three-base（手写 fsQuad 后处理）：
- *   const water = new WaterFlow(renderer, { size: 200 });
- *   const pass = water.createPass(scene, camera, {
- *     colorTexture: this.baseRenderTarget.texture,
- *     depthTexture: this.baseDepthTexture,
- *     depthMode: 'logarithmic',
- *   });
- *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
- *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
- *   //       然后 water.update(dt, elapsed);
- *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
- *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。
- */
-export class WaterFlow {
-  private readonly renderer: THREE.WebGLRenderer;
-  private width: number;
-  private height: number;
-  private readonly scale: number;
-  private readonly simulation: GPUFluidSimulation;
-  /** createPass 之前为 null；各渲染参数 setter 走 `this.pass?.xxx` 可选链。 */
-  private pass: ScreenSpaceFluidPass | null;
-
-  constructor(renderer: THREE.WebGLRenderer, options: WaterFlowOptions = {}) {
-    const {
-      width = 1,
-      height = 1,
-      scale = 0.75,
-      size = 200,
-      speed = 2.4,
-      aperture = 0.78,
-      nozzle,
-      basin,
-      jetDirection,
-      collision,
-    } = options;
-
-    this.renderer = renderer;
-    this.width = width;
-    this.height = height;
-    this.scale = scale;
-
-    this.simulation = new GPUFluidSimulation(renderer, {
-      size,
-      speed,
-      aperture,
-      nozzle,
-      basin,
-      jetDirection,
-      collision,
-    });
-    this.pass = null;
-  }
-
-  get supported(): boolean {
-    return this.simulation.supported;
-  }
-
-  get count(): number {
-    return this.simulation.count;
-  }
-
-  get positionTexture(): THREE.Texture | null {
-    return this.simulation.positionTexture;
-  }
-
-  get velocityTexture(): THREE.Texture | null {
-    return this.simulation.velocityTexture;
-  }
-
-  /**
-   * 生成屏幕空间流体 pass 并接入渲染链。
-   * @param scene 主场景（注入 base 纹理模式下不会被 pass 自渲染）
-   * @param camera 主相机（粒子投影 / spray 渲染需要）
-   * @param baseTextures 传入即启用「注入基础纹理」模式：pass 直接消费调用方颜色+深度，不再自渲染主场景。
-   * @returns 不支持浮点纹理时返回 null
-   *
-   * ⚠️ ScreenSpaceFluidPass 按**透视相机**建模（setSize 无条件读 `camera.fov` 算 pointScale、
-   *    depthMaterial 走 projectionMatrix 重建深度），故此处收 PerspectiveCamera。
-   *    ThreeBase.getCamera() 的返回类型是 `PerspectiveCamera | OrthographicCamera`，
-   *    调用处已显式窄化（见 ThreeBase 内 waterFlow.createPass 那行）。
-   *    ⚠️ 若真用正交相机，fov 为 undefined → pointScale 变 NaN（**原 JS 既有行为，本次未改运行时**）。
-   */
-  createPass(
-    scene: THREE.Scene,
-    camera: THREE.PerspectiveCamera,
-    baseTextures: WaterFlowBaseTextures | null = null,
-  ): ScreenSpaceFluidPass | null {
-    if (!this.supported) return null;
-    this.pass = new ScreenSpaceFluidPass(scene, camera, this.simulation, {
-      width: this.width,
-      height: this.height,
-      scale: this.scale,
-      activeCount: this.simulation.count,
-      externalBase: baseTextures ? {
-        colorTexture: baseTextures.colorTexture,
-        depthTexture: baseTextures.depthTexture,
-        depthMode: baseTextures.depthMode || 'standard',
-      } : null,
-    });
-    this.pass.setQuality({
-      scale: this.scale,
-      activeCount: this.simulation.count,
-      blurRadius: 5,
-    });
-    return this.pass;
-  }
-
-  /** 推进一帧模拟。 */
-  update(delta: number, elapsed: number): void {
-    if (this.supported) this.simulation.update(delta, elapsed);
-  }
-
-  // ---- 模拟参数代理 ----
-  setParameters(p: FluidParameters): void {
-    this.simulation.setParameters(p);
-  }
-
-  setReservoirState(state: ReservoirState): void {
-    this.simulation.setReservoirState(state);
-  }
-
-  setContainerMotion(accelerationX = 0, accelerationZ = 0): void {
-    this.simulation.setContainerMotion(accelerationX, accelerationZ);
-  }
-
-  setBasin(basin: BasinConfig): void {
-    this.simulation.setBasin(basin);
-  }
-
-  /** 运行时改喷流起点（喷嘴）坐标 */
-  setNozzle(x: number, y: number, z: number): void {
-    this.simulation.setNozzle(x, y, z);
-  }
-
-  /** 运行时改喷流方向（轴向，会被归一化） */
-  setJetDirection(dx: number, dy: number, dz: number): void {
-    this.simulation.setJetDirection(dx, dy, dz);
-  }
-
-  /** 运行时开关粒子与 basin/地面碰撞回弹 */
-  setCollision(enabled: boolean): void {
-    this.simulation.setCollision(enabled);
-  }
-
-  reset(): void {
-    this.simulation.reset();
-  }
-
-  // ---- 渲染参数代理（需 pass 已创建）----
-  setAirFraction(value: number): void {
-    this.pass?.setAirFraction(value);
-  }
-
-  setParticleRadius(value: number): void {
-    this.pass?.setParticleRadius(value);
-  }
-
-  setRetainedFluidVisible(value: boolean): void {
-    this.pass?.setRetainedFluidVisible(value);
-  }
-
-  setQuality(quality: FluidQuality): void {
-    this.pass?.setQuality(quality);
-  }
-
-  /** 运行时刷新注入的基础纹理（three-base resize / 切换 baseRT 时调用）。 */
-  setBaseTextures(baseTextures: WaterFlowBaseTextures): void {
-    this.pass?.setBaseTextures(baseTextures);
-  }
-
-  resize(width: number, height: number): void {
-    this.width = width;
-    this.height = height;
-    this.pass?.setSize(width, height);
-  }
-
-  /**
-   * 函数式渲染入口（three-base 手写 fsQuad 后处理链）：直接消费基础颜色/深度纹理，
-   * 把水面合成回当前渲染目标（与 frosted_glass_pass 同构，省去自渲染主场景）。
-   */
-  renderInto(renderer: THREE.WebGLRenderer, opts: WaterFlowRenderOptions): void {
-    if (this.supported && this.pass) this.pass.renderInto(renderer, opts);
-  }
-
-  dispose() {
-    this.pass?.dispose();
-    this.simulation.dispose();
-  }
-}
+import * as THREE from 'three';
+import { GPUFluidSimulation } from './GPUFluidSimulation';
+import { ScreenSpaceFluidPass } from './ScreenSpaceFluidPass';
+import type {
+  BasinConfig,
+  FluidParameters,
+  FluidQuality,
+  ReservoirState,
+  WaterFlowBaseTextures,
+  WaterFlowOptions,
+  WaterFlowRenderOptions,
+} from './types';
+
+/**
+ * WaterFlow —— 可独立使用的水流对象封装。
+ *
+ * 把「GPGPU 粒子流体模拟」与「屏幕空间流体后处理」打包成一个对象：
+ * 对外只暴露 update / 参数 setter / createPass，调用方无需关心 GPU ping-pong、
+ * SPH 场、深度重建等内部细节。
+ *
+ * 两种渲染模式：
+ *  A. 自渲染模式（默认）：createPass(scene, camera) 不传 base 纹理。pass 内部
+ *     自己把主场景渲到带深度的缓冲，再与粒子深度合成。需要作为后处理链一环。
+ *  B. 注入基础纹理模式：createPass(scene, camera, baseTextures)，其中
+ *     baseTextures = { colorTexture, depthTexture, depthMode }。pass 直接消费
+ *     调用方已有的基础颜色/深度纹理，不再自渲染主场景 —— 与 three-base「共用
+ *     base 纹理 / base 深度图」的后处理方案完全契合，省掉一遍主场景渲染。
+ *     depthMode: 'standard'（默认，普通透视深度）| 'logarithmic'
+ *     （three-base 开 logarithmicDepthBuffer 时，与 frosted_glass_pass 解码对齐）。
+ *
+ * 集成到 three-base（手写 fsQuad 后处理）：
+ *   const water = new WaterFlow(renderer, { size: 200 });
+ *   const pass = water.createPass(scene, camera, {
+ *     colorTexture: this.baseRenderTarget.texture,
+ *     depthTexture: this.baseDepthTexture,
+ *     depthMode: 'logarithmic',
+ *   });
+ *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
+ *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
+ *   //       然后 water.update(dt, elapsed);
+ *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
+ *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。
+ */
+export class WaterFlow {
+  private readonly renderer: THREE.WebGLRenderer;
+  private width: number;
+  private height: number;
+  private readonly scale: number;
+  private readonly simulation: GPUFluidSimulation;
+  /** createPass 之前为 null；各渲染参数 setter 走 `this.pass?.xxx` 可选链。 */
+  private pass: ScreenSpaceFluidPass | null;
+
+  constructor(renderer: THREE.WebGLRenderer, options: WaterFlowOptions = {}) {
+    const {
+      width = 1,
+      height = 1,
+      scale = 0.75,
+      size = 200,
+      speed = 2.4,
+      aperture = 0.78,
+      nozzle,
+      basin,
+      jetDirection,
+      collision,
+    } = options;
+
+    this.renderer = renderer;
+    this.width = width;
+    this.height = height;
+    this.scale = scale;
+
+    this.simulation = new GPUFluidSimulation(renderer, {
+      size,
+      speed,
+      aperture,
+      nozzle,
+      basin,
+      jetDirection,
+      collision,
+    });
+    this.pass = null;
+  }
+
+  get supported(): boolean {
+    return this.simulation.supported;
+  }
+
+  get count(): number {
+    return this.simulation.count;
+  }
+
+  get positionTexture(): THREE.Texture | null {
+    return this.simulation.positionTexture;
+  }
+
+  get velocityTexture(): THREE.Texture | null {
+    return this.simulation.velocityTexture;
+  }
+
+  /**
+   * 生成屏幕空间流体 pass 并接入渲染链。
+   * @param scene 主场景（注入 base 纹理模式下不会被 pass 自渲染）
+   * @param camera 主相机（粒子投影 / spray 渲染需要）
+   * @param baseTextures 传入即启用「注入基础纹理」模式：pass 直接消费调用方颜色+深度，不再自渲染主场景。
+   * @returns 不支持浮点纹理时返回 null
+   *
+   * ⚠️ ScreenSpaceFluidPass 按**透视相机**建模（setSize 无条件读 `camera.fov` 算 pointScale、
+   *    depthMaterial 走 projectionMatrix 重建深度），故此处收 PerspectiveCamera。
+   *    ThreeBase.getCamera() 的返回类型是 `PerspectiveCamera | OrthographicCamera`，
+   *    调用处已显式窄化（见 ThreeBase 内 waterFlow.createPass 那行）。
+   *    ⚠️ 若真用正交相机，fov 为 undefined → pointScale 变 NaN（**原 JS 既有行为，本次未改运行时**）。
+   */
+  createPass(
+    scene: THREE.Scene,
+    camera: THREE.PerspectiveCamera,
+    baseTextures: WaterFlowBaseTextures | null = null,
+  ): ScreenSpaceFluidPass | null {
+    if (!this.supported) return null;
+    this.pass = new ScreenSpaceFluidPass(scene, camera, this.simulation, {
+      width: this.width,
+      height: this.height,
+      scale: this.scale,
+      activeCount: this.simulation.count,
+      externalBase: baseTextures ? {
+        colorTexture: baseTextures.colorTexture,
+        depthTexture: baseTextures.depthTexture,
+        depthMode: baseTextures.depthMode || 'standard',
+      } : null,
+    });
+    this.pass.setQuality({
+      scale: this.scale,
+      activeCount: this.simulation.count,
+      blurRadius: 5,
+    });
+    return this.pass;
+  }
+
+  /** 推进一帧模拟。 */
+  update(delta: number, elapsed: number): void {
+    if (this.supported) this.simulation.update(delta, elapsed);
+  }
+
+  // ---- 模拟参数代理 ----
+  setParameters(p: FluidParameters): void {
+    this.simulation.setParameters(p);
+  }
+
+  setReservoirState(state: ReservoirState): void {
+    this.simulation.setReservoirState(state);
+  }
+
+  setContainerMotion(accelerationX = 0, accelerationZ = 0): void {
+    this.simulation.setContainerMotion(accelerationX, accelerationZ);
+  }
+
+  setBasin(basin: BasinConfig): void {
+    this.simulation.setBasin(basin);
+  }
+
+  /** 运行时改喷流起点（喷嘴）坐标 */
+  setNozzle(x: number, y: number, z: number): void {
+    this.simulation.setNozzle(x, y, z);
+  }
+
+  /** 运行时改喷流方向（轴向，会被归一化） */
+  setJetDirection(dx: number, dy: number, dz: number): void {
+    this.simulation.setJetDirection(dx, dy, dz);
+  }
+
+  /** 运行时开关粒子与 basin/地面碰撞回弹 */
+  setCollision(enabled: boolean): void {
+    this.simulation.setCollision(enabled);
+  }
+
+  reset(): void {
+    this.simulation.reset();
+  }
+
+  // ---- 渲染参数代理（需 pass 已创建）----
+  setAirFraction(value: number): void {
+    this.pass?.setAirFraction(value);
+  }
+
+  setParticleRadius(value: number): void {
+    this.pass?.setParticleRadius(value);
+  }
+
+  setRetainedFluidVisible(value: boolean): void {
+    this.pass?.setRetainedFluidVisible(value);
+  }
+
+  setQuality(quality: FluidQuality): void {
+    this.pass?.setQuality(quality);
+  }
+
+  /** 运行时刷新注入的基础纹理（three-base resize / 切换 baseRT 时调用）。 */
+  setBaseTextures(baseTextures: WaterFlowBaseTextures): void {
+    this.pass?.setBaseTextures(baseTextures);
+  }
+
+  resize(width: number, height: number): void {
+    this.width = width;
+    this.height = height;
+    this.pass?.setSize(width, height);
+  }
+
+  /**
+   * 函数式渲染入口（three-base 手写 fsQuad 后处理链）：直接消费基础颜色/深度纹理，
+   * 把水面合成回当前渲染目标（与 frosted_glass_pass 同构，省去自渲染主场景）。
+   */
+  renderInto(renderer: THREE.WebGLRenderer, opts: WaterFlowRenderOptions): void {
+    if (this.supported && this.pass) this.pass.renderInto(renderer, opts);
+  }
+
+  dispose() {
+    this.pass?.dispose();
+    this.simulation.dispose();
+  }
+}