three-base 2.0.142 → 2.0.145

package/WaterFlow/ScreenSpaceFluidPass.ts

@@ -1,789 +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();
-  }
-}
+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();
+  }
+}