fluid_core 0.1.1

GPU-accelerated fluid simulation core library (wgpu, no winit dependency)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# fluid_core


Real-time GPU fluid simulation in Rust, powered by `wgpu`.

`fluid_core` focuses on simulation and rendering infrastructure, while app/demo code is kept in separate crates.



## 中文简介


`fluid_core` 是一个面向 Rust 生态的实时 GPU 流体仿真项目。

- 核心库不强绑定窗口框架（不依赖 `winit`）
- 统一输入接口支持鼠标、触摸和程序化注入
- 物理与后处理参数支持运行时热修改
- 提供桌面 demo，便于展示与二次开发

## English Summary


`fluid_core` is an open-source Rust project for interactive GPU fluid simulation.

- Core crate is window-system-agnostic
- Unified input API for mouse, touch, and programmatic splats
- Runtime-tunable simulation and post-processing parameters
- Desktop demo for showcase and experimentation

## Upstream Credit and Origin


This project is a Rust/`wgpu` re-implementation and engineering adaptation inspired by:

- PavelDoGreat/WebGL-Fluid-Simulation  
  https://github.com/PavelDoGreat/WebGL-Fluid-Simulation

The original implementation is based on JavaScript + WebGL.  
This repository ports and restructures core ideas into a Rust architecture (library + demo split, typed API surface, and reusable engine integration).

If you reuse or redistribute this project, please keep upstream attribution and preserve all required license notices.

## What Is Different From the Original WebGL Version


- Language/stack: Rust + `wgpu` instead of JavaScript + WebGL
- Architecture: reusable SDK-like core crate + separate desktop demo crate
- Integration model: accepts any window type implementing `raw-window-handle`
- API design: explicit engine/config/input types (`FluidEngine`, `FluidConfig`, `InputManager`)
- Runtime control: parameter updates and input injection via public Rust API

## Repository Layout


- `crates/fluid_core`: simulation core library
- `demos/desktop_demo`: desktop showcase app (`winit` + `egui`)
- [`api.md`](api.md): complete API reference
- `CONTRIBUTING.md`: contribution workflow and coding conventions
- `LICENSE`: project license text

## API Documentation


- Full SDK API reference: [`api.md`](api.md)
- Recommended entry points: `FluidEngine`, `FluidConfig`, `InputManager`, `RenderContext`
- For integration patterns (`egui`, runtime config updates, input injection), see the corresponding sections in [`api.md`](api.md)

## Features


- GPU fluid pipeline based on `wgpu`
- Bloom and sunrays post-processing
- Public engine API (`FluidEngine`, `FluidConfig`, `InputManager`)
- Demo scenes:
  - Main control panel
  - Circle Demo
  - Letter N Demo
  - Spiral Demo

## Quick Start


### 1) Build and run desktop demo


Run in this workspace root (`fluid_core/`):

```bash
cargo run -p fluid_core_desktop_demo
```

### 2) Use as a local dependency


```toml
[dependencies]
fluid_core = { path = "crates/fluid_core" }
```

### 3) Minimal usage example


```rust
use fluid_core::{FluidConfig, FluidEngine};

// `window` can be any type implementing HasWindowHandle + HasDisplayHandle
let mut engine = FluidEngine::new(&window, width, height, &FluidConfig::default()).await;

loop {
    engine.update(dt);
    engine.render()?;
}
```

## Controls (desktop demo)


- `Mouse Drag`: inject fluid force and dye
- `Space`: random burst
- `P`: pause/resume simulation
- `B`: toggle bloom
- `S`: toggle sunrays
- `H`: toggle shading
- `Esc`: quit

## Documentation


- API reference: [`api.md`](api.md)
- Contribution guide: `CONTRIBUTING.md`

## License


This repository is released under the MIT License. See `LICENSE`.

Upstream reference project (`PavelDoGreat/WebGL-Fluid-Simulation`) is also MIT-licensed.  
Please ensure attribution and license notice retention when redistributing derivative works.