r.InstanceCulling.OcclusionCull

r.InstanceCulling.OcclusionCull

#Overview

name: r.InstanceCulling.OcclusionCull

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

• type: Var
• help: Whether to do per instance occlusion culling for GPU instance culling.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.InstanceCulling.OcclusionCull is to control whether per-instance occlusion culling is performed for GPU instance culling in Unreal Engine 5’s rendering system.

This setting variable is primarily used by the Renderer module, specifically within the instance culling subsystem. It affects the GPU-based culling process for rendering instances of objects in the scene.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning it’s disabled by default.

The associated variable CVarOcclusionCullInstances directly interacts with r.InstanceCulling.OcclusionCull. They share the same value and purpose.

Developers should be aware that:

1. This setting is marked as ECVF_RenderThreadSafe and ECVF_Preview, indicating it’s safe to change on the render thread but may not be fully stable.
2. Enabling this feature (by setting it to a non-zero value) will activate per-instance occlusion culling, which can improve performance but may also introduce additional computational overhead.
3. The effect of this variable is dependent on GPU culling being enabled (IsGPUCullingEnabled() must return true).

Best practices when using this variable include:

1. Test thoroughly when enabling this feature, as it may affect rendering performance and visual output.
2. Consider the trade-off between potential performance gains from occlusion culling and the additional computational cost.
3. Use in conjunction with other instance culling settings for optimal results.

Regarding the associated variable CVarOcclusionCullInstances:

• It serves the same purpose as r.InstanceCulling.OcclusionCull.
• It’s used internally by the engine to check if occlusion culling for instances is enabled.
• The IsOcclusionCullingEnabled() function in FInstanceCullingContext uses this variable to determine if occlusion culling should be performed.
• Developers should not need to interact with this variable directly, as it’s managed internally by the engine.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:119, section: [/Script/Engine.RendererSettings]

• INI Section: /Script/Engine.RendererSettings
• Raw value: 0
• Is Array: False

#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:26

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarOcclusionCullInstances(
	TEXT("r.InstanceCulling.OcclusionCull"),
	0,
	TEXT("Whether to do per instance occlusion culling for GPU instance culling."),
	ECVF_RenderThreadSafe | ECVF_Preview);

static int32 GOcclusionForceInstanceCulling = 0;
static FAutoConsoleVariableRef CVarOcclusionForceInstanceCulling(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Public/InstanceCulling/InstanceCullingContext.h:109

Scope: file

Source code excerpt:

	/**
	 * Create an instance culling context to process draw commands that can be culled using GPU-Scene.
	 * @param InPrevHZB if non-null enables HZB-occlusion culling for the context (if r.InstanceCulling.OcclusionCull is enabled),
	 *                  NOTE: only one PrevHZB target is allowed accross all passes currently, so either must be atlased or otherwise the same.
	 */
	RENDERER_API FInstanceCullingContext(
		FName PassName,
		EShaderPlatform ShaderPlatform,
		FInstanceCullingManager* InInstanceCullingManager, 
		TArrayView<const int32> InViewIds, 
		const TRefCountPtr<IPooledRenderTarget>& InPrevHZB,
		EInstanceCullingMode InInstanceCullingMode = EInstanceCullingMode::Normal,
		EInstanceCullingFlags InFlags = EInstanceCullingFlags::None,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOcclusionCullInstances(
	TEXT("r.InstanceCulling.OcclusionCull"),
	0,
	TEXT("Whether to do per instance occlusion culling for GPU instance culling."),
	ECVF_RenderThreadSafe | ECVF_Preview);

static int32 GOcclusionForceInstanceCulling = 0;

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

Scope (from outer to inner):

file
function     bool FInstanceCullingContext::IsOcclusionCullingEnabled

Source code excerpt:

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

FInstanceCullingContext::~FInstanceCullingContext()
{
	for (auto& LoadBalancer : LoadBalancers)
	{