r.DumpGPU.Stream

r.DumpGPU.Stream

#Overview

name: r.DumpGPU.Stream

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.Stream is to control the method of copying GPU data to disk for debugging and analysis purposes in Unreal Engine’s rendering system.

This setting variable is primarily used in the rendering subsystem of Unreal Engine, specifically in the RenderCore module. It’s part of the GPU dump functionality, which is used for debugging and performance analysis of GPU operations.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable, which means it can be changed at runtime through console commands or configuration files.

The r.DumpGPU.Stream variable interacts closely with other GPU dump-related variables, such as r.DumpGPU.Root and r.Test.SecondaryUpscaleOverride. These variables work together to control various aspects of the GPU dump process.

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

  1. Setting it to 0 (default) enables synchronous copying from GPU to disk, which is more careful about memory usage.
  2. Setting it to 1 enables asynchronous copying, which may be faster but carries a risk of running out of memory (OOM).
  3. The asynchronous mode uses a dedicated staging resources pool, which could impact performance and memory usage.

Best practices when using this variable include:

  1. Use the synchronous mode (0) by default to avoid potential OOM issues.
  2. If using asynchronous mode (1), consider also using r.DumpGPU.Root to minimize the number of passes to stream.
  3. Consider using r.Test.SecondaryUpscaleOverride to reduce resource size, which can help minimize OOM risk and reduce disk bandwidth usage per frame.
  4. Be cautious when enabling this in production builds, as it can impact performance and memory usage.

Regarding the associated variable GDumpGPUStream:

The purpose of GDumpGPUStream is to provide internal access to the r.DumpGPU.Stream setting within the C++ code of the engine.

This variable is used within the RenderCore module, specifically in the GPU dumping functionality.

The value of GDumpGPUStream is set automatically based on the r.DumpGPU.Stream console variable. They share the same value, with GDumpGPUStream providing a more convenient way to access this setting in C++ code.

GDumpGPUStream interacts directly with r.DumpGPU.Stream, effectively acting as its C++ representation. It’s also used in conjunction with other GPU dump-related variables like GDumpTestEnableDiskWrite and GDumpGPUFrameCount.

Developers should be aware that changes to r.DumpGPU.Stream will be reflected in GDumpGPUStream, and vice versa. They should use GDumpGPUStream when they need to access this setting within C++ code.

Best practices for using GDumpGPUStream include:

  1. Use GetValueOnGameThread() when accessing its value to ensure thread-safety.
  2. Be aware of the performance implications of frequently checking this value, especially in performance-critical code paths.
  3. Consider caching the value if it’s accessed frequently within a single frame or update cycle.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:111

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


static TAutoConsoleVariable<int32> GDumpGPUStream(
	TEXT("r.DumpGPU.Stream"), 0,
	TEXT("Asynchronously readback from GPU to disk.\n")
	TEXT(" 0: Synchronously copy from GPU to disk with extra carefulness to avoid OOM (default);\n")
	TEXT(" 1: Asynchronously copy from GPU to disk with dedicated staging resources pool. May run OOM. ")
	TEXT("Please consider using r.DumpGPU.Root to minimise amount of passes to stream and r.Test.SecondaryUpscaleOverride ")
	TEXT("to reduce resource size to minimise OOM and disk bandwidth bottleneck per frame."),
	ECVF_Default);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:110

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_Default);

static TAutoConsoleVariable<int32> GDumpGPUStream(
	TEXT("r.DumpGPU.Stream"), 0,
	TEXT("Asynchronously readback from GPU to disk.\n")
	TEXT(" 0: Synchronously copy from GPU to disk with extra carefulness to avoid OOM (default);\n")
	TEXT(" 1: Asynchronously copy from GPU to disk with dedicated staging resources pool. May run OOM. ")
	TEXT("Please consider using r.DumpGPU.Root to minimise amount of passes to stream and r.Test.SecondaryUpscaleOverride ")
	TEXT("to reduce resource size to minimise OOM and disk bandwidth bottleneck per frame."),

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:2081

Scope (from outer to inner):

file
function     FString FRDGBuilder::BeginResourceDump

Source code excerpt:

		NewResourceDumpContext->DumpingDirectoryPath = DirectoryPath / FApp::GetProjectName() + TEXT("-") + FPlatformProperties::PlatformName() + TEXT("-") + NewResourceDumpContext->Time.ToString() + TEXT("/");
	}
	NewResourceDumpContext->bStream = GDumpGPUStream.GetValueOnGameThread() != 0;
	NewResourceDumpContext->bEnableDiskWrite = GDumpTestEnableDiskWrite.GetValueOnGameThread() != 0;
	NewResourceDumpContext->DeltaTime = FApp::GetDeltaTime();
	NewResourceDumpContext->FrameCount = FMath::Max(GDumpGPUFrameCount.GetValueOnGameThread(), 1);

	if (Switches.Contains(TEXT("upload")))
	{