r.DumpGPU.Screenshot

r.DumpGPU.Screenshot

#Overview

name: r.DumpGPU.Screenshot

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.DumpGPU.Screenshot is to control whether a final screenshot should be taken during GPU dump operations in Unreal Engine 5. This setting is primarily used for debugging and performance analysis purposes.

This setting variable is utilized by the Engine module, specifically within the GPU dumping functionality. Based on the callsites, it’s part of the engine’s core rendering and debugging systems.

The value of this variable is set through a console variable declaration using TAutoConsoleVariable. It’s initialized with a default value of 1, meaning that by default, a screenshot will be taken during GPU dumps.

The associated variable GDumpGPUScreenshot directly interacts with r.DumpGPU.Screenshot. They share the same value and purpose, with GDumpGPUScreenshot being the actual variable used in the C++ code to check the setting’s value.

Developers should be aware that this variable is only defined and used when the WITH_DUMPGPU preprocessor macro is set. This suggests that the GPU dumping functionality, including this screenshot feature, may not be available in all build configurations.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging or performance analysis, as taking screenshots may impact performance.
  2. Be aware of the potential disk space usage when enabling this feature, especially during extended debugging sessions.
  3. Use it in conjunction with other GPU dumping tools and settings for comprehensive analysis.

Regarding the associated variable GDumpGPUScreenshot:

The purpose of GDumpGPUScreenshot is to provide a runtime-accessible way to check whether a screenshot should be taken during GPU dumps.

It’s used within the Engine module, specifically in the HandleDumpGPUCommand function of the UEngine class.

The value of GDumpGPUScreenshot is set through the r.DumpGPU.Screenshot console variable.

GDumpGPUScreenshot interacts directly with the FScreenshotRequest system to trigger a screenshot when the GPU dump is performed.

Developers should be aware that this variable is checked on the game thread (GetValueOnGameThread()), which means changes to the console variable will be reflected in the next frame.

Best practices for using GDumpGPUScreenshot include:

  1. Use it to conditionally trigger screenshots in GPU-related debugging code.
  2. Be cautious about performance implications when frequently checking or using this variable in performance-critical sections.
  3. Consider the thread safety implications when accessing this variable from different threads.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:255

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> GDumpGPUScreenshot(
	TEXT("r.DumpGPU.Screenshot"), 1,
	TEXT("Whether to take a final screenshot."),
	ECVF_Default);

#endif

DEFINE_LOG_CATEGORY(LogEngine);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:254

Scope: file

Source code excerpt:

#if WITH_DUMPGPU

static TAutoConsoleVariable<int32> GDumpGPUScreenshot(
	TEXT("r.DumpGPU.Screenshot"), 1,
	TEXT("Whether to take a final screenshot."),
	ECVF_Default);

#endif

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:5970

Scope (from outer to inner):

file
function     bool UEngine::HandleDumpGPUCommand

Source code excerpt:

	{
		// Dump a screenshot
		if (GDumpGPUScreenshot.GetValueOnGameThread())
		{
			FString FileName = ResourceDumpDirectory / TEXT("Base/Screenshot.png");
			FScreenshotRequest::RequestScreenshot(FileName, /* bShowUI = */ true, /* bAddFilenameSuffix = */ false);
		}
	}