r.Shaders.Symbols

r.Shaders.Symbols

#Overview

name: r.Shaders.Symbols

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

This variable is created as a Console Variable (cvar).

• type: Var
• help: Enables debugging of shaders in platform specific graphics debuggers. This will generate and write shader symbols.\nThis enables the behavior of both r.Shaders.GenerateSymbols and r.Shaders.WriteSymbols.\nEnables shader debugging features that require shaders to be recompiled. This compiles shaders with symbols and also includes extra runtime information like shader names. When using graphical debuggers it can be useful to enable this on startup.\nThis setting can be overriden in any Engine.ini under the [ShaderCompiler] section.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shaders.Symbols is to enable debugging of shaders in platform-specific graphics debuggers by generating and writing shader symbols. This setting is primarily used for the shader compilation and debugging system within Unreal Engine 5.

The Unreal Engine subsystems that rely on this setting variable are primarily the shader compiler and rendering systems. This can be seen from the file locations where the variable is referenced, such as ShaderCompiler.cpp and ShaderCore.cpp.

The value of this variable is set through a console variable (CVar) system, as evident from the TAutoConsoleVariable declaration. It can be set in the Engine.ini configuration file under the [ShaderCompiler] section, or overridden via command line arguments.

This variable interacts with other related variables, specifically r.Shaders.GenerateSymbols and r.Shaders.WriteSymbols. When r.Shaders.Symbols is enabled, it effectively enables both of these other variables.

Developers must be aware that enabling this variable will cause shaders to be recompiled with additional debug information, which can impact performance and increase compilation times. It should primarily be used for debugging purposes and not in production builds.

Best practices when using this variable include:

1. Only enable it when actively debugging shader issues.
2. Be aware of the performance impact and increased compilation times.
3. Use it in conjunction with platform-specific graphics debuggers for maximum effectiveness.
4. Consider setting it in the appropriate Engine.ini file for long-term use on specific platforms during development.
5. When using it via command line, use the -dpcvars=“r.Shaders.Symbols=1” format.
6. Remember to disable it when not actively debugging to avoid unnecessary overhead.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1992, section: [ShaderCompiler]

• INI Section: ShaderCompiler
• Raw value: 0
• Is Array: False

Location: <Workspace>/Engine/Config/BaseEngine.ini:2007, section: [ShaderCompiler_BuildMachine]

• INI Section: ShaderCompiler_BuildMachine
• Raw value: 0
• Is Array: False

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:2146

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarShadersSymbols(
	TEXT("r.Shaders.Symbols"),
	0,
	TEXT("Enables debugging of shaders in platform specific graphics debuggers. This will generate and write shader symbols.\n")
	TEXT("This enables the behavior of both r.Shaders.GenerateSymbols and r.Shaders.WriteSymbols.\n")
	TEXT("Enables shader debugging features that require shaders to be recompiled. This compiles shaders with symbols and also includes extra runtime information like shader names. When using graphical debuggers it can be useful to enable this on startup.\n")
	TEXT("This setting can be overriden in any Engine.ini under the [ShaderCompiler] section."),
	ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Commandlets/CookShadersCommandlet.cpp:26

Scope: file

Source code excerpt:

// UnrealEditor-Cmd.exe <proj> -run=CookShaders -targetPlatform=<platform> -ShaderSymbolsExport=D:\ShaderSymbols\Out -material=M_UI_Base_BordersAndButtons
//
// Use -dpcvars="r.Shaders.Symbols=1" to force on symbols writing from the commandline, you can also edit the appropriate [Platform]Engine.ini and uncomment or add "r.Shaders.Symbols=1", especially if you want symbols enabled longer term for that specific platform.

namespace CookShadersCommandlet {

	// ShaderSymbols.info files will have a series of lines like the following, where the specifics of hash and extension are platform specific
	// hash0.extension Global/FTonemapCS/2233
	// hash1.extension M_Material_Name_ad9c64900150ee77/Default/FLocalVertexFactory/TBasePassPSFNoLightMapPolicy/0

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:616

Scope (from outer to inner):

file
function     bool ShouldGenerateShaderSymbols

Source code excerpt:

bool ShouldGenerateShaderSymbols(FName ShaderFormat)
{
	static const FShaderSymbolSettingHelper Symbols(TEXT("r.Shaders.Symbols"));
	static const FShaderSymbolSettingHelper GenerateSymbols(TEXT("r.Shaders.GenerateSymbols"), true);
	return Symbols.IsEnabled(ShaderFormat) || GenerateSymbols.IsEnabled(ShaderFormat);
}

bool ShouldGenerateShaderSymbolsInfo(FName ShaderFormat)
{

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderCore.cpp:629

Scope (from outer to inner):

file
function     bool ShouldWriteShaderSymbols

Source code excerpt:

bool ShouldWriteShaderSymbols(FName ShaderFormat)
{
	static const FShaderSymbolSettingHelper Symbols(TEXT("r.Shaders.Symbols"));
	static const FShaderSymbolSettingHelper WriteSymbols(TEXT("r.Shaders.WriteSymbols"), true);
	return Symbols.IsEnabled(ShaderFormat) || WriteSymbols.IsEnabled(ShaderFormat);
}

bool ShouldAllowUniqueShaderSymbols(FName ShaderFormat)
{