r.CullInstances

r.CullInstances

#Overview

name: r.CullInstances

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.CullInstances is to control instance culling in the rendering system of Unreal Engine 5. This setting variable is used to enable or disable GPU-based instance culling, which helps optimize rendering performance by reducing the number of instances that need to be processed.

The Unreal Engine subsystem that relies on this setting variable is primarily the Renderer module, specifically the instance culling system. This can be seen from the file location “Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingContext.cpp”.

The value of this variable is set through a console variable (CVar) named CVarCullInstances. It is initialized with a default value of 1, meaning instance culling is enabled by default. The value can be changed at runtime using console commands.

This variable interacts closely with another variable named CVarOcclusionCullInstances, which controls occlusion culling for instances. The r.CullInstances variable acts as a master switch for instance culling, while CVarOcclusionCullInstances provides more specific control over occlusion culling.

Developers must be aware that this variable significantly impacts rendering performance and visual output. Disabling instance culling (setting to 0) may increase rendering load but could be useful for debugging or in specific scenarios where culling causes issues.

Best practices when using this variable include:

  1. Generally leave it enabled (default value of 1) for optimal performance.
  2. Use it in conjunction with profiling tools to understand its impact on your specific scene.
  3. Consider temporarily disabling it (setting to 0) if you suspect culling-related rendering issues.

Regarding the associated variable CVarCullInstances:

The purpose of CVarCullInstances is to provide a programmatic way to access and modify the r.CullInstances setting. It’s an instance of TAutoConsoleVariable, which allows the engine to expose this setting as a console variable.

This variable is used throughout the instance culling system to check whether culling should be performed. For example, in the IsGPUCullingEnabled() function, it’s used to determine if GPU culling is active.

The value of CVarCullInstances is set when the console variable is initialized, but it can be changed at runtime through console commands.

Developers should be aware that changes to CVarCullInstances will immediately affect the rendering system’s behavior. It’s thread-safe and can be accessed from different threads (as seen in the GetValueOnAnyThread() and GetValueOnRenderThread() calls).

Best practices for using CVarCullInstances include:

  1. Use the provided accessor methods (GetValueOnAnyThread(), GetValueOnRenderThread()) rather than accessing the value directly.
  2. Be cautious when changing this value during runtime, as it can have significant performance implications.
  3. Consider using this variable for debugging or performance testing scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingContext.cpp:20

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarCullInstances(
	TEXT("r.CullInstances"),
	1,
	TEXT("CullInstances."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOcclusionCullInstances(
	TEXT("r.InstanceCulling.OcclusionCull"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingContext.cpp:19

Scope: file

Source code excerpt:

#include "MeshDrawCommandStats.h"

static TAutoConsoleVariable<int32> CVarCullInstances(
	TEXT("r.CullInstances"),
	1,
	TEXT("CullInstances."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOcclusionCullInstances(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingContext.cpp:195

Scope (from outer to inner):

file
function     bool FInstanceCullingContext::IsGPUCullingEnabled

Source code excerpt:

bool FInstanceCullingContext::IsGPUCullingEnabled()
{
	return CVarCullInstances.GetValueOnAnyThread() != 0;
}

bool FInstanceCullingContext::IsOcclusionCullingEnabled()
{
	return IsGPUCullingEnabled() && CVarOcclusionCullInstances.GetValueOnAnyThread() != 0;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingContext.cpp:742

Scope (from outer to inner):

file
function     void FInstanceCullingContext::BuildRenderingCommandsInternal

Source code excerpt:


	// If there is no manager, then there is no data on culling, so set flag to skip that and ignore buffers.
	const bool bCullInstances = InstanceCullingManager != nullptr && CVarCullInstances.GetValueOnRenderThread() != 0;
	const bool bAllowWPODisable = InstanceCullingManager != nullptr;

	RDG_EVENT_SCOPE(GraphBuilder, "BuildRenderingCommands(Culling=%s)", bCullInstances ? TEXT("On") : TEXT("Off"));
	RDG_GPU_STAT_SCOPE(GraphBuilder, BuildRenderingCommands);

	const bool bOrderPreservationEnabled = IsInstanceOrderPreservationEnabled();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingContext.cpp:1080

Scope (from outer to inner):

file
function     FInstanceCullingDeferredContext *FInstanceCullingContext::CreateDeferredContext

Source code excerpt:

	FInstanceCullingDeferredContext* DeferredContext = GraphBuilder.AllocObject<FInstanceCullingDeferredContext>(ShaderPlatform, &InstanceCullingManager);

	const bool bCullInstances = CVarCullInstances.GetValueOnRenderThread() != 0;
	const bool bAllowWPODisable = true;

	RDG_EVENT_SCOPE(GraphBuilder, "BuildRenderingCommandsDeferred(Culling=%s)", bCullInstances ? TEXT("On") : TEXT("Off"));
	RDG_GPU_STAT_SCOPE(GraphBuilder, BuildRenderingCommandsDeferred);

	TStaticArray<FBuildInstanceIdBufferAndCommandsFromPrimitiveIdsCs::FParameters*, static_cast<uint32>(EBatchProcessingMode::Num)> PassParameters;