虚幻引擎5文档已被迁移至 Epic开发者社区

在开发期间，你最好掌握虚幻引擎在向平台的着色器编译器发送什么内容。本页所包含的信息将使你能够调试与之相关的任何问题。

启用中间着色器的转储

若要开始对引擎安装进行调试，你需要在 Engine/Config 文件夹中找到 ConsoleVariables.ini 配置文件，然后在其中启用部分预定义控制台变量。在 [Startup] 分段下，会发现以下控制台变量列表，这些变量应如下所示：

[Startup]

; 取消注释以获得有关着色器编译的详细日志以及发生错误后的重试机会
r.ShaderDevelopmentMode=1
; 取消注释以在保存文件夹中转储着色器
; 警告：将此变量保持开启一段时间，会让硬盘充满许多小文件和文件夹
r.DumpShaderDebugInfo=1
; 启用此变量后，SCW崩溃将输出当前工作程序中的作业列表
r.ShaderCompiler.DumpQueuedJobs=1
; 启用此变量后，转储着色器时，将生成一个与ShaderCompilerWorker -direct模式一起使用的额外文件
r.DumpShaderDebugWorkerCommandLine=1
; 启用此变量后，着色器编译器的警告将在所有着色器加载时发送到日志中（从DDC或者着色器编译任务发送）。
r.ShaderCompiler.EmitWarningsOnLoad=1

在调试模式下构建ShaderCompileWorker

默认情况下， UnrealBuildTool (UBT)为工具生成项目，它们始终在 开发（Development） 模式下进行编译。出于调试目的，你需要在 调试（Debug） 模式下构建引擎和项目，此模式包含用于调试项目代码的符号。

若要在调试模式下构建项目，请执行以下操作：

1. 使用 配置管理器（Configuration Manager） 更改Visual Studio中的解决方案属性，你可从 构建（Build） 菜单打开此管理器。

2. 将 ShaderCompileWorker (SCW)下拉框设为 Debug_Program 。

生成中间文件

若要调试着色器，你首先需要生成想要实际调试的文件。这需要启用用于转储中间着色器的控制台变量，从而允许后续编译转储生成的文件。

通过在 Engine/Shaders 文件夹中的 Common.usf 文件中添加一个空格或做一些无关紧要的更改，强制重新编译所有着色器。然后重新运行编辑器。此操作将触发所有着色器的重新编译，并将所有中间文件转储到项目的 Saved/ShaderDebugInfo 文件夹中。

如果你在调试某个材质，你可以进行任何更改，或者做一些无关紧要的更改，例如移动节点，以便触发更改。使用工具栏中的 保存（Save） 或 应用（Apply） 功能来保存或应用材质的更改，从而再次转储着色器文件。

转储着色器的文件夹结构

转储着色器所生成的文件夹路径包含了相关信息。让我们来看看转储着色器路径示例并分析其各个部分：

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\BasePassPixelShader.usf

首先是项目的根路径。在本例中，它指向名为Tappy Chicken的项目。

D:\UE4\Samples\Games\TappyChicken\

路径的下一个部分表示着色器转储后的保存路径。

D:\UE4\Samples\Games\TappyChicken\ Saved\ShaderDebugInfo \

对于每个着色器格式和/或平台，路径都将创建一个子文件夹。此路径将为 PC D3D着色器模型5 创建一个子文件夹。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\ PCD3D_SM5 \

每个材质都将有一个文件夹，且路径将创建一个名为 Global 的特殊文件夹。这里看到的调试着色器用于 M_Egg 材质。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\ M_Egg \

着色器在按顶点工厂排序的贴图中进行分组，此类顶点工厂通常对应于网格体/组件类型。此路径指向 LocalVF ，它表示 本地顶点工厂（Local Vertex Factory） 。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\ LocalVF \

路径的最后一个部分表示用于材质的各种功能集合。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\ BPPSFNoLMPolicy \

着色器转储文件夹包含生成的批处理文件、文本文件和usf文件。

• usf文件是转至平台编译器的最终着色器代码，编译器在预处理器之后运行。

• 批处理文件用于调用平台编译器以查看中间代码。

• 名为 DirectCompile.txt 的文本文件包含使用ShaderCompileWorker进行调试的命令行。

使用ShaderCompileWorker进行调试

ShaderCompileWorker可以使用以下命令行，以便调试对平台编译器的调用：

PathToGeneratedUsfFile -directcompile -format=ShaderFormat -ShaderType -entry=EntryPoint {plus platform specific switches}

• PathToGeneratedUsfFile 是ShaderDebugInfo文件夹中的最终usf文件。

• ShaderFormat 是你需要调试的着色器平台格式（在本例中为PCD3D_SM5）。

• ShaderType 可以是vs/ps/gs/hs/ds/cs，它们分别对应下列其中一种着色器类型：

  文件夹名称缩写	着色器类型
  vs	顶点着色器（Vertex Shader）
  ps	像素着色器（Pixel Shader）
  gs	几何体着色器（Geometry Shader）
  hs	凸包着色器（Hull Shader）
  ds	域着色器（Domain Shader）
  cs	计算着色器（Computer Shader）

• EntryPoint 是此着色器在usf文件中的进入点的函数名。

例如：

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\BasePassPixelShader.usf -format =PCD3D_SM5 -ps -entry =Main

如果你在 D3D11ShaderCompiler.cpp 上的 CompileD3D11Shader() 函数中添加了断点，则请用此命令行运行SCW以开始了解引擎调用平台编译器的方式。