# VolFx — 模块化后处理 VFX

> **VFX Core** — 基于 URP 的模块化后处理管线  
> © NullTale | [Unity Forum](https://forum.unity.com/threads/1542860) | [@NullTale](https://x.com/NullTale)

**包名**: `www.nulltale.volfx` | **版本**: v2.3.3 | **依赖**: URP 14.x

---

## 1. 目录结构

```
Assets/Plugins/VolFx/
├── VolFx/
│   └── Runtime/                    ← 核心
│       ├── VolFx.cs                ← Render Feature 主入口
│       ├── VolFx.Api.cs            ← InitApi / CallApi 抽象
│       ├── Attributes/             ← ShaderNameAttribute, CurveRangeAttribute 等
│       ├── Utils/                  ← 工具类（GradientParameter, SoCollection 等）
│       └── Passes/
│           ├── Base/               ← 基础 Pass
│           │   ├── Blit/           BlitPass（通用 blit）
│           │   ├── Mask/           MaskPass, MaskVol
│           │   ├── Blur/           BlurPass, BlurVol
│           │   ├── Bloom/          BloomPass, BloomVol
│           │   └── Adjustments/    AdjustmentsPass, AdjustmentsVol
│           ├── Add/                ← 附加效果
│           │   ├── Chromatic/      ChromaticPass, ChromaticVol
│           │   ├── Distort/        DistortPass, DistortVol
│           │   ├── Grain/          GrainPass, GrainVol
│           │   ├── Posterize/      PosterizePass, PosterizeVol
│           │   ├── Scanlines/      ScanlinesPass, ScanlinesVol
│           │   ├── Sharpen/        SharpenPass, SharpenVol
│           │   └── Slice/          SlicePass, SliceVol
│           └── Lib/                ← 风格化效果
│               ├── Ascii/          AsciiPass, AsciiVol
│               ├── ColorMap/       ColorMapPass, ColorMapVol
│               ├── Dither/         DitherPass, DitherVol
│               ├── Flow/           FlowPass, FlowVol
│               ├── Glitch/         GlitchPass, GlitchVol
│               ├── OldMovie/       OldMoviePass, OldMovieVol
│               ├── Outline/        OutlinePass, OutlineVol
│               ├── Pixelation/     PixelationPass, PixelationVol
│               └── Vhs/            VhsPass, VhsVol
├── ScreenFx/                       ← 屏幕效果扩展（Timeline 等）
├── Samples/
└── Tools/
```

---

## 2. 基本架构

### 2.1 入口：VolFx — URP 的 ScriptableRendererFeature

在 URP 的 **Renderer Asset** 上挂载 VolFx Feature。主要字段：

| 字段 | 说明 |
|------|------|
| `_event` | 执行时机（默认 `BeforeRenderingPostProcessing`） |
| `_format` | RT 格式（默认 ARGB32，可选用 DefaultHDR） |
| `_mask` | Volume 层遮罩，用于分层控制 |
| `_source` | 输入源：Camera / LayerMask / Custom / Pool |
| `_output` | 输出目标：Camera / GlobalTex / RenderTex / Sprite |
| `_passes` | **按顺序执行**的 Pass 列表（`SoCollection<Pass>`） |

执行流程（简化）：

1. 每帧对 `_passes` 中的每个 Pass 调用 `Validate()`
2. 过滤出 `IsActiveCheck == true` 的 Pass
3. 对每个活跃 Pass 依次调用 `Init(InitApi)` 和 `Invoke(source, dest, CallApi)`
4. 通过 `RenderTargetFlip` 在 A/B buffer 间切换，形成管线链

### 2.2 Pass 基类 — VolFx.Pass

所有后处理 Pass 继承 `VolFx.Pass`，需实现：

- **ShaderName**：Shader 路径（可用 `[ShaderName("Hidden/VolFx/YourEffect")]`）
- **Validate(Material mat)**：判断是否启用、设置材质参数、返回是否参与渲染

可选的虚方法：

- `Init()` / `Init(InitApi initApi)` — 初始化资源
- `Invoke(source, dest, CallApi)` — 执行渲染（默认 blit）
- `Cleanup(CommandBuffer cmd)` — 清理

### 2.3 Volume 侧 — Unity VolumeComponent + IPostProcessComponent

所有 Vol 组件继承 `VolumeComponent` 并实现 `IPostProcessComponent`：

```csharp
[Serializable, VolumeComponentMenu("VolFx/YourEffect")]
public sealed class YourVol : VolumeComponent, IPostProcessComponent
{
    public ClampedFloatParameter m_Scale = new ClampedFloatParameter(1, 0, 1);
    public bool IsActive() => active && m_Scale.value > 0f;
    public bool IsTileCompatible() => false;
}
```

控制流程：场景中放置 Volume（Global / Local）→ 添加对应 Vol 组件 → Pass 在 `Validate()` 中通过 `Stack.GetComponent<YourVol>()` 读取参数并设置材质。

### 2.4 InitApi / CallApi

- **InitApi**：分配 RT，如 `initApi.Allocate(rt, width, height, format)`
- **CallApi**：执行 `Blit`、访问 `CamColor`、`Mat` 等

### 2.5 BlitPass — 简单 Blit

无 Volume、直接指定 Material 时，可使用 `BlitPass`。只需在 Inspector 中指定 `_mat` 和 `_pass`。

---

## 3. 自带效果列表

| 效果 | Pass | Vol | 目录 |
|------|------|-----|------|
| Adjustments | AdjustmentsPass | AdjustmentsVol | Base/Adjustments |
| Blur | BlurPass | BlurVol | Base/Blur |
| Bloom | BloomPass | BloomVol | Base/Bloom |
| Blit | BlitPass | — | Base/Blit |
| Mask | MaskPass | MaskVol | Base/Mask |
| Chromatic | ChromaticPass | ChromaticVol | Add/Chromatic |
| Distort | DistortPass | DistortVol | Add/Distort |
| Grain | GrainPass | GrainVol | Add/Grain |
| Posterize | PosterizePass | PosterizeVol | Add/Posterize |
| Scanlines | ScanlinesPass | ScanlinesVol | Add/Scanlines |
| Sharpen | SharpenPass | SharpenVol | Add/Sharpen |
| Slice | SlicePass | SliceVol | Add/Slice |
| Ascii | AsciiPass | AsciiVol | Lib/Ascii |
| ColorMap | ColorMapPass | ColorMapVol | Lib/ColorMap |
| Dither | DitherPass | DitherVol | Lib/Dither |
| Flow | FlowPass | FlowVol | Lib/Flow |
| Glitch | GlitchPass | GlitchVol | Lib/Glitch |
| OldMovie | OldMoviePass | OldMovieVol | Lib/OldMovie |
| Outline | OutlinePass | OutlineVol | Lib/Outline |
| Pixelation | PixelationPass | PixelationVol | Lib/Pixelation |
| Vhs | VhsPass | VhsVol | Lib/Vhs |

---

## 4. 添加新效果（简要流程）

1. **创建 Vol 组件**  
   继承 `VolumeComponent`，实现 `IPostProcessComponent`，添加 `VolumeComponentMenu` 和参数。

2. **创建 Pass**  
   继承 `VolFx.Pass`（或 `BlitPass`），使用 `[ShaderName("Hidden/VolFx/YourEffect")]`，在 `Validate()` 中读取 Volume 并设置材质。

3. **创建 Shader**  
   放在 Pass 指定的路径或 VolFx 常用路径下。

4. **挂到 VolFx**  
   在 VolFx 的 `_passes` 中添加新建的 Pass ScriptableObject。

5. **场景使用**  
   在 Volume 中添加对应 Vol 组件，通过参数控制效果。

---

## 5. 管线模式

- **Legacy**：旧版 URP 管线
- **Render Graph**：Unity 6+ (`UNITY_6000_0_OR_NEWER`) 自动启用

---

## 6. 快速引用

```
包名: www.nulltale.volfx
版本: 2.3.3
URP: 14.0.6
文档: https://forum.unity.com/threads/1542860
```