r.RDG.Debug.ExtendResourceLifetimes

r.RDG.Debug.ExtendResourceLifetimes

#Overview

name: r.RDG.Debug.ExtendResourceLifetimes

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RDG.Debug.ExtendResourceLifetimes is to debug potential issues related to transient aliasing in the Render Dependency Graph (RDG) system of Unreal Engine 5. It extends the lifetimes of resources within the render graph to prevent memory overlap between resources.

This setting variable is primarily used by the rendering system, specifically within the Render Dependency Graph (RDG) subsystem of Unreal Engine 5. It’s part of the RenderCore module, as evident from its location in the RenderGraphPrivate.cpp and RenderGraphPrivate.h files.

The value of this variable is set through a console variable (cvar) system. It can be enabled or disabled via the console or command line arguments. By default, it’s set to 0 (disabled), but it can be set to 1 to enable the feature.

This variable interacts closely with GRDGDebugExtendResourceLifetimes, which is its associated C++ variable. They share the same value and purpose.

Developers should be aware that enabling this variable can impact performance, as it prevents memory reuse between resources. It should primarily be used for debugging purposes when suspecting issues related to transient aliasing in the render graph.

Best practices for using this variable include:

  1. Only enable it when debugging specific rendering issues related to resource aliasing.
  2. Use it in conjunction with r.RDG.Debug.ResourceFilter to narrow down the affected resources if needed.
  3. Remember to disable it after debugging to avoid unnecessary performance overhead.

Regarding the associated variable GRDGDebugExtendResourceLifetimes:

The purpose of GRDGDebugExtendResourceLifetimes is to serve as the C++ representation of the r.RDG.Debug.ExtendResourceLifetimes console variable within the engine’s code.

This variable is used directly in the RenderCore module’s implementation of the Render Dependency Graph system. It’s checked in various parts of the RDG code to determine whether to extend resource lifetimes.

The value of this variable is set in multiple ways:

  1. It’s initialized to 0 by default.
  2. It can be set through the console variable system.
  3. It can be set via a command line argument “rdgdebugextendresourcelifetimes”.

This variable is primarily used in conditional statements to enable or disable the resource lifetime extension feature in the RDG system.

Developers should be aware that this variable is used in performance-critical rendering code, so its state can have a significant impact on rendering performance and behavior.

Best practices for using this variable include:

  1. Avoid modifying it directly in C++ code; instead, use the console variable system.
  2. Be cautious when enabling it in production builds, as it can affect performance.
  3. Use it as a temporary debugging tool rather than a permanent solution to rendering issues.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphPrivate.cpp:47

Scope: file

Source code excerpt:

int32 GRDGDebugExtendResourceLifetimes = 0;
FAutoConsoleVariableRef CVarRDGDebugExtendResourceLifetimes(
	TEXT("r.RDG.Debug.ExtendResourceLifetimes"),
	GRDGDebugExtendResourceLifetimes,
	TEXT("Extends the resource lifetimes of resources (or a specific resource filter specified by r.RDG.Debug.ResourceFilter) ")
	TEXT("so that they cannot overlap memory with any other resource within the graph. Useful to debug if transient aliasing is causing issues.\n")
	TEXT(" 0: disabled (default);\n")
	TEXT(" 1: enabled;\n"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphPrivate.cpp:45

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

int32 GRDGDebugExtendResourceLifetimes = 0;
FAutoConsoleVariableRef CVarRDGDebugExtendResourceLifetimes(
	TEXT("r.RDG.Debug.ExtendResourceLifetimes"),
	GRDGDebugExtendResourceLifetimes,
	TEXT("Extends the resource lifetimes of resources (or a specific resource filter specified by r.RDG.Debug.ResourceFilter) ")
	TEXT("so that they cannot overlap memory with any other resource within the graph. Useful to debug if transient aliasing is causing issues.\n")
	TEXT(" 0: disabled (default);\n")
	TEXT(" 1: enabled;\n"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphPrivate.cpp:534

Scope (from outer to inner):

file
function     void InitRenderGraph

Source code excerpt:

	if (FParse::Param(FCommandLine::Get(), TEXT("rdgdebugextendresourcelifetimes")))
	{
		GRDGDebugExtendResourceLifetimes = 1;
	}

	if (FParse::Param(FCommandLine::Get(), TEXT("rdgtransitionlog")))
	{
		// Set to -1 to specify infinite number of frames.
		GRDGTransitionLog = -1;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphPrivate.h:34

Scope: file

Source code excerpt:

extern int32 GRDGDebug;
extern int32 GRDGDebugFlushGPU;
extern int32 GRDGDebugExtendResourceLifetimes;
extern int32 GRDGDebugDisableTransientResources;
extern int32 GRDGBreakpoint;
extern int32 GRDGTransitionLog;
extern int32 GRDGImmediateMode;
extern int32 GRDGOverlapUAVs;
extern bool  GRDGAllowRHIAccess;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphPrivate.h:97

Scope: file

Source code excerpt:

const int32 GRDGDebug = 0;
const int32 GRDGDebugFlushGPU = 0;
const int32 GRDGDebugExtendResourceLifetimes = 0;
const int32 GRDGDebugDisableTransientResources = 0;
const int32 GRDGBreakpoint = 0;
const int32 GRDGTransitionLog = 0;
const int32 GRDGImmediateMode = 0;
const int32 GRDGOverlapUAVs = 1;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphPrivate.h:267

Scope (from outer to inner):

file
function     inline void EnumerateExtendedLifetimeResources

Source code excerpt:

{
#if RDG_ENABLE_DEBUG
	if (GRDGDebugExtendResourceLifetimes)
	{
		for (auto Handle = Registry.Begin(); Handle != Registry.End(); ++Handle)
		{
			auto* Resource = Registry[Handle];

			if (IsDebugAllowedForResource(Resource->Name) && !Resource->IsCulled())