调试着色器编译过程

概述调试着色器编译过程。

Windows
MacOS
Linux

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

启用中间着色器的转储

若要开始对引擎安装进行调试,你需要在 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) 模式下构建引擎和项目,此模式包含用于调试项目代码的符号。

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

BuildConfiguration_SCW.png

  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\

由于 ConsoleVariables.ini 文件中设置了控制台变量 r.DumpShaderDebugShortNames=1,因此名称已经过压缩,以便缩短文件长度。

例如,如果之前未启用此控制台变量,则路径将为:

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

着色器转储文件夹包含生成的批处理文件、文本文件和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以开始了解引擎调用平台编译器的方式。

如果你在 ConsoleVariables.ini 文件中启用了控制台变量 r.DumpShaderDebugWorkerCommandLine=1,而此变量可在生成的usf文件旁转储名为 DirectCompile.txt 的文件,则你可直接复制此命令行。

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback