three-base 2.0.137 → 2.0.142

package/WaterFlow/ScreenSpaceFluidPass.ts

@@ -0,0 +1,789 @@
+import * as THREE from 'three';
+import { Pass, FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
+import type {
+    ExternalBaseTextures,
+    FluidQuality,
+    PartialBaseTextures,
+    ScreenSpaceFluidPassOptions,
+    ScreenSpaceFluidSource,
+    WaterFlowRenderOptions,
+} from './types';
+
+const fullscreenVertex = /* glsl */`
+  out vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = vec4(position, 1.0);
+  }
+`;
+
+function createColorDepthTarget(width: number, height: number): THREE.WebGLRenderTarget {
+  const target = new THREE.WebGLRenderTarget(width, height, {
+    type: THREE.HalfFloatType,
+    format: THREE.RGBAFormat,
+    minFilter: THREE.LinearFilter,
+    magFilter: THREE.LinearFilter,
+    depthBuffer: true,
+  });
+  target.depthTexture = new THREE.DepthTexture(width, height, THREE.UnsignedIntType);
+  target.depthTexture.minFilter = THREE.NearestFilter;
+  target.depthTexture.magFilter = THREE.NearestFilter;
+  return target;
+}
+
+function createFluidTarget(width: number, height: number, depthBuffer = false): THREE.WebGLRenderTarget {
+  return new THREE.WebGLRenderTarget(width, height, {
+    type: THREE.HalfFloatType,
+    format: THREE.RGBAFormat,
+    minFilter: THREE.LinearFilter,
+    magFilter: THREE.LinearFilter,
+    wrapS: THREE.ClampToEdgeWrapping,
+    wrapT: THREE.ClampToEdgeWrapping,
+    depthBuffer,
+    stencilBuffer: false,
+  });
+}
+
+function createLookupGeometry(size: number): THREE.BufferGeometry {
+  const count = size * size;
+  const positions = new Float32Array(count * 3);
+  const lookup = new Float32Array(count * 2);
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const i = y * size + x;
+      lookup[i * 2] = (x + 0.5) / size;
+      lookup[i * 2 + 1] = (y + 0.5) / size;
+    }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+  geometry.setAttribute('aLookup', new THREE.BufferAttribute(lookup, 2));
+  return geometry;
+}
+
+const particleVertex = /* glsl */`
+  precision highp float;
+  uniform sampler2D uPosition;
+  uniform sampler2D uVelocity;
+  uniform float uParticleRadius;
+  uniform float uRetainedRadiusScale;
+  uniform float uShowRetained;
+  uniform float uPointScale;
+  in vec2 aLookup;
+  out vec3 vViewCenter;
+  out float vRadius;
+  out float vImpact;
+  out float vRetained;
+  out float vAlive;
+
+  void main() {
+    vec4 particle = texture(uPosition, aLookup);
+    vec4 velocity = texture(uVelocity, aLookup);
+    float retained = 1.0 - step(-0.5, velocity.w);
+    vRetained = retained;
+    vAlive = step(0.0, particle.w) * mix(1.0, uShowRetained, retained);
+    vImpact = velocity.w;
+    float jetRadius = mix(uParticleRadius, uParticleRadius * 0.56, smoothstep(0.05, 0.7, velocity.w));
+    vRadius = mix(jetRadius, uParticleRadius * uRetainedRadiusScale, retained);
+    vec4 mv = viewMatrix * vec4(particle.xyz, 1.0);
+    vViewCenter = mv.xyz;
+    gl_Position = projectionMatrix * mv;
+    gl_PointSize = vAlive * max(0.0, vRadius * uPointScale / max(0.2, -mv.z));
+    if (vAlive < 0.5) gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+  }
+`;
+
+export class ScreenSpaceFluidPass extends Pass {
+  /**
+   * 字段集中声明。
+   *
+   * 构造器在 `if (!this.supported) return;` 处提前返回，因此下面标注 `T | null` 的这批资源字段
+   * 在「不支持 WebGL2 / 浮点纹理」的空壳实例上**根本没被赋值**（运行时是 undefined，不是 null）。
+   * 一律建模为 `T | null` 而不是用 `!` 硬压，且所有读取点都在 `if (!this.supported) return;`
+   * 守卫之后（setSize/dispose 里原有的 `?.` 也照留），语义与原实现逐字节一致。
+   */
+  private readonly scene: THREE.Scene;
+  /** setSize 要读 camera.fov 算 pointScale，故按透视相机建模。 */
+  private readonly camera: THREE.PerspectiveCamera;
+  private readonly simulation: ScreenSpaceFluidSource;
+  private readonly supported: boolean;
+  private scale: number;
+  private airFraction: number;
+  private activeCount: number;
+  /** 外部注入的基础纹理；只在 renderInto 里被赋值，此前为 undefined，setBaseTextures 的 falsy 守卫会直接返回。 */
+  private externalBase: ExternalBaseTextures | null;
+  /** 由 setSize 写入（构造器 supported 分支末尾调用过），空壳实例上为 undefined。 */
+  private width: number | null;
+  private height: number | null;
+  private readonly sceneTarget: THREE.WebGLRenderTarget | null;
+  private readonly depthTarget: THREE.WebGLRenderTarget | null;
+  private readonly thicknessTarget: THREE.WebGLRenderTarget | null;
+  private readonly blurA: THREE.WebGLRenderTarget | null;
+  private readonly blurB: THREE.WebGLRenderTarget | null;
+  private readonly thicknessBlurA: THREE.WebGLRenderTarget | null;
+  private readonly thicknessBlurB: THREE.WebGLRenderTarget | null;
+  private readonly compositeTarget: THREE.WebGLRenderTarget | null;
+  private readonly lookupGeometry: THREE.BufferGeometry | null;
+  private readonly depthMaterial: THREE.ShaderMaterial | null;
+  private readonly thicknessMaterial: THREE.ShaderMaterial | null;
+  private readonly sprayMaterial: THREE.ShaderMaterial | null;
+  private readonly depthBlurMaterial: THREE.ShaderMaterial | null;
+  private readonly thicknessBlurMaterial: THREE.ShaderMaterial | null;
+  private readonly compositeMaterial: THREE.ShaderMaterial | null;
+  private readonly copyMaterial: THREE.ShaderMaterial | null;
+  private readonly particleScene: THREE.Scene | null;
+  private readonly sprayScene: THREE.Scene | null;
+  private readonly depthPoints: THREE.Points<THREE.BufferGeometry, THREE.ShaderMaterial> | null;
+  private readonly sprayPoints: THREE.Points<THREE.BufferGeometry, THREE.ShaderMaterial> | null;
+  private readonly fsQuad: FullScreenQuad | null;
+
+  constructor(
+    scene: THREE.Scene,
+    camera: THREE.PerspectiveCamera,
+    simulation: ScreenSpaceFluidSource,
+    { width = 1, height = 1, scale = 0.75, activeCount = simulation.count }: ScreenSpaceFluidPassOptions = {},
+  ) {
+    super();
+    this.scene = scene;
+    this.camera = camera;
+    this.simulation = simulation;
+    this.scale = scale;
+    this.airFraction = 0.18;
+    this.activeCount = Math.min(activeCount, simulation.count);
+    this.supported = simulation.supported;
+    this.needsSwap = true;
+
+    if (!this.supported) return;
+
+    this.sceneTarget = createColorDepthTarget(width, height);
+    this.depthTarget = createFluidTarget(Math.ceil(width * scale), Math.ceil(height * scale), true);
+    this.thicknessTarget = createFluidTarget(Math.ceil(width * scale), Math.ceil(height * scale));
+    this.blurA = createFluidTarget(Math.ceil(width * scale), Math.ceil(height * scale));
+    this.blurB = createFluidTarget(Math.ceil(width * scale), Math.ceil(height * scale));
+    this.thicknessBlurA = createFluidTarget(Math.ceil(width * scale), Math.ceil(height * scale));
+    this.thicknessBlurB = createFluidTarget(Math.ceil(width * scale), Math.ceil(height * scale));
+
+    this.lookupGeometry = createLookupGeometry(simulation.size);
+    this.lookupGeometry.setDrawRange(0, this.activeCount);
+
+    this.depthMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: {
+        uPosition: { value: simulation.positionTexture },
+        uVelocity: { value: simulation.velocityTexture },
+        uParticleRadius: { value: 0.037 },
+        uRetainedRadiusScale: { value: 1.55 },
+        uShowRetained: { value: 0 },
+        uPointScale: { value: 1 },
+        uProjectionMatrix: { value: camera.projectionMatrix.clone() },
+      },
+      vertexShader: particleVertex,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        uniform mat4 uProjectionMatrix;
+        in vec3 vViewCenter;
+        in float vRadius;
+        in float vImpact;
+        in float vRetained;
+        in float vAlive;
+        out vec4 outColor;
+        void main() {
+          vec2 circle = gl_PointCoord * 2.0 - 1.0;
+          float radiusSq = dot(circle, circle);
+          if (radiusSq > 1.0 || vAlive < 0.5) discard;
+          float sphereZ = sqrt(max(0.0, 1.0 - radiusSq));
+          vec3 surfacePosition = vViewCenter + vec3(circle * vRadius, sphereZ * vRadius);
+          vec4 clip = uProjectionMatrix * vec4(surfacePosition, 1.0);
+          float ndcDepth = clip.z / clip.w;
+          gl_FragDepth = ndcDepth * 0.5 + 0.5;
+          outColor = vec4(-surfacePosition.z, max(vImpact, 0.0), vRetained, 1.0);
+        }
+      `,
+      depthTest: true,
+      depthWrite: true,
+      blending: THREE.NoBlending,
+      toneMapped: false,
+    });
+
+    this.thicknessMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: {
+        uPosition: { value: simulation.positionTexture },
+        uVelocity: { value: simulation.velocityTexture },
+        uParticleRadius: { value: 0.037 },
+        uRetainedRadiusScale: { value: 1.55 },
+        uShowRetained: { value: 0 },
+        uPointScale: { value: 1 },
+      },
+      vertexShader: particleVertex,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        in vec3 vViewCenter;
+        in float vRadius;
+        in float vImpact;
+        in float vRetained;
+        in float vAlive;
+        out vec4 outColor;
+        void main() {
+          vec2 circle = gl_PointCoord * 2.0 - 1.0;
+          float radiusSq = dot(circle, circle);
+          if (radiusSq > 1.0 || vAlive < 0.5) discard;
+          float chord = sqrt(max(0.0, 1.0 - radiusSq)) * vRadius * 2.0;
+          float softEdge = smoothstep(1.0, 0.72, radiusSq);
+          outColor = vec4(
+            chord * softEdge,
+            chord * max(vImpact, 0.0) * softEdge,
+            chord * vRetained * softEdge,
+            softEdge
+          );
+        }
+      `,
+      transparent: true,
+      depthTest: false,
+      depthWrite: false,
+      blending: THREE.AdditiveBlending,
+      toneMapped: false,
+    });
+
+    this.particleScene = new THREE.Scene();
+    this.depthPoints = new THREE.Points(this.lookupGeometry, this.depthMaterial);
+    this.depthPoints.frustumCulled = false;
+    this.particleScene.add(this.depthPoints);
+
+    this.sprayMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: {
+        uPosition: { value: simulation.positionTexture },
+        uVelocity: { value: simulation.velocityTexture },
+        uPixelRatio: { value: 1 },
+        uAirFraction: { value: this.airFraction },
+      },
+      vertexShader: /* glsl */`
+        precision highp float;
+        uniform sampler2D uPosition;
+        uniform sampler2D uVelocity;
+        uniform float uPixelRatio;
+        in vec2 aLookup;
+        out float vImpact;
+        void main() {
+          vec4 particle = texture(uPosition, aLookup);
+          vec4 velocity = texture(uVelocity, aLookup);
+          vImpact = velocity.w;
+          vec4 mv = viewMatrix * vec4(particle.xyz, 1.0);
+          gl_Position = projectionMatrix * mv;
+          gl_PointSize = min(6.5, (1.2 + velocity.w * 3.4) * uPixelRatio * (5.5 / max(2.0, -mv.z)));
+          if (particle.w < 0.0 || velocity.w < 0.045) gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+        }
+      `,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        uniform float uAirFraction;
+        in float vImpact;
+        out vec4 outColor;
+        void main() {
+          vec2 p = gl_PointCoord - 0.5;
+          float d = length(p);
+          if (d > 0.5) discard;
+          float glint = 1.0 - smoothstep(0.02, 0.15, distance(gl_PointCoord, vec2(0.34, 0.3)));
+          float edge = 1.0 - smoothstep(0.34, 0.5, d);
+          vec3 color = mix(vec3(0.18, 0.68, 0.78), vec3(0.86, 1.0, 1.0), glint);
+          outColor = vec4(color, edge * vImpact * (0.12 + uAirFraction * 0.34));
+        }
+      `,
+      transparent: true,
+      depthTest: false,
+      depthWrite: false,
+      blending: THREE.AdditiveBlending,
+      toneMapped: false,
+    });
+    this.sprayScene = new THREE.Scene();
+    this.sprayPoints = new THREE.Points(this.lookupGeometry, this.sprayMaterial);
+    this.sprayPoints.frustumCulled = false;
+    this.sprayScene.add(this.sprayPoints);
+
+    this.depthBlurMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: {
+        uInput: { value: this.depthTarget.texture },
+        uTexel: { value: new THREE.Vector2() },
+        uDirection: { value: new THREE.Vector2(1, 0) },
+        uRadius: { value: 5 },
+        uRetainedOnly: { value: 0 },
+      },
+      vertexShader: fullscreenVertex,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        uniform sampler2D uInput;
+        uniform vec2 uTexel;
+        uniform vec2 uDirection;
+        uniform int uRadius;
+        uniform float uRetainedOnly;
+        in vec2 vUv;
+        out vec4 outColor;
+
+        void main() {
+          vec4 centerSample = texture(uInput, vUv);
+          if (uRetainedOnly > 0.5 && centerSample.b < 0.35) {
+            outColor = centerSample;
+            return;
+          }
+          float center = centerSample.r;
+          if (center <= 0.0) {
+            float nearest = 1e6;
+            vec4 nearestSample = vec4(0.0);
+            for (int i = -5; i <= 5; i++) {
+              if (abs(i) > uRadius) continue;
+              vec4 candidate = texture(uInput, vUv + uDirection * uTexel * float(i));
+              if (candidate.r > 0.0 && candidate.r < nearest) {
+                nearest = candidate.r;
+                nearestSample = candidate;
+              }
+            }
+            if (nearest > 1e5) { outColor = vec4(0.0); return; }
+            center = nearest;
+            centerSample = nearestSample;
+          }
+
+          float total = 0.0;
+          float retainedTotal = 0.0;
+          float weightSum = 0.0;
+          float centerRetained = step(0.45, centerSample.b);
+          for (int i = -5; i <= 5; i++) {
+            if (abs(i) > uRadius) continue;
+            vec4 sampleValue = texture(uInput, vUv + uDirection * uTexel * float(i));
+            if (sampleValue.r <= 0.0) continue;
+            float retained = max(centerRetained, step(0.45, sampleValue.b));
+            float gaussian = exp(-float(i * i) * mix(0.11, 0.055, retained));
+            float bilateral = exp(-abs(sampleValue.r - center) * mix(18.0, 3.2, retained));
+            float weight = gaussian * bilateral;
+            total += sampleValue.r * weight;
+            retainedTotal += sampleValue.b * weight;
+            weightSum += weight;
+          }
+          outColor = vec4(
+            total / max(weightSum, 0.0001),
+            0.0,
+            retainedTotal / max(weightSum, 0.0001),
+            1.0
+          );
+        }
+      `,
+      depthTest: false,
+      depthWrite: false,
+      toneMapped: false,
+    });
+
+    this.thicknessBlurMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: {
+        uInput: { value: this.thicknessTarget.texture },
+        uTexel: { value: new THREE.Vector2() },
+        uDirection: { value: new THREE.Vector2(1, 0) },
+      },
+      vertexShader: fullscreenVertex,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        uniform sampler2D uInput;
+        uniform vec2 uTexel;
+        uniform vec2 uDirection;
+        in vec2 vUv;
+        out vec4 outColor;
+        void main() {
+          vec4 result = texture(uInput, vUv) * 0.227027;
+          result += texture(uInput, vUv + uDirection * uTexel * 1.384615) * 0.316216;
+          result += texture(uInput, vUv - uDirection * uTexel * 1.384615) * 0.316216;
+          result += texture(uInput, vUv + uDirection * uTexel * 3.230769) * 0.070270;
+          result += texture(uInput, vUv - uDirection * uTexel * 3.230769) * 0.070270;
+          outColor = result;
+        }
+      `,
+      depthTest: false,
+      depthWrite: false,
+      toneMapped: false,
+    });
+
+    this.compositeMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: {
+        uSceneColor: { value: this.externalBase ? this.externalBase.colorTexture : this.sceneTarget.texture },
+        uSceneDepth: { value: this.externalBase ? this.externalBase.depthTexture : this.sceneTarget.depthTexture },
+        uDepthMode: { value: this.externalBase && this.externalBase.depthMode === 'logarithmic' ? 1.0 : 0.0 },
+        uFluidDepth: { value: this.blurB.texture },
+        uThickness: { value: this.thicknessBlurB.texture },
+        uResolution: { value: new THREE.Vector2(width, height) },
+        uInverseProjection: { value: camera.projectionMatrixInverse },
+        uCameraNear: { value: camera.near },
+        uCameraFar: { value: camera.far },
+        uLightDirection: { value: new THREE.Vector3(-0.2, 0.7, 0.6).normalize() },
+        uAirFraction: { value: this.airFraction },
+      },
+      vertexShader: fullscreenVertex,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        uniform sampler2D uSceneColor;
+        uniform sampler2D uSceneDepth;
+        uniform sampler2D uFluidDepth;
+        uniform sampler2D uThickness;
+        uniform vec2 uResolution;
+        uniform mat4 uInverseProjection;
+        uniform float uCameraNear;
+        uniform float uCameraFar;
+        uniform vec3 uLightDirection;
+        uniform float uAirFraction;
+        in vec2 vUv;
+        out vec4 outColor;
+
+        uniform float uDepthMode;
+        float sceneDepthToViewDistance(float depth) {
+          if (uDepthMode > 0.5) {
+            // 对数深度（three-base logarithmicDepthBuffer）：与 frosted_glass_pass.ts:146 对齐
+            return pow(uCameraFar + 1.0, depth) - 1.0;
+          }
+          float viewZ = (uCameraNear * uCameraFar) / ((uCameraFar - uCameraNear) * depth - uCameraFar);
+          return -viewZ;
+        }
+
+        vec3 viewPosition(vec2 uv, float distanceToCamera) {
+          vec4 ray = uInverseProjection * vec4(uv * 2.0 - 1.0, 1.0, 1.0);
+          vec3 direction = ray.xyz / ray.w;
+          return direction * (-distanceToCamera / direction.z);
+        }
+
+        void main() {
+          vec3 sceneColor = texture(uSceneColor, vUv).rgb;
+          float depth = texture(uFluidDepth, vUv).r;
+          if (depth <= 0.0) { outColor = vec4(sceneColor, 1.0); return; }
+
+          float sceneDistance = sceneDepthToViewDistance(texture(uSceneDepth, vUv).r);
+          if (depth > sceneDistance + 0.018) { outColor = vec4(sceneColor, 1.0); return; }
+
+          vec4 thicknessData = texture(uThickness, vUv);
+          float retainedPreview = clamp(
+            thicknessData.b / max(thicknessData.r, 0.0001),
+            0.0,
+            1.0
+          );
+          vec2 texel = 1.0 / uResolution;
+          float normalSpan = mix(1.0, 2.35, retainedPreview);
+          float dL = texture(uFluidDepth, vUv - vec2(texel.x * normalSpan, 0.0)).r;
+          float dR = texture(uFluidDepth, vUv + vec2(texel.x * normalSpan, 0.0)).r;
+          float dD = texture(uFluidDepth, vUv - vec2(0.0, texel.y * normalSpan)).r;
+          float dU = texture(uFluidDepth, vUv + vec2(0.0, texel.y * normalSpan)).r;
+          dL = dL <= 0.0 ? depth : dL;
+          dR = dR <= 0.0 ? depth : dR;
+          dD = dD <= 0.0 ? depth : dD;
+          dU = dU <= 0.0 ? depth : dU;
+
+          vec3 pL = viewPosition(vUv - vec2(texel.x * normalSpan, 0.0), dL);
+          vec3 pR = viewPosition(vUv + vec2(texel.x * normalSpan, 0.0), dR);
+          vec3 pD = viewPosition(vUv - vec2(0.0, texel.y * normalSpan), dD);
+          vec3 pU = viewPosition(vUv + vec2(0.0, texel.y * normalSpan), dU);
+          vec3 normal = normalize(cross(pR - pL, pU - pD));
+          if (normal.z < 0.0) normal = -normal;
+
+          float thickness = max(0.0, thicknessData.r * 1.28);
+          float impactFoam = thicknessData.g / max(thicknessData.r, 0.0001);
+          float retainedPhase = clamp(thicknessData.b / max(thicknessData.r, 0.0001), 0.0, 1.0);
+          float curvature = abs(dL + dR + dD + dU - 4.0 * depth) / max(depth, 0.1);
+          float foam = smoothstep(0.22, 0.8, impactFoam) * (0.08 + uAirFraction * 0.5)
+                     + smoothstep(0.004, 0.02, curvature) * uAirFraction * 0.2
+                       * mix(1.0, 0.1, retainedPhase);
+          foam = clamp(foam, 0.0, 0.55);
+
+          vec2 refractOffset = normal.xy * (0.004 + min(thickness, 0.8) * 0.012) * vec2(1.0, -1.0);
+          vec2 refractUv = clamp(vUv + refractOffset, vec2(0.002), vec2(0.998));
+          vec3 refracted = texture(uSceneColor, refractUv).rgb;
+          vec3 absorption = vec3(0.09, 0.032, 0.017);
+          vec3 transmission = exp(-absorption * thickness * mix(3.8, 2.45, retainedPhase));
+          vec3 waterTint = vec3(0.01, 0.145, 0.18);
+          vec3 body = refracted * transmission + waterTint * (1.0 - transmission);
+
+          vec3 viewDir = normalize(-viewPosition(vUv, depth));
+          float fresnel = 0.0204 + 0.9796 * pow(1.0 - max(dot(normal, viewDir), 0.0), 5.0);
+          vec3 lightDir = normalize(uLightDirection);
+          vec3 halfDir = normalize(lightDir + viewDir);
+          float specular = pow(max(dot(normal, halfDir), 0.0), 132.0);
+          vec3 reflection = mix(vec3(0.03, 0.09, 0.11), vec3(0.34, 0.56, 0.62), max(normal.y * 0.5 + 0.5, fresnel));
+          vec3 waterColor = mix(body, reflection, fresnel * 0.5);
+          waterColor += vec3(0.84, 0.98, 1.0) * specular * 1.1;
+          waterColor = mix(waterColor, vec3(0.72, 0.94, 0.96), foam);
+
+          float coverage = smoothstep(0.002, 0.06, thickness);
+          float fluidOpacity = mix(0.76, 0.59, retainedPhase) + fresnel * 0.22;
+          vec3 result = mix(sceneColor, waterColor, coverage * fluidOpacity);
+          outColor = vec4(result, 1.0);
+        }
+      `,
+      depthTest: false,
+      depthWrite: false,
+      toneMapped: false,
+    });
+
+    this.copyMaterial = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      uniforms: { tDiffuse: { value: null } },
+      vertexShader: fullscreenVertex,
+      fragmentShader: /* glsl */`
+        precision highp float;
+        uniform sampler2D tDiffuse;
+        in vec2 vUv;
+        out vec4 outColor;
+        void main() { outColor = texture(tDiffuse, vUv); }
+      `,
+      depthTest: false,
+      depthWrite: false,
+      toneMapped: false,
+    });
+    // 函数式 renderInto 的中间合成目标：composite 先写到它，再拷回 outputTarget，
+    // 避免「读当前目标写当前目标」的反馈未定义行为（与 frosted_glass_pass 同构）。
+    // 与 outputTarget 同分辨率（全分辨率），保证合成回屏幕时不丢清晰度（水本身是软的，但背景不能糊）。
+    this.compositeTarget = createFluidTarget(width, height, false);
+
+    this.fsQuad = new FullScreenQuad(this.compositeMaterial);
+    this.setSize(width, height);
+  }
+
+  setAirFraction(value: number): void {
+    if (!this.supported) return;
+    this.airFraction = value;
+    this.compositeMaterial.uniforms.uAirFraction.value = value;
+    this.sprayMaterial.uniforms.uAirFraction.value = value;
+  }
+
+  setParticleRadius(value: number): void {
+    if (!this.supported) return;
+    this.depthMaterial.uniforms.uParticleRadius.value = value;
+    this.thicknessMaterial.uniforms.uParticleRadius.value = value;
+  }
+
+  setRetainedFluidVisible(visible: boolean): void {
+    if (!this.supported) return;
+    const value = visible ? 1 : 0;
+    this.depthMaterial.uniforms.uShowRetained.value = value;
+    this.thicknessMaterial.uniforms.uShowRetained.value = value;
+  }
+
+  setQuality({ scale, activeCount, blurRadius }: FluidQuality): void {
+    if (!this.supported) return;
+    this.scale = scale;
+    this.activeCount = Math.min(activeCount, this.simulation.count);
+    this.lookupGeometry.setDrawRange(0, this.activeCount);
+    const retainedRadiusScale = 1.58 * Math.cbrt(40000 / Math.max(this.activeCount, 1));
+    this.depthMaterial.uniforms.uRetainedRadiusScale.value = retainedRadiusScale;
+    this.thicknessMaterial.uniforms.uRetainedRadiusScale.value = retainedRadiusScale;
+    this.depthBlurMaterial.uniforms.uRadius.value = blurRadius;
+    this.setSize(this.width, this.height);
+  }
+
+  /** three-base 等外部调用方在 resize / 切换 baseRT 时刷新注入的基础纹理。 */
+  setBaseTextures({ colorTexture, depthTexture, depthMode }: PartialBaseTextures = {}): void {
+    if (!this.supported || !this.externalBase) return;
+    if (colorTexture) {
+      this.externalBase.colorTexture = colorTexture;
+      this.compositeMaterial.uniforms.uSceneColor.value = colorTexture;
+    }
+    if (depthTexture) {
+      this.externalBase.depthTexture = depthTexture;
+      this.compositeMaterial.uniforms.uSceneDepth.value = depthTexture;
+    }
+    if (depthMode) {
+      this.externalBase.depthMode = depthMode === 'logarithmic' ? 'logarithmic' : 'standard';
+      this.compositeMaterial.uniforms.uDepthMode.value = this.externalBase.depthMode === 'logarithmic' ? 1.0 : 0.0;
+    }
+  }
+
+  setSize(width: number, height: number): void {
+    if (!this.supported) return;
+    this.width = Math.max(1, Math.floor(width));
+    this.height = Math.max(1, Math.floor(height));
+    const fluidWidth = Math.max(1, Math.ceil(this.width * this.scale));
+    const fluidHeight = Math.max(1, Math.ceil(this.height * this.scale));
+    this.sceneTarget?.setSize(this.width, this.height);
+    this.depthTarget.setSize(fluidWidth, fluidHeight);
+    this.thicknessTarget.setSize(fluidWidth, fluidHeight);
+    this.blurA.setSize(fluidWidth, fluidHeight);
+    this.blurB.setSize(fluidWidth, fluidHeight);
+    this.thicknessBlurA.setSize(fluidWidth, fluidHeight);
+    this.thicknessBlurB.setSize(fluidWidth, fluidHeight);
+    this.compositeTarget.setSize(this.width, this.height);
+    this.depthBlurMaterial.uniforms.uTexel.value.set(1 / fluidWidth, 1 / fluidHeight);
+    this.thicknessBlurMaterial.uniforms.uTexel.value.set(1 / fluidWidth, 1 / fluidHeight);
+    this.compositeMaterial.uniforms.uResolution.value.set(fluidWidth, fluidHeight);
+    const pointScale = fluidHeight / Math.tan(THREE.MathUtils.degToRad(this.camera.fov * 0.5));
+    this.depthMaterial.uniforms.uPointScale.value = pointScale;
+    this.thicknessMaterial.uniforms.uPointScale.value = pointScale;
+    this.sprayMaterial.uniforms.uPixelRatio.value = Math.min(window.devicePixelRatio, 2);
+  }
+
+  /** 渲染粒子深度/厚度 + 两轮分离模糊 + 厚度模糊（不输出合成、不渲染 spray）。render/renderInto 共用。 */
+  renderFluidTextures(renderer: THREE.WebGLRenderer, camera?: THREE.Camera): void {
+    if (!this.supported) return;
+    const cam = camera || this.camera;
+    this.depthMaterial.uniforms.uPosition.value = this.simulation.positionTexture;
+    this.depthMaterial.uniforms.uVelocity.value = this.simulation.velocityTexture;
+    this.thicknessMaterial.uniforms.uPosition.value = this.simulation.positionTexture;
+    this.thicknessMaterial.uniforms.uVelocity.value = this.simulation.velocityTexture;
+    this.sprayMaterial.uniforms.uPosition.value = this.simulation.positionTexture;
+    this.sprayMaterial.uniforms.uVelocity.value = this.simulation.velocityTexture;
+    this.compositeMaterial.uniforms.uInverseProjection.value.copy(cam.projectionMatrixInverse);
+    this.depthMaterial.uniforms.uProjectionMatrix.value.copy(cam.projectionMatrix);
+
+    renderer.setClearColor(0x000000, 0);
+    this.depthPoints.material = this.depthMaterial;
+    renderer.setRenderTarget(this.depthTarget);
+    renderer.clear(true, true, false);
+    renderer.render(this.particleScene, cam);
+
+    this.depthPoints.material = this.thicknessMaterial;
+    renderer.setRenderTarget(this.thicknessTarget);
+    renderer.clear(true, false, false);
+    renderer.render(this.particleScene, cam);
+
+    this.fsQuad.material = this.depthBlurMaterial;
+    this.depthBlurMaterial.uniforms.uInput.value = this.depthTarget.texture;
+    this.depthBlurMaterial.uniforms.uRetainedOnly.value = 0;
+    this.depthBlurMaterial.uniforms.uDirection.value.set(1, 0);
+    renderer.setRenderTarget(this.blurA);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+    this.depthBlurMaterial.uniforms.uInput.value = this.blurA.texture;
+    this.depthBlurMaterial.uniforms.uDirection.value.set(0, 1);
+    renderer.setRenderTarget(this.blurB);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+
+    // A second phase-aware relaxation removes the individual SPH sphere imprint
+    // from stored water without softening the narrow free jet.
+    this.depthBlurMaterial.uniforms.uRetainedOnly.value = 1;
+    this.depthBlurMaterial.uniforms.uInput.value = this.blurB.texture;
+    this.depthBlurMaterial.uniforms.uDirection.value.set(1, 0);
+    renderer.setRenderTarget(this.blurA);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+    this.depthBlurMaterial.uniforms.uInput.value = this.blurA.texture;
+    this.depthBlurMaterial.uniforms.uDirection.value.set(0, 1);
+    renderer.setRenderTarget(this.blurB);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+    this.depthBlurMaterial.uniforms.uRetainedOnly.value = 0;
+
+    this.fsQuad.material = this.thicknessBlurMaterial;
+    this.thicknessBlurMaterial.uniforms.uInput.value = this.thicknessTarget.texture;
+    this.thicknessBlurMaterial.uniforms.uDirection.value.set(1, 0);
+    renderer.setRenderTarget(this.thicknessBlurA);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+    this.thicknessBlurMaterial.uniforms.uInput.value = this.thicknessBlurA.texture;
+    this.thicknessBlurMaterial.uniforms.uDirection.value.set(0, 1);
+    renderer.setRenderTarget(this.thicknessBlurB);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+  }
+
+  /** EffectComposer 链入口（自渲染模式 / base 纹理注入模式通用，保持原行为不变）。 */
+  render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget): void {
+    if (!this.supported) return;
+    const previousTarget = renderer.getRenderTarget();
+    const previousColor = renderer.getClearColor(new THREE.Color());
+    const previousAlpha = renderer.getClearAlpha();
+    const previousAutoClear = renderer.autoClear;
+
+    if (!this.externalBase) {
+      renderer.autoClear = true;
+      renderer.setClearColor(0x061017, 1);
+      renderer.setRenderTarget(this.sceneTarget);
+      renderer.clear(true, true, true);
+      renderer.render(this.scene, this.camera);
+    }
+
+    this.renderFluidTextures(renderer, this.camera);
+
+    this.fsQuad.material = this.compositeMaterial;
+    this.compositeMaterial.uniforms.uFluidDepth.value = this.blurB.texture;
+    this.compositeMaterial.uniforms.uThickness.value = this.thicknessBlurB.texture;
+    renderer.setRenderTarget(this.renderToScreen ? null : writeBuffer);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+
+    renderer.autoClear = false;
+    renderer.render(this.sprayScene, this.camera);
+    renderer.autoClear = previousAutoClear;
+    renderer.setRenderTarget(previousTarget);
+    renderer.setClearColor(previousColor, previousAlpha);
+  }
+
+  /**
+   * 函数式入口：直接消费调用方已有的基础颜色/深度纹理，把水面合成到指定目标。
+   * 与 three-base 的手写 fsQuad 后处理链（frosted_glass_pass 等）形态一致：
+   * 不创建/自渲染主场景，composite 先写到内部 compositeTarget，再拷回 outputTarget，
+   * 避免「读 baseRenderTarget 写 baseRenderTarget」的反馈未定义行为。
+   * @param {THREE.WebGLRenderer} renderer
+   * @param {{colorTexture:THREE.Texture,depthTexture:THREE.Texture,depthMode?:'standard'|'logarithmic',outputTarget:THREE.WebGLRenderTarget,camera:THREE.Camera}} opts
+   */
+  renderInto(renderer: THREE.WebGLRenderer, opts: WaterFlowRenderOptions): void {
+    if (!this.supported || !opts) return;
+    const {
+      colorTexture,
+      depthTexture,
+      depthMode = 'logarithmic',
+      outputTarget,
+      camera,
+    } = opts;
+
+    if (colorTexture) {
+      this.externalBase = { colorTexture, depthTexture, depthMode };
+      this.compositeMaterial.uniforms.uSceneColor.value = colorTexture;
+      this.compositeMaterial.uniforms.uSceneDepth.value = depthTexture;
+      this.compositeMaterial.uniforms.uDepthMode.value = depthMode === 'logarithmic' ? 1.0 : 0.0;
+    }
+
+    const previousTarget = renderer.getRenderTarget();
+    const previousColor = renderer.getClearColor(new THREE.Color());
+    const previousAlpha = renderer.getClearAlpha();
+    const previousAutoClear = renderer.autoClear;
+
+    this.renderFluidTextures(renderer, camera);
+
+    // composite → 独立 compositeTarget（读 base 写 compositeTarget，无 feedback）
+    this.fsQuad.material = this.compositeMaterial;
+    this.compositeMaterial.uniforms.uFluidDepth.value = this.blurB.texture;
+    this.compositeMaterial.uniforms.uThickness.value = this.thicknessBlurB.texture;
+    renderer.setRenderTarget(this.compositeTarget);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+
+    // 拷贝 compositeTarget → outputTarget（如 baseRenderTarget）
+    this.fsQuad.material = this.copyMaterial;
+    this.copyMaterial.uniforms.tDiffuse.value = this.compositeTarget.texture;
+    renderer.setRenderTarget(outputTarget);
+    renderer.clear();
+    this.fsQuad.render(renderer);
+
+    // spray 飞沫叠加到 outputTarget
+    renderer.autoClear = false;
+    renderer.render(this.sprayScene, camera);
+    renderer.autoClear = previousAutoClear;
+
+    renderer.setRenderTarget(previousTarget);
+    renderer.setClearColor(previousColor, previousAlpha);
+  }
+
+  dispose(): void {
+    if (!this.supported) return;
+    this.sceneTarget?.dispose();
+    this.depthTarget.dispose();
+    this.thicknessTarget.dispose();
+    this.blurA.dispose();
+    this.blurB.dispose();
+    this.thicknessBlurA.dispose();
+    this.thicknessBlurB.dispose();
+    this.lookupGeometry.dispose();
+    this.depthMaterial.dispose();
+    this.thicknessMaterial.dispose();
+    this.sprayMaterial.dispose();
+    this.depthBlurMaterial.dispose();
+    this.thicknessBlurMaterial.dispose();
+    this.compositeMaterial.dispose();
+    this.fsQuad.dispose();
+  }
+}