• 图形学
• 游戏开发

本篇指南基于 AMD FidelityFX SDK 官方文档《Building FidelityFX SDK Samples》展开，完整讲解如何从零生成并构建 SDK 附带的全部示例程序（Samples）：包括所需工具链的最低版本要求、BuildSamplesSolutionDX12.bat/BuildSamplesSolutionVK.bat批处理的交互式流程与背后的 CMake 行为，以及在 Visual Studio 中编译、启动与运行示例的完整步骤。读完本文，你将能够在 Windows 上独立生成FidelityFX SDK [DX12/VK] Samples.sln解决方案，并针对 DX12 或 Vulkan 后端自由选择要构建的 FidelityFX 效果示例。

概述：FidelityFX SDK 与示例程序的关系

FidelityFX SDK 是一套开源的、面向 DirectX 12 与 Vulkan 的高性能图形效果集合（着色器与运行时代码），涵盖超分辨率、帧生成、环境光遮蔽、阴影、景深、模糊、镜头效果等数十种效果，全部示例均使用 C++ 编写，并基于 FidelityFX Cauldron Framework 示例框架构建（见 SDK 官方介绍）。

在仓库中，FidelityFX SDK 位于 dependencies/FidelityFX-SDK 目录下。其构建体系分为两层：

1. SDK 后端层：由 sdk/BuildFidelityFXSDK.bat 驱动，负责把效果组件与对应图形 API 后端编译成静态库或 DLL；
2. 示例层：由 BuildSamplesSolutionDX12.bat 或 BuildSamplesSolutionVK.bat 驱动，先生成/构建 SDK 后端，再生成包含所有示例工程的 Visual Studio 解决方案。

前置条件：工具链与最低版本要求

要构建 SDK 示例，首先需要安装以下软件开发工具，并满足最低版本要求（引用自官方文档）：

注意：即使只构建 DX12 后端，官方文档仍建议安装 Vulkan SDK——SDK 的着色器编译工具链（如glslangValidator.exe）与若干共享工具会依赖它。

从源码看，CMake 版本约束在 dependencies/FidelityFX-SDK/CMakeLists.txt#L23 与 dependencies/FidelityFX-SDK/sdk/CMakeLists.txt#L23 中均被声明为 3.23 及以上，因此若你的 CMake 版本介于 3.23 与 3.30 之间，可以同时满足文档要求与源码约束。

生成 Visual Studio 解决方案：两种批处理脚本

安装好上述工具后，进入 FidelityFX SDK 根目录（即仓库中的 dependencies/FidelityFX-SDK），根据目标图形 API 运行对应的批处理脚本：

# DirectX 12 后端 > BuildSamplesSolutionDX12.bat # Vulkan 后端 > BuildSamplesSolutionVK.bat

交互式问答：是否将 SDK 构建为 DLL

脚本运行后会首先询问：

Build the SDK as DLL [y/n]?

• 输入y：将 SDK 构建为动态链接库（DLL）。脚本会追加-DFFX_BUILD_AS_DLL=1编译选项（见 BuildSamplesSolutionDX12.bat），生成的可执行文件在运行时动态加载 SDK DLL；
• 输入n（或其它字符）：将 SDK 构建为静态链接库，效果组件代码直接静态链接进示例程序。

对应到源码，该逻辑在 BuildSamplesSolutionDX12.bat#L35-L41 中实现，Vulkan 版本完全一致（BuildSamplesSolutionVK.bat#L35-L41）。

交互式问答：选择要构建的示例

随后脚本会打印一份示例清单并询问：

1. ALL 2. BLUR 3. BREADCRUMBS 4. BRIXELIZER GI 5. CACAO 6. CAS 7. DOF 8. FSR 9. HYBRID REFLECTIONS 10. HYBRID SHADOWS 11. LENS 12. LPM 13. PARALLEL SORT 14. SPD 15. SSSR 16. VRS Enter numbers of which samples to build [space delimitted]:

• 输入1：构建全部示例（对应 CMake 选项-DFFX_ALL=ON）；
• 输入一组以空格分隔的编号（如2 5 8）：仅构建对应示例。

每个编号会映射为对应的 CMake 开关（FFX_BLUR、FFX_CACAO、FFX_FSR等），同时脚本还会自动补充示例所依赖的 SDK 组件。例如：

• 选择4 BRIXELIZER GI时，脚本会同时开启FFX_BRIXELIZER与FFX_BRIXELIZER_GI（BuildSamplesSolutionDX12.bat#L78-L81）；
• 选择9 HYBRID REFLECTIONS时，会一并开启FFX_CLASSIFIER、FFX_DENOISER、FFX_SPD（BuildSamplesSolutionDX12.bat#L98-L101）；
• 选择15 SSSR时会一并开启FFX_DENOISER（BuildSamplesSolutionDX12.bat#L122-L125）。

这些依赖关系同样体现在 CMake 侧：例如 dependencies/FidelityFX-SDK/sdk/CMakeLists.txt#L152-L160 中，开启FFX_FSR3会自动默认开启FFX_FSR3UPSCALER、FFX_FI、FFX_OF三个 API；开启FFX_SSSR会自动默认开启FFX_DENOISER。

脚本背后的完整构建流程

两个批处理脚本的流程完全一致，以 DX12 版本为例（BuildSamplesSolutionDX12.bat）：

1. 架构检测：根据PROCESSOR_ARCHITECTURE环境变量自动判定为X64或ARM64，并追加-Ax64（或-AARM64）与-DCMAKE_GENERATOR_PLATFORM参数（BuildSamplesSolutionDX12.bat#L134-L144）；
2. 构建 SDK 后端：进入sdk子目录调用BuildFidelityFXSDK.bat，传入后端选项-DFFX_API_BACKEND=DX12_X64与用户选择的组件开关（BuildSamplesSolutionDX12.bat#L147-L153）；
3. 清理旧缓存：在根目录创建build\目录，并删除其中的CMakeFiles\与CMakeCache.txt，避免脏缓存影响新配置（BuildSamplesSolutionDX12.bat#L156-L168）；
4. 生成解决方案：在build\目录中执行cmake .. -DBUILD_TYPE=SAMPLES_DX12 <samples_build_options>（BuildSamplesSolutionDX12.bat#L174），Vulkan 版本对应为cmake -A x64 .. -DBUILD_TYPE=SAMPLES_VK ...（BuildSamplesSolutionVK.bat#L161）。

其中BUILD_TYPE是顶层 dependencies/FidelityFX-SDK/CMakeLists.txt 强制要求的变量，取值必须是CAULDRON、SAMPLES_DX12、SAMPLES_VK三者之一，否则会直接报错退出（CMakeLists.txt#L25-L42）。SAMPLES_DX12与SAMPLES_VK分别会把解决方案命名为FidelityFX SDK DX12 Samples与FidelityFX SDK VK Samples（CMakeLists.txt#L34-L39）。

而 SDK 后端构建脚本 sdk/BuildFidelityFXSDK.bat 本身也会：

• 检查cmake --version，未找到 CMake 时直接退出（BuildFidelityFXSDK.bat#L34-L41）；
• 无参数调用时默认使用-DFFX_API_BACKEND=DX12_<arch> -DFFX_ALL=ON -DFFX_AUTO_COMPILE_SHADERS=1（BuildFidelityFXSDK.bat#L71-L76）；
• 配置完成后依次以Debug、Release、RelWithDebInfo三种配置并行编译（--parallel 4），并把生成的库输出到bin\ffx_sdk\目录（BuildFidelityFXSDK.bat#L80-L82、sdk/CMakeLists.txt#L122-L125）。

生成的输出

构建脚本执行完毕后，会在 FidelityFX SDK 根目录下生成：

• build\目录：包含解决方案文件FidelityFX SDK [DX12/VK] Samples.sln（即FidelityFX SDK DX12 Samples.sln或FidelityFX SDK VK Samples.sln）；
• bin\目录：包含编译输出的可执行文件、配置（configs）、着色器（shaders）与 SDK 库文件。

另外需要说明：示例构建通过 common.cmake 定义了大量路径变量，包括BIN_OUTPUT、SHADER_OUTPUT、CONFIG_OUTPUT等（common.cmake#L39-L52），示例的可执行文件统一输出到bin\目录（dependencies/FidelityFX-SDK/CMakeLists.txt#L89-L94）。顶层 CMake 还会为 DX12/VK 分别生成DebugDX12、ReleaseDX12、RelWithDebInfoDX12（及对应的 VK 版本）等自定义配置类型（dependencies/FidelityFX-SDK/CMakeLists.txt#L57-L70），因此在 Visual Studio 中切换配置时应留意这些带后缀的配置名。

在 Visual Studio 中构建示例

CMake 生成的 .sln 默认包含 SDK 中所有示例应用的工程。构建方式：

1. 打开build\目录下的FidelityFX SDK [DX12/VK] Samples.sln；
2. 在菜单栏点击Build→Build solution。

此操作会按依赖关系先后编译：

• SDK 后端库（ffx_backend_native，见 dependencies/FidelityFX-SDK/CMakeLists.txt#L101-L117）；
• FidelityFX Cauldron Framework（Framework工程，见 dependencies/FidelityFX-SDK/CMakeLists.txt#L119-L129）；
• 示例共用的渲染模块库RenderModules（dependencies/FidelityFX-SDK/CMakeLists.txt#L131-L133）；
• 最后才是全部示例应用工程。

各示例工程的加入由 samples/CMakeLists.txt 根据先前选择的FFX_*开关决定，例如FFX_FSR对应fsrapi工程（samples/CMakeLists.txt#L31-L34）、FFX_CACAO对应cacao工程（samples/CMakeLists.txt#L41-L44）等；若选择了1. ALL，则默认将FFX_API_FSR设为启动项目（samples/CMakeLists.txt#L101-L103）。

在 Visual Studio 中运行示例

要运行某个示例应用，官方文档给出的步骤为：

1. 在解决方案资源管理器中，于"Effects"文件夹下选择感兴趣的示例工程；
2. 右键该工程，选择Set as Start-up project（设为启动项目）；
3. 点击菜单栏Build，然后点击Run（运行）。

从源码结构看，各示例工程被组织在 "Effects" 文件夹下，且顶层 CMake 已通过VS_STARTUP_PROJECT属性设置了默认启动项目（dependencies/FidelityFX-SDK/CMakeLists.txt#L153-L155），多数情况下你无需手动切换即可直接运行默认示例。

运行示例的补充：内容下载与运行时配置

构建成功后运行示例，还需要两方面的准备（详见官方 Running the FidelityFX SDK Samples）：

1. 示例内容（Content）下载：SDK 示例默认从预下载的场景内容中加载 glTF 场景、IBL 环境贴图与粒子图集，需要先使用 媒体投递工具 Media Delivery Tool 下载对应资源；
2. 运行时配置：示例（以及 Cauldron Framework 整体）通过 JSON 配置文件驱动运行时行为，加载顺序为：cauldronconfig.json（框架默认值）→ 示例自身配置文件（覆盖默认值）→ 各渲染模块的配置文件（提供模块默认值）→ 示例配置再次覆盖模块默认值。

各示例的配置文件位于 dependencies/FidelityFX-SDK/samples 下各示例目录的config/子目录中（例如blur/blurconfig.json、fsrapi/fsrapiconfig.json）。此外，示例还支持大量命令行覆盖参数，例如-resolution [WIDTH] [HEIGHT]覆盖启动分辨率、-loadcontent [SCENE PATH]加载自定义 glTF 场景、-devmode启用 CPU 验证与内存泄漏检测、-benchmark [duration=X]执行定帧基准测试等，可用于快速验证你自己的内容与效果。

常见问题排查要点

• No BUILD_TYPE specified报错：直接手动执行cmake ..而不带-DBUILD_TYPE会触发顶层 CMake 的致命错误（dependencies/FidelityFX-SDK/CMakeLists.txt#L25-L27），务必通过官方批处理脚本或在命令行显式传入-DBUILD_TYPE=SAMPLES_DX12/-DBUILD_TYPE=SAMPLES_VK；
• Cannot find path to CMake：说明 CMake 未加入 PATH 或未安装，SDK 构建脚本会直接退出（dependencies/FidelityFX-SDK/sdk/BuildFidelityFXSDK.bat#L34-L41）；
• Requested architecture ... not yet supported：顶层 CMake 目前仅支持x64、ARM64、ARM64EC三种生成平台（dependencies/FidelityFX-SDK/CMakeLists.txt#L53-L87），Win32 等其他平台不受支持；
• 配置名带后缀：解决方案中的有效配置是DebugDX12、ReleaseDX12、RelWithDebInfoDX12（或对应 VK 变体），切换构建配置时请使用这些名称；
• 首次构建耗时较长：SDK 后端会以三种配置各编译一遍（dependencies/FidelityFX-SDK/sdk/BuildFidelityFXSDK.bat#L80-L82），且着色器默认自动编译（FFX_AUTO_COMPILE_SHADERS=1），请耐心等待。

小结

构建 FidelityFX SDK 示例的完整链路可总结为：安装满足最低版本要求的工具链 → 运行BuildSamplesSolutionDX12.bat或BuildSamplesSolutionVK.bat→ 依次回答 DLL/静态库选择与示例组件选择 → 脚本自动构建 SDK 后端并生成build\FidelityFX SDK [DX12/VK] Samples.sln→ 在 Visual Studio 中 Build solution 并用 "Effects" 下的工程作为启动项目运行 → 配合 Media Delivery Tool 下载内容并按 JSON 配置/命令行参数调整运行行为。

本文所述步骤均以仓库内实际存在的构建脚本与 CMake 配置为据，相关文件可直接查看：根构建脚本 BuildSamplesSolutionDX12.bat / BuildSamplesSolutionVK.bat、SDK 构建脚本 BuildFidelityFXSDK.bat、顶层 CMake CMakeLists.txt、示例清单 samples/CMakeLists.txt，以及官方运行指南 running-samples.md。

• 图形学
• 游戏开发