import * as THREE from 'three/webgpu'; import type { TSLTextureNode, TSLUniformNode } from '../types/tsl.cjs'; import type { MPMSolver } from '../Simulation/MPM/MPMSolver.cjs'; import type { SurfaceField } from '../Simulation/MPM/SurfaceField.cjs'; import type { WaterVolume } from '../Simulation/MPM/WaterVolume.cjs'; import type { WaterCompositeSurface, WaterSurfaceCompositeUniforms } from './WaterNodeMaterial.cjs'; export type WaterRayMarchQualityPresetName = 'performance' | 'balanced' | 'high' | 'cinematic' | 'extreme'; export type WaterRayMarchScatterSamples = 0 | 4 | 8 | 12; export type WaterRayMarchWavesReflectionSteps = 0 | 24 | 32; export interface WaterRayMarchQualitySettings { resolutionScale: number; whitewaterScale: number; stepScale: number; isoScale: number; maxThickness: number; resolveDepthRange: number; maxSteps: number; refinementSteps: number; normalSmoothing: number; normalFilterRadius: number; trilinearTracing: boolean; scatterSamples: WaterRayMarchScatterSamples; wavesReflectionSteps: WaterRayMarchWavesReflectionSteps; temporal: boolean; } export interface WaterRayMarchQualityOverrides { resolutionScale?: number | undefined; whitewaterScale?: number | undefined; stepScale?: number | undefined; isoScale?: number | undefined; maxThickness?: number | undefined; resolveDepthRange?: number | undefined; maxSteps?: number | undefined; refinementSteps?: number | undefined; normalSmoothing?: number | undefined; normalFilterRadius?: number | undefined; trilinearTracing?: boolean | undefined; scatterSamples?: WaterRayMarchScatterSamples | undefined; wavesReflectionSteps?: WaterRayMarchWavesReflectionSteps | undefined; temporal?: boolean | undefined; } export interface WaterRayMarchRendererOptions extends WaterRayMarchQualityOverrides { qualityPreset?: string | undefined; /** Mirror the render-facing grid into a filterable rgba16float 3D texture. */ textureGridMirror?: boolean | undefined; } export interface WaterRayMarchTraceOptions { maxSteps?: number | undefined; refinementSteps?: number | undefined; normalSmoothing?: number | undefined; normalFilterRadius?: number | undefined; trilinearTracing?: boolean | undefined; scatterSamples?: WaterRayMarchScatterSamples | undefined; wavesReflectionSteps?: WaterRayMarchWavesReflectionSteps | undefined; temporal?: boolean | undefined; } export interface WaterRayMarchQualitySnapshot extends WaterRayMarchQualitySettings { qualityPreset: WaterRayMarchQualityPresetName; } type WaterFloatUniform = TSLUniformNode<'float', number>; type WaterUintUniform = TSLUniformNode<'uint', number>; type WaterVec2Uniform = TSLUniformNode<'vec2', THREE.Vector2>; type WaterMat4Uniform = TSLUniformNode<'mat4', THREE.Matrix4>; export interface WaterRayMarchRendererUniforms extends WaterSurfaceCompositeUniforms { near: WaterFloatUniform; far: WaterFloatUniform; projectionMatrix: WaterMat4Uniform; projectionMatrixInverse: WaterMat4Uniform; viewMatrix: WaterMat4Uniform; viewMatrixInverse: WaterMat4Uniform; previousViewProjectionMatrix: WaterMat4Uniform; previousViewMatrix: WaterMat4Uniform; fullResolution: WaterVec2Uniform; fullTexelSize: WaterVec2Uniform; thicknessTexelSize: WaterVec2Uniform; traceTexelSize: WaterVec2Uniform; stepScale: WaterFloatUniform; isoScale: WaterFloatUniform; maxThickness: WaterFloatUniform; resolveDepthRange: WaterFloatUniform; scatterExtinction: WaterFloatUniform; sunDirection: TSLUniformNode<'vec3', THREE.Vector3>; temporalBlend: WaterFloatUniform; historyValid: WaterFloatUniform; frameIndex: WaterUintUniform; cameraUnderwater: WaterFloatUniform; } export interface WaterRayMarchSceneNodesOptions { depthNode?: TSLTextureNode | null | undefined; } export interface WaterRayMarchCamera extends THREE.Camera { near: number; far: number; } export type WaterRayMarchSource = WaterVolume & { solver: MPMSolver; surface: SurfaceField; }; /** * Coherent raymarch quality tiers. The settings are intentionally grouped: * increasing only the loop cap does not improve a trace that is still running * below native resolution with nearest-cell normals. * * `cinematic` is the practical high-end tier and evaluates the continuous * trilinear density field at every DDA segment. `extreme` adds the widest * edge-aware surface polish and full-resolution whitewater for hero captures. */ export declare const WATER_RAYMARCH_QUALITY_PRESETS: Readonly<{ performance: Readonly<{ resolutionScale: 0.5; whitewaterScale: 0.1875; stepScale: 1.5; isoScale: 1; maxThickness: 4; resolveDepthRange: 1; maxSteps: 224; refinementSteps: 3; normalSmoothing: 0; normalFilterRadius: 0; trilinearTracing: false; scatterSamples: 0; wavesReflectionSteps: 0; temporal: false; }>; balanced: Readonly<{ resolutionScale: 0.7; whitewaterScale: 0.25; stepScale: 1; isoScale: 1; maxThickness: 4; resolveDepthRange: 0.75; maxSteps: 384; refinementSteps: 5; normalSmoothing: 0; normalFilterRadius: 0; trilinearTracing: false; scatterSamples: 4; wavesReflectionSteps: 0; temporal: true; }>; high: Readonly<{ resolutionScale: 0.9; whitewaterScale: 0.375; stepScale: 1; isoScale: 1; maxThickness: 4; resolveDepthRange: 0.5; maxSteps: 384; refinementSteps: 6; normalSmoothing: 1.5; normalFilterRadius: 2; trilinearTracing: false; scatterSamples: 8; wavesReflectionSteps: 0; temporal: true; }>; cinematic: Readonly<{ resolutionScale: 1; whitewaterScale: 0.5; stepScale: 1; isoScale: 1; maxThickness: 4; resolveDepthRange: 0.35; maxSteps: 448; refinementSteps: 7; normalSmoothing: 3.5; normalFilterRadius: 5; trilinearTracing: true; scatterSamples: 8; wavesReflectionSteps: 24; temporal: false; }>; extreme: Readonly<{ resolutionScale: 1; whitewaterScale: 1; stepScale: 1; isoScale: 1; maxThickness: 4; resolveDepthRange: 0.25; maxSteps: 512; refinementSteps: 8; normalSmoothing: 4.5; normalFilterRadius: 5; trilinearTracing: true; scatterSamples: 12; wavesReflectionSteps: 32; temporal: false; }>; }>; /** Return a mutable copy of a named raymarch quality tier. */ export declare function getWaterRayMarchQualityPreset(name?: string): WaterRayMarchQualitySettings; /** * Grid-accelerated volume raymarcher for {@link WaterVolume}. * * MLS-MPM already constructs a dense spatial mass grid every substep. Reading * that grid directly is the dynamic-water equivalent of traversing a rebuilt * point BVH, without the CPU readback and BVH rebuild that would otherwise * dominate a one-million-particle frame. The fragment pass performs a voxel * DDA, refines the first density crossing with trilinear samples, evaluates an * analytic density gradient, and integrates the visible water column. * * A reduced-resolution trace is edge-aware resolved to full resolution. The * public texture contract matches {@link WaterSurfaceRenderer}: `depthNode`, * `normalNode`, `thicknessNode`, and `whitewaterNode` can be passed directly to * {@link createWaterComposite} and `DiffuseParticles.createMesh`. * * @short Dynamic MLS-MPM water volume raymarcher over the solver's GPU mass grid. * @category Materials * @tags WebGPU, TSL, Water, Raymarching, Volume */ export declare class WaterRayMarchRenderer implements WaterCompositeSurface { renderer: THREE.Renderer; water: WaterRayMarchSource; solver: MPMSolver; qualityPreset: WaterRayMarchQualityPresetName; resolutionScale: number; whitewaterScale: number; maxSteps: number; refinementSteps: number; normalSmoothing: number; normalFilterRadius: number; trilinearTracing: boolean; scatterSamples: WaterRayMarchScatterSamples; wavesReflectionSteps: WaterRayMarchWavesReflectionSteps; temporal: boolean; textureGridMirror: boolean; uniforms: WaterRayMarchRendererUniforms; rawDepthNode: TSLTextureNode; depthNode: TSLTextureNode; normalNode: TSLTextureNode; surfaceDataNode: TSLTextureNode; thicknessNode: TSLTextureNode; /** rg scatter integrals; |b| horizon visibility; b<0 secondary-wave hit; a normal variance. */ auxNode: TSLTextureNode; whitewaterNode: TSLTextureNode; width: number; height: number; fullWidth: number; fullHeight: number; whitewaterWidth: number; whitewaterHeight: number; private _sceneDepthNode; private _disposed; private _gridMirror; private _maxSurfaceHeight; private _gridTexture; private _gridTextureNode; private _gridTextureCopy; private _surfaceFieldNode; private _traceTarget; private _resolveHorizontalTarget; private _resolvedTarget; private _temporalTargets; private _whitewaterTarget; private _traceQuad; private _resolveQuad; private _resolveVerticalQuad; private _temporalQuad; private _whitewaterScene; private _whitewaterMesh; private _whitewaterTargetNeedsClear; private _clearColor; private _traceMaterial; private _resolveMaterial; private _resolveVerticalMaterial; private _temporalMaterial; private _traceDepthInput; private _traceSurfaceInput; private _traceAuxInput; private _temporalCurrentDepthInput; private _temporalCurrentSurfaceInput; private _temporalCurrentAuxInput; private _temporalHistoryDepthInput; private _temporalHistorySurfaceInput; private _temporalHistoryAuxInput; private _temporalIndex; private _historyValid; private _cameraHistoryInitialized; private _previousCameraPosition; private _previousCameraQuaternion; private _cameraPositionScratch; private _cameraQuaternionScratch; private _previousProjectionMatrix; /** * @param {THREE.WebGPURenderer} renderer Active renderer. * @param {WaterVolume} water WaterVolume with its SurfaceField enabled. * @param {Object} [options] * @param {'performance'|'balanced'|'high'|'cinematic'|'extreme'} [options.qualityPreset='balanced'] Coherent quality tier. * @param {number} [options.resolutionScale=0.7] Internal trace resolution. * @param {number} [options.whitewaterScale=0.25] Whitewater accumulation resolution. * @param {number} [options.stepScale=1] Empty-cell stride; one visits every crossed cell. * @param {number} [options.isoScale=1] Multiplier over the SurfaceField mass iso level. * @param {number} [options.maxThickness=4] Maximum integrated world-space optical path. * @param {number} [options.resolveDepthRange=0.75] Edge-aware resolve range in view units. * @param {number} [options.maxSteps=384] Compile-time DDA iteration cap. * @param {number} [options.refinementSteps=5] Compile-time crossing refinement count. * @param {number} [options.normalSmoothing=0] Density-normal radius in grid cells; zero uses the analytic trilinear gradient. * @param {number} [options.normalFilterRadius=0] Edge-aware screen-space normal filter radius in pixels. * @param {boolean} [options.trilinearTracing=false] Evaluate trilinear density during every DDA segment. * @param {0|4|8|12} [options.scatterSamples=4] Fixed simulation-driven volume-lighting samples per hit. * @param {0|24|32} [options.wavesReflectionSteps=0] Fixed secondary mass-grid reflection march. * @param {boolean} [options.temporal=true] Reproject and accumulate trace history; tier default applies. * @param {boolean} [options.textureGridMirror=true] Copy the grid once per rendered frame to a filterable rgba16float 3D texture. */ constructor(renderer: THREE.Renderer, water: WaterVolume, options?: WaterRayMarchRendererOptions); private _buildGridTextureMirror; /** Filterable velocity + mass mirror (`rgb`: grid velocity, `a`: mass). */ get gridTexture(): THREE.Storage3DTexture | null; private _gridPointer; private _readMass; private _nearestMass; private _trilinearCorners; private _trilinearMass; private _trilinearGradient; private _smoothedGradient; private _buildTraceMaterial; private _buildResolveMaterial; private _buildVerticalResolveMaterial; private _buildTemporalMaterial; private _setOutputTarget; /** Configure scene depth so the optical path stops at opaque geometry. */ setSceneNodes({ depthNode }?: WaterRayMarchSceneNodesOptions): this; /** Attach the diffuse-particle mesh used by the reduced whitewater pass. */ setWhitewaterMesh(mesh: THREE.Object3D | null | undefined): this; /** Set the internal trace resolution and invalidate target dimensions. */ setResolutionScale(scale: number): this; /** Set the independent whitewater accumulation resolution. */ setWhitewaterScale(scale: number): this; /** Apply one coherent quality tier, optionally overriding individual values. */ setQualityPreset(name: string, overrides?: WaterRayMarchQualityOverrides): this; /** Snapshot the effective settings, including manual overrides. */ getQualitySettings(): WaterRayMarchQualitySnapshot; /** Rebuild after changing compile-time tracing and normal-reconstruction options. */ setTraceOptions({ maxSteps, refinementSteps, normalSmoothing, normalFilterRadius, trilinearTracing, scatterSamples, wavesReflectionSteps, temporal, }?: WaterRayMarchTraceOptions): this; /** Backward-compatible loop-bound convenience. */ setTraceIterations(options?: WaterRayMarchTraceOptions): this; /** Drop reprojected trace history after simulation resets or camera cuts. */ resetHistory(): this; resize(): this; private _isCameraCut; /** Trace, edge-aware resolve, and accumulate whitewater for one frame. */ update(renderer: THREE.Renderer, camera: WaterRayMarchCamera): this; dispose(): void; } export default WaterRayMarchRenderer;