bDebugBreakOnPromptToRetryShaderCompile

bDebugBreakOnPromptToRetryShaderCompile

#Overview

name: bDebugBreakOnPromptToRetryShaderCompile

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bDebugBreakOnPromptToRetryShaderCompile is to control the behavior of the shader compilation system when encountering errors during shader compilation. Specifically, it determines whether the system should break into the debugger or display a message box when prompting to retry failed shader compilations.

This setting variable is primarily used by the shader compilation subsystem within Unreal Engine’s rendering module. It is referenced in the FShaderCompilingManager class, which is responsible for managing shader compilation tasks.

The value of this variable is set from the engine configuration file (GEngineIni) in the “DevOptions.Shaders” section. It is read during the initialization of the FShaderCompilingManager.

This variable interacts with other shader compilation-related variables, such as bPromptToRetryFailedShaderCompiles, which determines whether to prompt for retrying failed compilations at all.

Developers should be aware that enabling this option (setting it to true) will cause the engine to break into the debugger when shader compilation errors occur, but only if a debugger is attached. This can be useful for debugging shader compilation issues, but it may interrupt normal gameplay or editor operations.

Best practices when using this variable include:

  1. Use it primarily in development builds or when actively debugging shader issues.
  2. Ensure a debugger is attached when enabling this option, or it will fall back to displaying a message box.
  3. Consider disabling it in shipping builds or when not actively debugging shader problems to avoid unexpected interruptions.
  4. Use in conjunction with other shader debugging tools and settings for a comprehensive debugging approach.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1964, section: [DevOptions.Shaders]

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

Scope (from outer to inner):

file
function     FShaderCompilingManager::FShaderCompilingManager

Source code excerpt:

	verify(GConfig->GetInt( TEXT("DevOptions.Shaders"), TEXT("MaxShaderJobBatchSize"), MaxShaderJobBatchSize, GEngineIni ));
	verify(GConfig->GetBool( TEXT("DevOptions.Shaders"), TEXT("bPromptToRetryFailedShaderCompiles"), bPromptToRetryFailedShaderCompiles, GEngineIni ));
	verify(GConfig->GetBool(TEXT("DevOptions.Shaders"), TEXT("bDebugBreakOnPromptToRetryShaderCompile"), bDebugBreakOnPromptToRetryShaderCompile, GEngineIni));
	verify(GConfig->GetBool( TEXT("DevOptions.Shaders"), TEXT("bLogJobCompletionTimes"), bLogJobCompletionTimes, GEngineIni ));
	GConfig->GetFloat(TEXT("DevOptions.Shaders"), TEXT("WorkerTimeToLive"), GRegularWorkerTimeToLive, GEngineIni);
	GConfig->GetFloat(TEXT("DevOptions.Shaders"), TEXT("BuildWorkerTimeToLive"), GBuildWorkerTimeToLive, GEngineIni);

	verify(GConfig->GetFloat( TEXT("DevOptions.Shaders"), TEXT("ProcessGameThreadTargetTime"), ProcessGameThreadTargetTime, GEngineIni ));

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

Scope (from outer to inner):

file
function     bool FShaderCompilingManager::HandlePotentialRetryOnError

Source code excerpt:

				{
					// Use debug break in debug with the debugger attached, otherwise message box
					if (bDebugBreakOnPromptToRetryShaderCompile && FPlatformMisc::IsDebuggerPresent())
					{
						// A shader compile error has occurred, see the debug output for information.
						// Double click the errors in the VS.NET output window and the IDE will take you directly to the file and line of the error.
						// Check ErrorJobs for more state on the failed shaders, for example in-memory includes like Material.usf
						UE_DEBUG_BREAK();
						// Set GRetryShaderCompilation to true in the debugger to enable retries in debug

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShaderCompiler.h:718

Scope (from outer to inner):

file
class        class FShaderCompilingManager : IAssetCompilingManager

Source code excerpt:

	bool bPromptToRetryFailedShaderCompiles;
	/** If enabled when we enter the prompt to retry we will break in the debugger if one is attached rather than prompting. */
	bool bDebugBreakOnPromptToRetryShaderCompile = false;
	/** Whether to log out shader job completion times on the worker thread.  Useful for tracking down which global shader is taking a long time. */
	bool bLogJobCompletionTimes;
	/** Target execution time for ProcessAsyncResults.  Larger values speed up async shader map processing but cause more hitchiness while async compiling is happening. */
	float ProcessGameThreadTargetTime;
	/** Base directory where temporary files are written out during multi core shader compiling. */
	FString ShaderBaseWorkingDirectory;