# VaporWaveSmoke

**Repository Path**: alienity/VaporWaveSmoke

## Basic Information

- **Project Name**: VaporWaveSmoke
- **Description**: Vaporwave: Scalable Real-Time Smoke Simulation and Rendering
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VaporWaveSmoke

> **基于 Vaporwave 技术的实时 3D 烟雾模拟与体积渲染（WebGPU）**

本项目是 EA SEED 提出的 **Vaporwave** 算法的浏览器实现 —— 一种可扩展的实时烟雾模拟技术，结合了 Stable Fluids 物理模拟与先进的体积渲染。

![Vaporwave Smoke Demo](./public/vaporwave-demo.png)

## 🌟 特性

- **基于物理的烟雾模拟**：采用 Stable Fluids 算法（Jos Stam, 1999）
- **Vaporwave 增强**：三次插值平流、RK4 积分、Clipmap 嵌套网格
- **实时体积渲染**：变分不透明度（VO）着色
- **WebGPU 加速**：计算着色器实现 GPU 并行
- **交互式控制**：支持调节模拟参数和障碍物

## 📖 技术概览

### 什么是 Vaporwave？

Vaporwave 是 EA SEED 开发的烟雾模拟技术，在经典 Stable Fluids 算法基础上进行了三项关键改进：

1. **高精度平流**：Tricubic 插值 + RK4 轨迹追踪（原始算法为三线性插值 + 欧拉法）
2. **Clipmap 嵌套网格**：3 层嵌套网格系统，用有限内存实现大规模模拟
3. **多重网格压力求解器**：利用 Clipmap 层级结构实现 O(N) 复杂度的泊松方程求解

### 烟雾背后的物理

模拟求解**不可压缩欧拉方程**：

```
Du/Dt + (1/ρ)∇p = g          （动量守恒）
∇·u = 0                      （不可压缩约束）
```

其中：
- **u** = 速度场
- **p** = 压力场
- **g** = 浮力（热烟雾上升！）

### 算法流程（每帧）

```
┌─────────────────────────────────────────────┐
│ 步骤 1：平流（半拉格朗日法）                 │
│ • 反向追踪：xP = xG - Δt·u(xG)  [RK4]       │
│ • 插值：q(xP)  [三次插值，64 个采样点]        │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│ 步骤 2：外力（浮力）                         │
│ • b = [α·s - β·(T-Tamb)]·g                  │
│ • 施加到垂直速度分量                         │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│ 步骤 3：投影（压力求解）                     │
│ • 计算散度：∇·u                             │
│ • 求解泊松方程：∇²p = (ρ/Δt)∇·u            │
│ • 减去梯度：u -= (Δt/ρ)∇p                  │
│ • 多重网格 V-Cycle：O(N) 求解器              │
└─────────────────────────────────────────────┘
                      ↓
              使用 VO 着色进行体积渲染
```

### 为什么是泊松方程？

核心洞察：在不可压缩流体中，**压力以"无穷大声速"瞬间传遍全场**。某处流体被挤压（散度>0），压力立即升高并向四周推动流体，直到各处进出平衡（散度=0）。

泊松方程 `∇²p = (ρ/Δt)∇·u` 回答的问题是：**"压力在每个位置应该是多少，才能同时消除所有位置的散度？"**

这是整个算法中最耗时的步骤 —— 使用多重网格法高效求解。

## 🏗️ 项目结构

```
VaporWaveSmoke/
├── src/
│   ├── engine/
│   │   ├── SmokeEngine.js      # WebGPU 初始化、相机、Uniforms
│   │   ├── math.js             # 矩阵/光线数学工具
│   │   ├── clipmap.js          # Clipmap 网格管理
│   │   └── vaporwave/
│   │       ├── VaporwaveSim.js     # 模拟步骤调度器
│   │       ├── VaporwaveRenderer.js # VO 预计算 + 体积渲染
│   │       ├── resources.js        # GPU 纹理/缓冲区创建
│   │       └── shaders/            # WGSL 计算着色器源码
│   ├── App.jsx                 # React UI 组件
│   ├── SmokeOverlay.jsx        # 模拟控制面板
│   └── styles.css
├── public/
│   └── vaporwave-deep-dive.md  # 📚 完整技术文档（中文）
├── package.json
└── vite.config.ts
```

## 🚀 快速开始

### 前置要求

- **Node.js** 18+
- **支持 WebGPU 的浏览器**（Chrome 113+、Edge 或 Firefox Nightly）
- **支持 WebGPU 的显卡**（大多数现代独立显卡）

### 安装

```bash
npm install
npm run dev
```

在浏览器中打开 `http://localhost:5173`。

### 控制方式

| 交互 | 功能 |
|------|------|
| **鼠标左键拖拽** | 旋转相机 |
| **鼠标右键拖拽** | 平移相机 |
| **滚轮** | 缩放 |
| **UI 面板** | 调节模拟参数 |

### 模拟参数

- **浮力（Buoyancy）**：控制热烟雾上升的强度
- **烟雾密度（Smoke Density）**：烟雾排放量
- **温度（Temperature）**：烟雾的初始温度
- **速度（Velocity）**：烟雾初始喷射速度
- **时间缩放（Time Scale）**：模拟速度（支持暂停/倒带）

## 📚 技术文档

完整技术深度解读，请参阅 [`public/vaporwave-deep-dive.md`](./public/vaporwave-deep-dive.md)：

- **第一部分**：从零开始的 Stable Fluids 推导
- **第二 - 三部分**：多重网格 V-Cycle 推导
- **第四 - 五部分**：Clipmap + 体积渲染
- **第六 - 九部分**：高级主题（球谐/球面高斯、VO、HG 相位函数）

### 快速参考：核心符号表

| 符号 | 含义 | 出现位置 |
|:----:|------|----------|
| **u** | 速度场 | 模拟 |
| **ρ** | 密度 | 模拟 |
| **p** | 压力场 | 投影步骤 |
| **∇·u** | 散度 | 不可压缩条件 |
| **∇²** | 拉普拉斯算子 | 泊松方程 |
| **σₜ** | 消光系数 | 渲染 |
| **v₀, v₁** | VO 密度矩 | 体积渲染 |
| **g** | HG 各向异性参数 | 相位函数 |

## 🔬 实现细节

### WebGPU 计算着色器

所有模拟步骤均通过计算着色器在 GPU 上运行：

| 着色器 | 功能 | 工作组大小 |
|--------|------|-----------|
| `advection.comp` | 三次插值 + RK4 平流 | 8×8×1 |
| `forces.comp` | 浮力施加 | 8×8×1 |
| `divergence.comp` | 计算散度 ∇·u | 8×8×1 |
| `jacobi.comp` | 多重网格压力求解 | 8×8×1 |
| `subtract.comp` | 速度修正 | 8×8×1 |
| `vo.comp` | 变分不透明度预计算 | 8×8×1 |
| `render.comp` | 体积光线步进 | 8×8×1 |

### 网格配置

默认：**128³** 网格单元（200 万体素）

```javascript
N = 128          // 每维网格分辨率
Δx = 0.02 m      // 单元格尺寸
Δt = 1/60 s      // 时间步长
CFL < 1          // 库朗数（稳定性条件）
```

Clipmap 模式：**3 层**（精细 → 粗糙），覆盖范围扩大 64 倍，内存占用不变。

### 性能表现

| 配置 | 网格尺寸 | 内存 | FPS（RTX 4070） |
|------|---------|------|----------------|
| 小型 | 64³ | 50 万体素 | ~240 |
| 默认 | 128³ | 200 万体素 | ~120 |
| 大型 | 256³ | 800 万体素 | ~45 |
| Clipmap 3 层 | 3×128³ | 600 万体素 | ~90 |

## 🎨 渲染：变分不透明度（VO）

传统体积渲染需要在每个像素上进行昂贵的光线步进。Vaporwave 使用**变分不透明度**预计算一个紧凑表示：

1. **球谐分解**：对密度场进行球谐函数分解
2. **L1 矩提取**：`v₀`（球面平均）、`v₁`（方向矩）
3. **每像素解析积分**：渲染时快速计算

这将渲染复杂度从 O(N³) 降低到 O(N²)，同时保持视觉质量。

### 体积渲染方程

```
L(x,ω) = ∫₀^D T(x+tω) · σₜ · Lₑ · p(ω,ω') dt

其中：
  T = 透射率 = exp(-τ)
  τ = 光学厚度
  p = Henyey-Greenstein 相位函数
```

## 🤝 贡献

本项目为教育和研究目的的参考实现。欢迎：

- 报告 Bug 或提出改进建议
- 尝试不同的网格分辨率
- 修改着色器参数实现视觉效果

## 📄 许可证

本项目仅供**教育和研究使用**。

Vaporwave 算法基于 EA SEED 的研究成果。商业用途可能需要向原作者获取授权。

## 🙏 致谢

- **Jos Stam** — Stable Fluids（1999）
- **Chris Lewin 等（EA SEED）** — Vaporwave 算法
- **Robert Bridson** — 《Fluid Simulation for Computer Graphics》
- **W.L. Briggs 等** — 《A Multigrid Tutorial》

## 🔗 参考文献

1. Stam, J. (1999). "Stable Fluids". *SIGGRAPH*.
2. Bridson, R. (2008). *Fluid Simulation for Computer Graphics*, 第二版.
3. Lewin, C. 等。(2023). "Vaporwave: Scalable Real-Time Smoke Simulation and Rendering". *EA SEED 技术报告*.
4. Briggs, W.L. 等。(2000). *A Multigrid Tutorial*, 第二版.

---

**使用 WebGPU + React + Vite 构建 ❤️**