r.RDG.CullPasses

r.RDG.CullPasses

#Overview

name: r.RDG.CullPasses

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.CullPasses is to control the culling of render passes with unused outputs in the Render Dependency Graph (RDG) system of Unreal Engine 5. This setting is primarily used for optimizing the rendering pipeline.

This setting variable is utilized by the Render Core subsystem of Unreal Engine 5, specifically within the Render Dependency Graph (RDG) module. The RDG is a crucial part of UE5’s rendering system that manages dependencies between render passes and resources.

The value of this variable is set through a console variable (CVar) named “r.RDG.CullPasses”. It’s initialized with a default value of 1 (enabled) but can be changed at runtime or through command-line arguments.

The associated variable GRDGCullPasses interacts directly with r.RDG.CullPasses, sharing the same value. This internal variable is used throughout the RDG implementation to determine whether pass culling should be performed.

Developers should be aware that:

  1. When enabled (value > 0), the RDG will attempt to cull render passes that have unused outputs, potentially improving performance.
  2. Certain passes may be marked as “NeverCull” or have external outputs, preventing them from being culled even when this setting is enabled.
  3. Disabling this feature (setting to 0) may be useful for debugging or in scenarios where all passes need to be executed regardless of their output usage.

Best practices when using this variable include:

  1. Generally, leave it enabled (default value of 1) for optimal performance in production builds.
  2. If experiencing unexpected visual artifacts or missing render elements, temporarily disabling this feature can help isolate whether pass culling is the cause.
  3. When developing new render passes, ensure they are properly integrated with the RDG system to benefit from this optimization.

Regarding the associated variable GRDGCullPasses: The purpose of GRDGCullPasses is to serve as an internal representation of the r.RDG.CullPasses setting. It’s used directly in the C++ code to control the pass culling logic within the RDG system.

This variable is used in several key locations within the RDG implementation:

  1. In the FRDGBuilder::Compile() function, where it determines whether pass culling should be performed during graph compilation.
  2. In the FRDGBuilder::SetupPassDependencies() function, where it influences how dependencies between passes are established.

The value of GRDGCullPasses is set based on the r.RDG.CullPasses CVar, and it can also be modified through command-line arguments at engine startup.

Developers should be aware that modifying GRDGCullPasses directly is not recommended. Instead, they should use the r.RDG.CullPasses console variable to control this behavior.

Best practices for GRDGCullPasses align with those of r.RDG.CullPasses, as they represent the same setting within different contexts of the engine code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GRDGCullPasses = 1;
FAutoConsoleVariableRef CVarRDGCullPasses(
	TEXT("r.RDG.CullPasses"),
	GRDGCullPasses,
	TEXT("The graph will cull passes with unused outputs.\n")
	TEXT(" 0:off;\n")
	TEXT(" 1:on(default);\n"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphBuilder.cpp:1211

Scope (from outer to inner):

file
function     void FRDGBuilder::Compile

Source code excerpt:

	TransitionCreateQueue.Reserve(CompilePassCount);

	const bool bCullPasses = GRDGCullPasses > 0;

	if (bCullPasses || AsyncComputePassCount > 0)
	{
		SCOPED_NAMED_EVENT(PassDependencies, FColor::Emerald);

		if (!ParallelSetup.bEnabled)

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderGraphBuilder.cpp:2123

Scope (from outer to inner):

file
function     void FRDGBuilder::SetupPassDependencies

Source code excerpt:

	}

	const bool bCullPasses = GRDGCullPasses > 0;
	Pass->bCulled = bCullPasses;

	if (bCullPasses && (bIsCullRootProducer || Pass->bHasExternalOutputs || EnumHasAnyFlags(Pass->Flags, ERDGPassFlags::NeverCull)))
	{
		CullPassStack.Emplace(Pass);

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

Scope: file

Source code excerpt:

}));

int32 GRDGCullPasses = 1;
FAutoConsoleVariableRef CVarRDGCullPasses(
	TEXT("r.RDG.CullPasses"),
	GRDGCullPasses,
	TEXT("The graph will cull passes with unused outputs.\n")
	TEXT(" 0:off;\n")
	TEXT(" 1:on(default);\n"),
	ECVF_RenderThreadSafe);

int32 GRDGMergeRenderPasses = 1;

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

Scope (from outer to inner):

file
function     void InitRenderGraph

Source code excerpt:

	if (FParse::Value(FCommandLine::Get(), TEXT("rdgcullpasses="), CullPassesValue))
	{
		GRDGCullPasses = CullPassesValue;
	}

#if RDG_ENABLE_PARALLEL_TASKS
	int32 ParallelSetupValue = 0;
	if (FParse::Value(FCommandLine::Get(), TEXT("rdgparallelsetup="), ParallelSetupValue))
	{

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

Scope: file

Source code excerpt:


extern int32 GRDGAsyncCompute;
extern int32 GRDGCullPasses;
extern int32 GRDGMergeRenderPasses;
extern int32 GRDGTransientAllocator;
extern int32 GRDGTransientExtractedResources;
extern int32 GRDGTransientIndirectArgBuffers;

#if RDG_ENABLE_PARALLEL_TASKS