r.GPUCrashOnOutOfMemory

r.GPUCrashOnOutOfMemory

#Overview

name: r.GPUCrashOnOutOfMemory

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GPUCrashOnOutOfMemory is to enable crash reporting when the GPU runs out of memory. This setting variable is primarily used for debugging and error handling in the graphics rendering system of Unreal Engine 5.

This setting variable is relied upon by the RHI (Rendering Hardware Interface) module and specific graphics API implementations, particularly the D3D11RHI and D3D12RHI modules. These modules are responsible for interfacing between Unreal Engine and the graphics hardware.

The value of this variable is set as a console variable, initialized with a default value of 0 (disabled). It can be modified at runtime through the console or configuration files.

The r.GPUCrashOnOutOfMemory variable interacts with the engine’s error handling and crash reporting systems. It doesn’t directly interact with other variables, but its state influences how the engine responds to out-of-memory conditions on the GPU.

Developers must be aware that enabling this variable (setting it to 1) will cause the engine to crash when a GPU out-of-memory condition is encountered. This can be useful for debugging but should not be enabled in production builds.

Best practices when using this variable include:

  1. Use it during development and testing phases to catch and diagnose GPU memory issues early.
  2. Ensure it’s disabled in production builds to prevent unexpected crashes for end-users.
  3. When enabled and a crash occurs, thoroughly investigate the circumstances leading to the out-of-memory condition.
  4. Use in conjunction with other debugging tools and variables to get a comprehensive view of GPU resource usage.
  5. Be cautious when enabling this in environments where GPU memory is limited, as it may lead to frequent crashes during development.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHI.cpp:1130

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarGPUCrashOnOutOfMemory(
	TEXT("r.GPUCrashOnOutOfMemory"),
	0,
	TEXT("Enable crash reporting on GPU OOM"),
	ECVF_ReadOnly
);

static TAutoConsoleVariable<int32> CVarGPUCrashDebuggingAftermathMarkers(

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Util.cpp:908

Scope (from outer to inner):

file
function     static void TerminateOnOutOfMemory

Source code excerpt:

#endif

	static IConsoleVariable* GPUCrashOOM = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUCrashOnOutOfMemory"));
	const bool bGPUCrashOOM = GPUCrashOOM && GPUCrashOOM->GetInt();
	if (bGPUCrashOOM)
	{
		// If no device provided then try and log the DRED status of each device
		D3D12RHI->ForEachDevice(InDevice, [&](FD3D12Device* IterationDevice)
			{

#Loc: <Workspace>/Engine/Source/Runtime/Windows/D3D11RHI/Private/D3D11Util.cpp:201

Scope (from outer to inner):

file
function     static void TerminateOnOutOfMemory

Source code excerpt:

		GetRendererModule().DebugLogOnCrash();
#endif
		static IConsoleVariable* GPUCrashOOM = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUCrashOnOutOfMemory"));
		if (GPUCrashOOM && GPUCrashOOM->GetInt())
		{
			UE_LOG(LogD3D11RHI, Fatal, TEXT("Out of video memory trying to allocate a rendering resource"));
		}
		else
		{