r.RDG.Events

r.RDG.Events

#Overview

name: r.RDG.Events

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RDG.Events is to control how Render Dependency Graph (RDG) events are emitted in Unreal Engine’s rendering system. This setting variable is primarily used for debugging and profiling purposes within the rendering pipeline.

The Unreal Engine subsystem that relies on this setting variable is the Render Dependency Graph (RDG) system, which is part of the rendering core. It’s used in the RenderCore module, specifically in the RDG-related components.

The value of this variable is set through a console variable (CVar) named “r.RDG.Events”. It can be changed at runtime using console commands or through configuration files.

The associated variable GRDGEvents interacts directly with r.RDG.Events, sharing the same value. This internal variable is used throughout the RDG system to determine the event emission behavior.

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

  1. It has three possible values (0, 1, 2), each with different behaviors:

    • 0: RDG events are turned off
    • 1 (default): RDG events are enabled, and RDG_EVENT_SCOPE_FINAL is respected
    • 2: All RDG events are enabled, ignoring RDG_EVENT_SCOPE_FINAL

  2. This variable affects performance and debugging capabilities. Enabling more events (value 2) can provide more detailed information but may impact performance.

  3. It’s render thread safe, meaning it can be changed without causing thread-safety issues in the rendering system.

Best practices when using this variable include:

  1. Use the default value (1) for normal development and testing scenarios.
  2. Set it to 0 in shipping builds or when maximum performance is required.
  3. Use value 2 when detailed debugging of the rendering pipeline is necessary, but be aware of potential performance implications.
  4. Consider using this in conjunction with other RDG debugging tools and variables for comprehensive rendering pipeline analysis.

Regarding the associated variable GRDGEvents:

The purpose of GRDGEvents is to internally represent the state of r.RDG.Events within the engine’s C++ code. It’s used to control the behavior of RDG event emission in various parts of the rendering code.

This variable is primarily used in the RenderCore module, specifically in RDG-related functionality.

The value of GRDGEvents is set by the console variable r.RDG.Events, ensuring they always have the same value.

GRDGEvents interacts with other variables and systems, such as GRDGEmitDrawEvents_RenderThread and GRDGDebug, to determine whether RDG events should be emitted.

Developers should be aware that GRDGEvents is used in conditional statements to control the flow of RDG event-related code. Its value affects how event scopes are handled and whether certain debug features are enabled.

Best practices for GRDGEvents mirror those of r.RDG.Events, as they are directly linked. Developers should primarily interact with r.RDG.Events rather than GRDGEvents directly, as the latter is an internal implementation detail.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GRDGEvents = 1;
FAutoConsoleVariableRef CVarRDGEvents(
	TEXT("r.RDG.Events"),
	GRDGEvents,
	TEXT("Controls how RDG events are emitted.\n")
	TEXT(" 0: off;\n")
	TEXT(" 1: events are enabled and RDG_EVENT_SCOPE_FINAL is respected; (default)\n")
	TEXT(" 2: all events are enabled (RDG_EVENT_SCOPE_FINAL is ignored);"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphEvent.cpp:512

Scope (from outer to inner):

file
function     bool GetEmitRDGEvents

Source code excerpt:

	bRDGChannelEnabled = UE_TRACE_CHANNELEXPR_IS_ENABLED(RDGChannel);
#endif // RDG_ENABLE_TRACE
	return GRDGEvents != 0 && (GRDGEmitDrawEvents_RenderThread != 0 || GRDGDebug != 0 || bRDGChannelEnabled != 0);
#else
	return false;
#endif
}

#if RDG_EVENTS == RDG_EVENTS_STRING_COPY

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphEvent.cpp:572

Scope (from outer to inner):

file
function     FRDGEventScopeGuard::FRDGEventScopeGuard

Source code excerpt:

	if (bCondition)
	{
		if (GRDGEvents == 2)
		{
			EnumRemoveFlags(InFlags, ERDGEventScopeFlags::Final);
		}

		GraphBuilder.GPUScopeStacks.bFinalEventScopeActive = (EnumHasAnyFlags(InFlags, ERDGEventScopeFlags::Final));
		GraphBuilder.GPUScopeStacks.BeginEventScope(MoveTemp(ScopeName), GraphBuilder.RHICmdList.GetGPUMask(), InFlags);

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

Scope: file

Source code excerpt:


#if RDG_GPU_DEBUG_SCOPES
int32 GRDGEvents = 1;
FAutoConsoleVariableRef CVarRDGEvents(
	TEXT("r.RDG.Events"),
	GRDGEvents,
	TEXT("Controls how RDG events are emitted.\n")
	TEXT(" 0: off;\n")
	TEXT(" 1: events are enabled and RDG_EVENT_SCOPE_FINAL is respected; (default)\n")
	TEXT(" 2: all events are enabled (RDG_EVENT_SCOPE_FINAL is ignored);"),
	ECVF_RenderThreadSafe);
#endif

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

Scope: file

Source code excerpt:


#if RDG_GPU_DEBUG_SCOPES
extern int32 GRDGEvents;
#endif

#if RDG_EVENTS != RDG_EVENTS_NONE
extern int32 GRDGEmitDrawEvents_RenderThread;
#endif