aibis-dream/Assets/Plugins/VolFx

VolFx — 模块化后处理 VFX

VFX Core — 基于 URP 的模块化后处理管线
© NullTale | Unity Forum | @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：

[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