r.DumpGPU.DumpOnScreenshotTest

r.DumpGPU.DumpOnScreenshotTest

#Overview

name: r.DumpGPU.DumpOnScreenshotTest

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DumpGPU.DumpOnScreenshotTest is to control GPU resource dumping during screenshot functional tests in Unreal Engine 5. This setting variable is primarily used for debugging and performance analysis in the rendering system, specifically during automated testing scenarios.

This setting variable is utilized by the Functional Testing module, particularly in the ScreenshotFunctionalTestBase class. It is part of the rendering system’s diagnostic tools and interacts with the GPU resource dumping functionality.

The value of this variable is set through a console command, as it is defined as a TAutoConsoleVariable. It can be modified at runtime using the console command “r.DumpGPU.DumpOnScreenshotTest”.

The associated variable GDumpGPUDumpOnScreenshotTest directly interacts with r.DumpGPU.DumpOnScreenshotTest. They share the same value and are used interchangeably in the code.

Developers must be aware of the following when using this variable:

  1. It is only effective when WITH_DUMPGPU is defined, which is typically only in development or debug builds.
  2. Enabling this variable may impact performance, as it triggers additional rendering operations.
  3. It is primarily intended for debugging and testing purposes, not for use in production builds.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging or analyzing GPU resource usage during screenshot tests.
  2. Be mindful of the performance impact when enabled.
  3. Use it in conjunction with other GPU debugging tools for comprehensive analysis.
  4. Disable it in production builds to avoid unnecessary overhead.

Regarding the associated variable GDumpGPUDumpOnScreenshotTest:

The purpose of GDumpGPUDumpOnScreenshotTest is to provide a programmatic way to access the value of r.DumpGPU.DumpOnScreenshotTest within the C++ code. It serves as a convenient interface for the engine’s internal systems to check and react to the console variable’s value.

This variable is used in the Functional Testing module, specifically in the ScreenshotFunctionalTestBase class. It allows the testing framework to conditionally execute GPU resource dumping operations based on the console variable’s value.

The value of GDumpGPUDumpOnScreenshotTest is set automatically by the TAutoConsoleVariable system, which links it to the r.DumpGPU.DumpOnScreenshotTest console variable.

GDumpGPUDumpOnScreenshotTest interacts directly with r.DumpGPU.DumpOnScreenshotTest, effectively serving as its in-code representation.

Developers should be aware that:

  1. Changes to r.DumpGPU.DumpOnScreenshotTest will be reflected in GDumpGPUDumpOnScreenshotTest.
  2. The variable is of type int32, so it can hold more than just binary on/off values.

Best practices for using GDumpGPUDumpOnScreenshotTest include:

  1. Use GetValueOnGameThread() to access its value safely from the game thread.
  2. Consider the performance implications of frequently checking this value in performance-critical code paths.
  3. Use it consistently throughout the codebase when referring to the r.DumpGPU.DumpOnScreenshotTest setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/FunctionalTesting/Private/ScreenshotFunctionalTestBase.cpp:25

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> GDumpGPUDumpOnScreenshotTest(
	TEXT("r.DumpGPU.DumpOnScreenshotTest"), 0,
	TEXT("Allows to filter the tree when using r.DumpGPU command, the pattern match is case sensitive."),
	ECVF_Default);

AScreenshotFunctionalTestBase::AScreenshotFunctionalTestBase(const FObjectInitializer& ObjectInitializer)
	: AFunctionalTest(ObjectInitializer)
	, ScreenshotOptions(EComparisonTolerance::Low)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/FunctionalTesting/Private/ScreenshotFunctionalTestBase.cpp:24

Scope: file

Source code excerpt:

#define	WITH_EDITOR_AUTOMATION_TESTS	(WITH_EDITOR && WITH_AUTOMATION_TESTS)

static TAutoConsoleVariable<int32> GDumpGPUDumpOnScreenshotTest(
	TEXT("r.DumpGPU.DumpOnScreenshotTest"), 0,
	TEXT("Allows to filter the tree when using r.DumpGPU command, the pattern match is case sensitive."),
	ECVF_Default);

AScreenshotFunctionalTestBase::AScreenshotFunctionalTestBase(const FObjectInitializer& ObjectInitializer)
	: AFunctionalTest(ObjectInitializer)

#Loc: <Workspace>/Engine/Source/Developer/FunctionalTesting/Private/ScreenshotFunctionalTestBase.cpp:149

Scope (from outer to inner):

file
function     void AScreenshotFunctionalTestBase::PrepareForScreenshot

Source code excerpt:

#if WITH_DUMPGPU
	// Reset render target extent to reduce size of the dumpGPU.
	if (GDumpGPUDumpOnScreenshotTest.GetValueOnGameThread() != 0)
	{
		FlushRenderingCommands();
		UKismetSystemLibrary::ExecuteConsoleCommand(GameViewportClient->GetWorld(), TEXT("r.ResetRenderTargetsExtent"), nullptr);
	}
#endif
#endif

#Loc: <Workspace>/Engine/Source/Developer/FunctionalTesting/Private/ScreenshotFunctionalTestBase.cpp:211

Scope (from outer to inner):

file
function     void AScreenshotFunctionalTestBase::RequestScreenshot

Source code excerpt:


#if WITH_AUTOMATION_TESTS && WITH_DUMPGPU
	if (GDumpGPUDumpOnScreenshotTest.GetValueOnGameThread() != 0)
	{
		FRDGBuilder::BeginResourceDump(TEXT(""));
	}
#endif
}