Go Unreal Shader Module (iv): Shader compilation

This article is ( go ):Unreal Debugging shader compilation Process

Debugging the shader compilation process

Rolando Caloca in April 19, 2016 | Learn to Program

• Share on Facebook  
• Share on Twitter  
• Share on Google +  
• Share on LinkedIn

Enable CVAR to allow dumping of intermediate shaders

In the Consolevariables.ini file (typically located in Engine/config/consolevariables.ini), enable the following Cvar:

Build Shadercompileworker while debugging

By default, Unrealbuildtool (UBT) builds the project for the tool so that it is always compiled at development time. To build the project during debugging, change the Shadercompileworker solution properties (Visual Studio: Build-and Configuration Manager) to Debug_program:

Generate intermediate files

At this point, you want to generate a file that can be debugged; enabling Cvar will allow subsequent compilation of files generated by the dump; to force rebuilding all shaders, add a space in ENGINE/SHADERS/COMMON.USF or make changes and rerun the editor. This will recompile the shader and dump all intermediate files in the Project/saved/shaderdebuginfo folder.

folder structure of the dump shader

Let's analyze the full path of the dump file:

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

The root path of the project:

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

Dump the root path of the shader:

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

Now, for each shader format/platform, you can find a subfolder, in this case, this is the PC D3D Shader Model 5:

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

Now there is a folder for each material name, and there is a special folder called Global. In this example, we are within the M_egg material:

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

Shaders are grouped within maps and sorted by vertex factory, which usually ultimately corresponds to the grid/component type; In this case, there is a local vertex factory:

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

Finally, the next path is the arrangement of the attributes, because we have previously enabled R.dumpshaderdebugshortnames=1, so the name is compressed (to reduce the path length). If you set it to 0, the full path will be:

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\FLocalVertexFactory\ Tbasepasspsfnolightmappolicy\basepasspixelshader.usf

In this folder, there is a batch file and a USF file. This USF file is the final shader code to provide to the platform compiler. This batch file allows you to invoke the platform compiler to see the intermediate code.

Using Shadercompileworker for debugging

Starting with version 4.11, we added a feature for Shadercompileworker (SCW) to debug the platform compiler call, as shown in the command line:

Pathtogeneratedusffile-directcompile-format=shaderformat-shadertype-entry=entrypoint

• Pathtogeneratedusffile is the final USF file in the Shaderdebuginfo folder
• Shaderformat is the shader platform format you want to debug (in this case, this is PCD3D_SM5)
• Shadertype is an item in the VS/PS/GS/HS/DS/CS that corresponds to the vertex, pixel, geometry, object shell, field, and compute shader types
• EntryPoint is the function name of the entry point for this shader in the USF file

For example, D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\ Basepasspixelshader.usf-format=pcd3d_sm5-ps-entry=main

You can now set breakpoints on the Compiled3d11shader () function in D3D11ShaderCompiler.cpp, run SCW from the command line, and you should be able to begin to understand how to invoke the platform compiler.

For more information about this topic, see the following two pages of the Unreal Engine documentation:

• Shader development
• HLSL Cross Compiler

Go Unreal Shader Module (iv): Shader compilation