如何为 Magpie 编写自定义效果：MagpieFX HLSL 效果格式完全指南

【免费下载链接】MagpieUnofficial experimental Magpie fork with colour-only DLSS, FSR2 and NVIDIA RTX Video integrations项目地址: https://gitcode.com/gh_mirrors/magpie27/Magpie

Magpie 是一款开源的游戏画面增强工具，支持 DLSS、FSR2 与 RTX Video 等色彩处理集成。它内置了一套基于 DirectX 11 计算着色器的自定义效果格式 MagpieFX——只要你了解 HLSL，就能用纯文本文件为 Magpie 添加锐化、降噪、CRT 等任意画面效果。本文是一份面向新手的完整指南：从效果文件结构、指令语法到参数、纹理与通道定义，教你一步步写出可运行的自定义效果。

为什么选择 MagpieFX 格式

Magpie 的所有效果都存储在effects文件夹中，本质上就是一批.hlsl文本文件。这意味着：

• 无需编译：效果文件由 Magpie 在运行时自动加载和着色器编译
• 纯文本友好：用记事本就能编辑，方便版本管理和分享
• 指令式声明：通过//!开头的注释指令声明参数、纹理和通道，格式统一、易读

官方文档 MagpieFX 是权威参考，本文帮你把它的核心概念讲透。

效果文件的整体结构

一个完整的 MagpieFX 效果文件按以下顺序组织（官方示例见 MagpieFX）：

1. 文件头指令：//!MAGPIE EFFECT声明效果类型，//!VERSION 4声明格式版本
2. 参数定义：//!PARAMETER块，定义用户可调的界面参数
3. 纹理定义：//!TEXTURE块，声明输入、输出和中间纹理
4. 采样器定义：//!SAMPLER块
5. 通道定义：//!PASS n块，每个通道是一段 GPU 着色器代码

官方内置的 Bicubic.hlsl 是一个绝佳的入门范本，结构清晰且只有百余行：

//!MAGPIE EFFECT //!VERSION 4 #include "StubDefs.hlsli" //!PARAMETER //!LABEL B //!DEFAULT 0.33 //!MIN 0 //!MAX 1 //!STEP 0.01 float paramB; //!TEXTURE Texture2D INPUT; //!TEXTURE Texture2D OUTPUT; //!SAMPLER //!FILTER LINEAR SamplerState sam; //!PASS 1 //!STYLE PS //!IN INPUT //!OUT OUTPUT float4 Pass1(float2 pos) { // 双三次插值逻辑…… }

💡 建议直接克隆仓库后打开 src/Effects/ 目录，里面有 FXAA、SMAA、CRT 等几十个现成效果可作参考。

参数定义：让效果拥有可调滑块

每个//!PARAMETER块声明一个参数，必须包含DEFAULT、MIN、MAX、STEP四项，并用LABEL指定界面上显示的名称：

//!PARAMETER //!LABEL Sharpness //!GROUP Detail //!DEFAULT 0.1 //!MIN 0.01 //!MAX 5 //!STEP 0.01 float sharpness;

几个实用技巧：

• GROUP参数分组：相同非空名称的参数会被归入同一个界面列，列顺序按分组首次出现顺序排列。例如把多个细节相关参数都归入Detail组，界面更整洁
• LABEL支持换行：字面量\n会显示为换行，适合较长标签
• 参数在通道中像普通变量一样使用，如paramB在 Bicubic.hlsl 中直接参与权重计算

纹理定义：INPUT 与 OUTPUT 是特殊关键字

纹理通过//!TEXTURE声明，其中INPUT和OUTPUT是特殊关键字：

//!TEXTURE Texture2D INPUT; //!TEXTURE //!WIDTH INPUT_WIDTH * 2 //!HEIGHT INPUT_HEIGHT * 2 Texture2D OUTPUT;

关键规则（来自 MagpieFX 文档）：

• INPUT不能作为任何通道的输出；OUTPUT不能作为通道的输入
• 只有最后一个通道可以写OUTPUT，且最后一个通道只能写OUTPUT
• OUTPUT的WIDTH/HEIGHT决定此效果的输出尺寸；不指定则支持任意输出尺寸
• 尺寸计算可用预定义常量：INPUT_WIDTH、INPUT_HEIGHT、OUTPUT_WIDTH、OUTPUT_HEIGHT

中间纹理可以指定FORMAT（如R8G8B8A8_UNORM）和偏移尺寸，还支持从文件加载纹理（BMP、PNG、JPG、DDS）：

//!TEXTURE //!SOURCE test.png Texture2D testTex;

通道定义：效果的真正计算逻辑

每个//!PASS n块是一个 GPU 通道。以双通道效果为例：

//!PASS 1 //!DESC First Pass //!STYLE PS //!IN INPUT //!OUT tex1 MF4 Pass1(float2 pos) { return MF4(1, 1, 1, 1); } //!PASS 2 //!IN INPUT, tex1 //!OUT OUTPUT //!BLOCK_SIZE 16, 16 //!NUM_THREADS 64, 1, 1 void Pass2(uint2 blockStart, uint3 threadId) { OUTPUT[blockStart] = MF4(1, 1, 1, 1); }

两种通道风格：

• //!IN声明通道输入纹理（可多个）
• //!OUT声明输出；PS 风格下可指定多个输出实现多渲染目标（MRT，最多 8 个）
• BLOCK_SIZE和NUM_THREADS控制每次 dispatch 的处理区域与并行线程数

预定义函数与宏：省掉样板代码

MagpieFX 内置了一批辅助函数（完整列表见 MagpieFX 文档），无需自己实现：

• GetInputSize()/GetOutputSize()：获取输入/输出纹理尺寸
• GetInputPt()/GetOutputPt()：获取每个像素的坐标步长
• GetScale()：获取输出相对输入的缩放比
• Rmp8x8(id)：8x8 坐标 swizzle 映射，提升纹理缓存命中率
• MulAdd(x, y, a)：比mul(x, y) + a更快的融合运算，机器学习类效果（如 Anime4K）常用，需先声明//!USE MulAdd

预定义类型MF、MF2、MF4等会随 FP16 能力自动切换为float或min16float别名，写效果时优先用MF4而不是裸float4，可以免费获得半精度支持。

若需声明 FP16 能力，在文件头加//!CAPABILITY FP16即可（是否生效取决于用户配置）。

让效果被正确识别：细节清单

写完效果后，检查以下几点避免踩坑：

1. 文件头两行不可少：//!MAGPIE EFFECT和//!VERSION 4，否则不会被识别为效果
2. 最后一个通道必须且只能输出到OUTPUT
3. 减少 IDE 报错：加上#include "StubDefs.hlsli"（可选，但能显著改善编辑器体验），该文件提供了预定义函数的桩定义，见 StubDefs.hlsli
4. 排序名称：可用//!SORT_NAME test1指定效果在列表中的排序名，否则按文件名排序
5. 放入 effects 文件夹：把.hlsl文件放进 Magpie 安装目录下的effects文件夹（可参考内置效果的存放方式，见 Effects.vcxproj 的部署规则），重启后在「效果组」→「添加效果器」中即可看到它

学习路线建议

1. 先读懂 Bicubic.hlsl：参数 + 单通道 PS 风格，最简完整闭环
2. 再看 Deband.hlsl 与 CRT 着色器（src/Effects/CRT/）：体验中间纹理和BLOCK_SIZE用法
3. 进阶参考 Anime4K/ 系列：多通道 +MulAdd+ FP16 的组合拳
4. 查阅 内置效果介绍 了解每个内置效果的输出尺寸与参数含义

掌握以上格式后，你已可以着手自己的第一个 MagpieFX 效果。更多细节请以官方 MagpieFX 文档 为准。

【免费下载链接】MagpieUnofficial experimental Magpie fork with colour-only DLSS, FSR2 and NVIDIA RTX Video integrations项目地址: https://gitcode.com/gh_mirrors/magpie27/Magpie