RenderDoc 着色器编辑指南：从自定义可视化到场景着色器实时替换-开发者社区

开发工具
调试器
图形学
GPU

【免费下载链接】renderdoc

RenderDoc is a stand-alone graphics debugging tool.

项目地址：https://gitcode.com/gh_mirrors/re/renderdoc

本指南围绕 RenderDoc 图形调试工具中的着色器编辑能力展开，覆盖两大场景：为纹理查看器编写并编辑自定义可视化着色器（Custom Visualisation Shader），以及对捕获场景中的实际着色器进行临时替换与实时验证。读完本文，你将掌握如何通过内置 Shader Editor 窗口（基于 Scintilla 编辑器）修改着色器源码、按F5一键编译应用，并理解 RenderDoc 如何借助 SPIRV-Cross、glslang、spirv-dis 等外部工具在 DXBC/DXIL/SPIR-V/GLSL 之间完成反编译与编译的完整原理。

本文是 docs/how/how_edit_shader.rst 的深度展开，相关联动文档包括自定义可视化着色器指南、纹理查看器与管线状态窗口。

编辑自定义着色器（Custom Visualisation Shader）

自定义可视化着色器允许你在纹理查看器中查看任意纹理时，先执行一段自定义变换再把结果显示出来。最常见的用途是解码打包数据或自定义格式的数据，或者把某些数据以更直观的视觉效果呈现。你可以先阅读如何编写自定义可视化着色器来了解着色器的完整书写规范，本小节聚焦"如何编辑"。

着色器文件的存放位置与外部编辑

这些着色器以文件形式存放在应用程序存储目录中：

Windows：%APPDATA%/qrenderdoc/
其他平台（Linux/macOS 等）：~/.local/share/qrenderdoc

你可以使用任意编辑器直接修改这些文件。RenderDoc 会在加载捕获时加载这些着色器，并且会持续监视文件变化——无论是外部修改还是在 RenderDoc 内置编辑器中的修改，保存后都会自动重新加载生效。

需要特别注意的是：在外部编辑时，目前没有途径看到编译警告或编译错误。也就是说，外部编辑器修改文件后如果编译失败，你无法在文件系统中直接获知编译信息，只能回到 RenderDoc 内部观察结果（详见下文"错误处理与回退行为"一节）。

使用内置编辑器编辑自定义着色器

更推荐的编辑方式是在 RenderDoc 内部完成：

在纹理查看器中为当前纹理选中一个自定义着色器（选择方式见纹理查看器文档）；
点击编辑按钮（）；
弹出一个新窗口，显示该自定义着色器的源码。

此后你对这个着色器所做的任何修改都会保存到文件、重新编译并即时反映在纹理查看器中，前提是你仍然选中了该自定义着色器。此外，编辑可视化着色器时，编辑器还提供按钮可以插入若干预定义的变量片段（snippets），这些片段对应 RenderDoc 可以绑定的预定义输入，例如 UV 坐标、纹理尺寸、选中的 mip 级别、采样器与各类纹理资源绑定宏。具体片段内容与绑定说明详见自定义可视化着色器指南。

编辑场景着色器（Scene Shader）

RenderDoc 允许你编辑捕获中实际使用的着色器，修改后可以实时看到效果——这是调试渲染问题的利器。

启动着色器编辑器

打开管线状态窗口（pipeline_state 文档）；
定位到你希望修改的管线阶段；
点击该着色器旁边的编辑按钮（）。

如果该阶段存在多个编辑选项，会出现下拉菜单供你选择——这通常出现在有多个工具可用于反编译/编译该着色器时，具体见下文"着色器处理工具"一节。

作用范围与持久性

修改会影响所有使用该着色器的动作，而不仅仅是当前选中的动作；
这些更改会一直持续到编辑窗口关闭为止，关闭后恢复捕获中的原始着色器；
因此这是一种临时替换机制，适合做"改了看看效果"的迭代调试，不会永久破坏你的捕获数据。

着色器处理工具（Shader Processing Tools）

为什么需要外部工具

每种图形 API 都有其原生着色器格式：

API	原生着色器格式
D3D11	DXBC 字节码
D3D12	DXBC 字节码，以及 DXIL
Vulkan	SPIR-V 字节码
OpenGL	GLSL 着色器文本

此外，字节码着色器可能内嵌了带原始源码与编译设置的调试信息。

当你要编辑一个着色器时，RenderDoc 的处理逻辑是：

如果可用，优先显示原始源码（来自内嵌的调试信息）；
否则，尝试调用一个着色器处理工具把字节码反编译成可用形式；
如果没有任何工具可用，则显示一个生成的stub（占位骨架）或默认反汇编作为编辑起点。

每个工具都被定义为从某种输入翻译为某种输出：编译器可能把 HLSL 编译为 DXBC，反编译器可能把 SPIR-V 反编译为 HLSL。当编辑窗口打开时，RenderDoc 会自动选择最合适的工具把源码编译回 API 的原生格式，并且如果调试信息可用，还会用调试信息中的编译参数预填充工具参数，供你进一步定制。

RenderDoc 内置的已知工具

从源码 renderdoc/api/replay/replay_enums.h 中的KnownShaderTool枚举与ToolExecutable映射可以看到，RenderDoc 默认认识以下工具及可执行文件名：

KnownShaderTool	可执行文件	用途
`SPIRV_Cross`/`SPIRV_Cross_OpenGL`	`spirv-cross`	SPIR-V 反编译
`spirv_dis`/`spirv_dis_OpenGL`	`spirv-dis`	SPIR-V 反汇编
`glslangValidatorGLSL`/`glslangValidatorHLSL`/`glslangValidatorGLSL_OpenGL`	`glslangValidator`	GLSL/HLSL 编译为 SPIR-V
`spirv_as`/`spirv_as_OpenGL`	`spirv-as`	SPIR-V 汇编
`dxcSPIRV`/`dxcDXIL`	`dxc`	HLSL 编译为 SPIR-V / DXIL
`fxc`	`fxc`	HLSL 编译为 DXBC
`slangSPIRV`/`slangDXIL`	`slangc`	Slang 编译为 SPIR-V / DXIL

其中多个 SPIR-V 处理工具会随 RenderDoc 构建版本一同分发；如果系统上已经安装了对应版本，RenderDoc 也能自动探测并直接使用。自动探测逻辑可以在 qrenderdoc/Code/Interface/PersistentConfig.cpp 中看到：它先在 PATH 中查找工具，再到 RenderDoc 安装目录的plugins/spirv/（以及各平台对应的plugins-win64/spirv/、plugins-linux64/spirv/、../share/renderdoc/plugins/spirv/等）插件目录中查找。

工具的执行与参数替换

每个ShaderProcessingTool在配置层面包含六个字段（见 qrenderdoc/Code/Interface/PersistentConfig.h）：

tool：标识这是哪个已知工具（KnownShaderTool）；
name：人类可读名称；
executable：可执行文件路径；
args：命令行参数；
input/output：输入与输出格式（ShaderEncoding，用于在运行时按着色器类型匹配工具）。

实际的执行流程实现在 qrenderdoc/Code/Interface/ShaderProcessingTool.cpp 中：

CompileShader()把编辑后的源码写入临时文件shader_input，展开参数后启动外部进程，产物写入shader_output（见 ShaderProcessingTool.cpp 第 316-368 行）；
DisassembleShader()把字节码写入临时输入文件，再调用工具反编译（见 ShaderProcessingTool.cpp 第 255-314 行）；
RunTool()负责进程启动、等待与输出收集：stdout/stderr 被合并捕获，工具的启动失败、崩溃、非零退出码都会被记录到日志面板（见 ShaderProcessingTool.cpp 第 66-253 行）。

命令行参数中支持以下替换占位符（配置说明见 docs/window/settings_window.rst）：

占位符	替换内容
`{input_file}`	输入文件名
`{output_file}`	输出文件名
`{entry_point}`	入口点名称（仅在编译着色器时替换）
`{glsl_stage4}`	GLSL 阶段简写：`vert`、`tesc`、`tese`、`geom`、`frag`、`comp`（另有`task`、`mesh`）
`{hlsl_stage2}`	HLSL 阶段简写：`vs`、`hs`、`ds`、`gs`、`ps`、`cs`（另有`as`、`ms`）
`{full_stage}`	完整阶段名：`vertex`、`hull`、`domain`、`geometry`、`pixel`、`compute`（另有`amplification`、`mesh`）
`{spirv_ver}`	使用的 SPIR-V 版本，例如`spirv1.2`、`spirv1.6`
`{vulkan_ver}`	对应的 Vulkan 标识版本，例如`vulkan1.0`、`vulkan1.3`；该值可能是有损的，会取能编译给定 SPIR-V 版本的下一个最低Vulkan 版本，例如 SPIR-V 1.2 没有对应的 Vulkan 版本，会被向下取整为`vulkan1.0`

阶段简写与版本映射的实现分别可见 ShaderProcessingTool.cpp 第 31-44 行（glsl_stage4、full_stage、hlsl_stage2数组）与 ShaderProcessingTool.cpp 第 50-64 行（vulkanVerForSpirVer映射）。SPIR-V 版本本身则来自着色器调试信息中的@spirver编译标志（见 ShaderProcessingTool.cpp 第 268-271 行）。

在设置窗口中配置工具

在设置窗口的Shader Viewer 选项 → Shader Processing Tools区域（settings_window.rst 对应章节），你可以：

查看和启用自动探测到的内置工具；
添加自定义工具，此时必须自行配置命令行参数（使用上表占位符）；
为工具选择输入与输出格式（如 HLSL 输入、SPIR-V 输出），RenderDoc 会在运行时按当前着色器的需求匹配最合适的工具；
在着色器编辑面板上，每次调用工具时还可以额外追加自定义参数。

使用内置着色器编辑器

当你启动着色器编辑器后，主窗口会填满着色器源码，你可以借助Scintilla 编辑器进行编辑，支持基础编辑控制与语法高亮。Scintilla 组件随 qrenderdoc 源码一同分发（见 qrenderdoc/3rdparty/scintilla 目录），编辑器本体实现在 qrenderdoc/Windows/ShaderViewer.cpp。