Ultra-Water README

项目的 README,来自 github.com/Humpalumps/Ultra-Water。合并为一个 markdown 文件:README.md。

Ultra Water

Real-time ocean renderer for three.js (WebGL2), with a demo island scene.

npm install
npm run dev

Open the printed localhost URL. Orbit with the mouse (or a finger: phones get their own profile, see Phones and tablets). It opens on the Lagoon shot. Pick others from the camera dropdown (they also set the sun). The performance panel (top left) shows the GPU, render size, fps, ms per frame and a 20 s graph. Its Uncap FPS button switches the loop off the display's refresh: frames then render back-to-back, with at most three in flight on the GPU, so the counter shows what the machine can do while the scene keeps running live. The screen still updates at its own rate. Cap to display switches back. Run benchmark (also benchmark (uncapped) in the settings) renders 300 frames back-to-back with the render loop paused and times them to GPU completion with a fence. The screen freezes for about a second while it runs, so it only runs when asked.

Performance

Measured with the in-page benchmark on an RTX 3060 (Chrome, ANGLE/D3D11), 4× MSAA, all features on, at 1954×1692 (3.3 MP, the pixel count of 1440p; devicePixelRatio 2 on the browser window):

Shot ms / frame fps (uncapped)
Open ocean 3.30 ~303
Golden hour 4.35 ~230
Aerial 4.90 ~204
Underwater 4.93 ~203
Breakers 4.95 ~202
Lagoon 5.32 ~188
Flotsam (10 floating props) 5.79 ~173
Surf rock 5.92 ~169

Per pass in Breakers: water 1.90 ms, opaque (island, rocks, props) 1.63, post 0.38, caustics 0.22, FFT sim ~0.45 (independent of resolution). Caustics cost more under a low sun (about 0.37 ms in Golden hour), because the refracted rays fold more. Lagoon, Flotsam and Surf rock look down into the shallows, where nearly every water pixel runs the shore waves, foam and swash, so their water pass is 2.6–3.0 ms.

Earlier versions of this README quoted numbers 2–4× lower. Those came from a benchmark that synced with readPixels/finish, which ANGLE doesn't wait on. The fence-based benchmark is the one to trust. The HUD's GPU timer-query numbers read high while vsync-capped, because the GPU downclocks between frames.

Phones and tablets

The same build spots phones and tablets (a finger as the main pointer, matchMedia('(pointer: coarse)')) and starts them on a lighter profile. Desktop is unchanged. Add ?mobile or ?desktop to the URL to force either.

The mobile profile is resolution 0.6 (of the device pixel ratio, capped at 2), 2× MSAA, reflections at 0.35 scale and no bloom. On a phone the cost is mostly the number of render passes Chrome's GPU process has to translate, not pixels, so dropping bloom's 12 passes did more than lowering resolution. Auto resolution (auto resolution in the Quality folder) steps down by 0.05, to a floor of 0.5, when more than 4% of frames miss vsync over 2 s. It climbs back to 0.6 once frames are clean, and locks to a steady 30 fps if the floor still misses more than a quarter.

Measured before the shore update (surf rock, clear shallows, wet sand), on a OnePlus Nord 4 (Snapdragon 7+ Gen 3, Adreno 732, Chrome 156, which runs pages at 60 Hz on it), portrait, 424×782:

Shot live fps missed frames fps (uncapped)
Open ocean 60 0% 142
Aerial 60 0% 118
Underwater 60 0% 103
Lagoon 60 0% 102
Flotsam 60 0% 101
Golden hour 60 0% 99
Breakers 60 0% 95

With the desktop settings (708×1304, 4× MSAA, bloom) the same phone ran 41–50 fps live, missing up to a third of its frames, and 62 fps uncapped on average. Phone numbers move with temperature. These were taken warm (thermal status 1) while charging over USB.

What's in it

Waves (src/water/OceanSim.js)

Surface (src/water/OceanSurface.js)

Caustics (src/water/Caustics.js)

Underwater (src/water/UnderwaterPass.js, underside branch in OceanSurface.js)

Floating objects (src/water/WaterQuery.js, src/scene/floaters.js, src/scene/floaterMeshes.js, src/scene/floaterShadow.js)

Pipeline (src/main.js)

  1. Ingest the last water query, step the floaters, then:
    • render the floater shadow map;
    • update the impact rings;
    • run the FFT;
    • splat the caustics;
    • submit the next query.
  2. Planar reflection (half res, skipped underwater).
  3. Opaque pass into a single 4× MSAA HDR target.
  4. Water pass, depth-tested against the kept MSAA depth for correct per-sample edges.
  5. Underwater pass, when near or below the surface.
  6. Post (PostFX.js):
    • GPU auto exposure, metered in log space and adapted over time; the GUI value is compensation.
    • Dual-filter bloom with Karis average.
    • AgX.
    • Lens droplets.
    • TPDF dither.

Scene

The Water folder has a colour preset dropdown (clear, tropical, toxic green, purple, rust orange, murky brown). Each sets the absorption, in-scatter colour, thin-foam tint and underwater scattering together; clarity and scatter still adjust on top.

Camera presets: Golden hour, Breakers, Lagoon, Surf rock, Open ocean, Aerial, Flotsam and Underwater. Flotsam and Underwater spawn a field of floating props. The Floaters & underwater folder has spawn, drop and clear buttons, plus drag, buoyancy, scattering, shaft and meniscus controls.

Not in yet

The design was argued out with a second agent before building, and again for each round of upgrades.

License

MIT, see LICENSE. Code adapted from other projects is listed in THIRD_PARTY_NOTICES.md.

Ultra-Water (Humpalumps/Ultra-Water)

正在搜索数据库…

这是什么?Ultra Water 是一款为 three.js(WebGL2)打造的实时 FFT 海洋渲染器,支持近岸破碎浪、泡沫、焦散、水下渲染和浮力,并附带一个运行帧率超过 200 fps 的小岛演示场景。
这是一个现成的应用,还是可以直接放进我自己 three.js 场景里的库?它是一组 JS 模块(OceanSim.js、OceanSurface.js、Caustics.js、UnderwaterPass.js、WaterQuery.js 等),用于接入 three.js 场景;仓库还包含一个可直接运行的演示页面,展示带小岛、漂浮物和图形界面(GUI)的效果。
我要怎么试用这个演示?启动项目的本地开发服务器,在浏览器中打开终端输出的 localhost 地址,然后用鼠标旋转镜头视角(触屏设备上用手指拖动)。
我需要独立显卡才能获得好的性能吗?主要性能数据(200-300+ fps)是在 RTX 3060 上测得的,但同一版本也能在 OnePlus Nord 4 等手机上运行,并通过自动调节分辨率保持 60 fps 的实时帧率,因此不需要独立显卡,只需一个支持 WebGL2 的浏览器。
目前还缺少哪些海洋效果?移动中的物体不会留下尾迹(漂浮物只有在落入水中时才会触发水花环),漂浮物之间也不会相互碰撞;破碎浪只会倾斜,不会卷成完整的管状浪;紧贴镜头处的水面网格也比较粗糙。
手机模式和电脑模式有什么区别?它会自动检测触屏输入,并切换到更轻量的配置(0.6 倍分辨率缩放、2 倍 MSAA、0.35 倍缩放的反射、无泛光(bloom)),如果帧率开始错过垂直同步(vsync),还会进一步降低分辨率;在 URL 中加上 ?mobile 或 ?desktop 可以强制使用其中一种模式。
近岸破碎浪是怎么模拟的?它基于 eikonal 方程的传播时间场运行,该场通过快速扫描法从海岸向外计算。因此波前会减速、聚拢,并绕过水下地形发生折射;破碎会沿每条波峰不均匀地依次发生;不同海岸段的波前相撞时会逐渐消退,而不会折叠成大片水幕。
我能自己测试性能吗?可以。内置面板会显示 GPU、渲染尺寸、帧率和帧时间曲线图。点击“运行基准测试”按钮后,会连续渲染 300 帧,并通过 fence 同步等待 GPU 执行完成后再计时,以保证数据可靠。
我能改变水面的外观吗?可以。颜色预设下拉菜单提供清澈、热带、有毒绿、紫色、锈橙和浑浊棕几种选项,每种都会同时设置吸收、内散射颜色、泡沫色调和水下散射;你还可以在此基础上继续调整清澈度和散射强度。
大小
0.2 MB
星标
679
更新
提交Nov 02
时长
21天
提交 · 90 天