r.ShaderCompiler.DebugDumpJobDiagnostics

r.ShaderCompiler.DebugDumpJobDiagnostics

#Overview

name: r.ShaderCompiler.DebugDumpJobDiagnostics

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

• type: Var
• help: If true, all diagnostic messages (errors and warnings) for each shader job will be dumped alongside other debug data (in Diagnostics.txt)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderCompiler.DebugDumpJobDiagnostics is to control the debug output of shader compilation job diagnostics in Unreal Engine 5’s shader compiler system.

This setting variable is primarily used in the shader compilation subsystem of Unreal Engine 5, specifically in the ShaderCompiler module. It is referenced in the ShaderCompiler.cpp file, which is part of the Engine’s runtime.

The value of this variable is set as a console variable (CVar) using the TAutoConsoleVariable template. It is initialized to false by default, meaning that the debug dump feature is turned off unless explicitly enabled.

The associated variable CVarDebugDumpJobDiagnostics directly interacts with r.ShaderCompiler.DebugDumpJobDiagnostics. They share the same value and purpose.

Developers must be aware that enabling this variable will cause all diagnostic messages (errors and warnings) for each shader job to be dumped alongside other debug data in a file named Diagnostics.txt. This can be useful for debugging shader compilation issues but may impact performance and generate large log files.

Best practices when using this variable include:

1. Only enable it when debugging shader compilation issues.
2. Be prepared for increased compilation times and larger log files when enabled.
3. Remember to disable it in production builds to avoid unnecessary overhead.
4. Use it in conjunction with other shader debugging tools for a comprehensive analysis.

Regarding the associated variable CVarDebugDumpJobDiagnostics:

The purpose of CVarDebugDumpJobDiagnostics is identical to r.ShaderCompiler.DebugDumpJobDiagnostics. It is the internal representation of the console variable within the engine’s code.

This variable is used in the FShaderCompilingManager::GetDumpShaderDebugInfoFlags() function to determine if the Diagnostics flag should be set in the shader debug info flags. When enabled, it adds the EShaderDebugInfoFlags::Diagnostics flag to the debug output.

The value of CVarDebugDumpJobDiagnostics is typically accessed using the GetValueOnAnyThread() method, which suggests that it can be safely read from multiple threads.

Developers should be aware that changes to CVarDebugDumpJobDiagnostics will directly affect the behavior controlled by r.ShaderCompiler.DebugDumpJobDiagnostics. They should treat these variables as two representations of the same setting.

Best practices for CVarDebugDumpJobDiagnostics are the same as those for r.ShaderCompiler.DebugDumpJobDiagnostics, as they are essentially the same variable.

#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:172

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarDebugDumpJobDiagnostics(
	TEXT("r.ShaderCompiler.DebugDumpJobDiagnostics"),
	false,
	TEXT("If true, all diagnostic messages (errors and warnings) for each shader job will be dumped alongside other debug data (in Diagnostics.txt)"),
	ECVF_ReadOnly);

static TAutoConsoleVariable<bool> CVarDebugDumpShaderCode(
	TEXT("r.ShaderCompiler.DebugDumpShaderCode"),

#Associated Variable and Callsites

This variable is associated with another variable named CVarDebugDumpJobDiagnostics. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly);

static TAutoConsoleVariable<bool> CVarDebugDumpJobDiagnostics(
	TEXT("r.ShaderCompiler.DebugDumpJobDiagnostics"),
	false,
	TEXT("If true, all diagnostic messages (errors and warnings) for each shader job will be dumped alongside other debug data (in Diagnostics.txt)"),
	ECVF_ReadOnly);

static TAutoConsoleVariable<bool> CVarDebugDumpShaderCode(

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

Scope (from outer to inner):

file
function     EShaderDebugInfoFlags FShaderCompilingManager::GetDumpShaderDebugInfoFlags

Source code excerpt:

	}

	if (CVarDebugDumpJobDiagnostics.GetValueOnAnyThread())
	{
		Flags |= EShaderDebugInfoFlags::Diagnostics;
	}

	if (CVarDebugDumpShaderCode.GetValueOnAnyThread())
	{