r.SceneCulling.Precomputed

r.SceneCulling.Precomputed

#Overview

name: r.SceneCulling.Precomputed

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

• type: Var
• help: Enable/Disable precomputed spatial hashes for scene culling.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.SceneCulling.Precomputed is to enable or disable the use of precomputed spatial hashes for scene culling in Unreal Engine 5. This setting variable is primarily related to the rendering system, specifically the scene culling subsystem.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the SceneCulling component. This can be seen from the file paths where the variable is referenced: ‘Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp’ and ‘Engine/Source/Runtime/Engine/Private/InstancedStaticMesh/ISMInstanceDataManager.cpp’.

The value of this variable is set through the console variable system. It is defined as a TAutoConsoleVariable with a default value of 0, meaning it’s disabled by default. Developers can change this value at runtime using console commands.

This variable interacts with another console variable named ‘r.SceneCulling’. Both need to be non-zero for the precomputed scene culling to be active, as seen in the ShouldUsePrecomputed() function.

Developers must be aware that this variable is marked as ECVF_RenderThreadSafe and ECVF_ReadOnly. This means it’s safe to read from the render thread, but it cannot be modified after engine initialization.

Best practices when using this variable include:

1. Only enable it if you need the performance boost from precomputed spatial hashes.
2. Be aware of the memory trade-off: precomputed spatial hashes use more memory but can improve culling performance.
3. Test thoroughly with both static and dynamic objects in your scene to ensure it doesn’t negatively impact visual quality or performance.

Regarding the associated variable CVarSceneCullingPrecomputed:

The purpose of CVarSceneCullingPrecomputed is to provide a C++ accessible interface to the r.SceneCulling.Precomputed console variable. It serves the same purpose as r.SceneCulling.Precomputed but is used directly in the C++ code.

This variable is used in the Renderer module, specifically in the SceneCulling component. It’s accessed in the FSceneCullingBuilder class to determine whether precomputed culling should be used.

The value of CVarSceneCullingPrecomputed is set when r.SceneCulling.Precomputed is set, as they share the same underlying value.

CVarSceneCullingPrecomputed interacts with CVarTreatDynamicInstancedAsUncullable, another console variable that affects how dynamic instanced primitives are treated in the culling process.

Developers should be aware that this variable is checked on the render thread (GetValueOnAnyThread() is called in a render thread context).

Best practices for using CVarSceneCullingPrecomputed include:

1. Use it for render-thread specific logic related to scene culling.
2. Be cautious when changing its value, as it can have significant impacts on rendering performance and visual output.
3. Always consider the interaction with other culling-related variables when modifying or relying on its value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:116

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarSceneCullingPrecomputed(
	TEXT("r.SceneCulling.Precomputed"), 
	0, 
	TEXT("Enable/Disable precomputed spatial hashes for scene culling."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarSceneCullingAsyncUpdate(
	TEXT("r.SceneCulling.Async.Update"), 

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh/ISMInstanceDataManager.cpp:1068

Scope (from outer to inner):

file
function     static bool ShouldUsePrecomputed

Source code excerpt:

static bool ShouldUsePrecomputed()
{
	static const auto CVarPrecomputed = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.SceneCulling.Precomputed"));
	static const auto CVarSceneCull = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.SceneCulling"));

	return CVarSceneCull && CVarSceneCull->GetValueOnAnyThread() != 0
		&& CVarPrecomputed && CVarPrecomputed->GetValueOnAnyThread() != 0;
}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:115

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSceneCullingPrecomputed(
	TEXT("r.SceneCulling.Precomputed"), 
	0, 
	TEXT("Enable/Disable precomputed spatial hashes for scene culling."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarSceneCullingAsyncUpdate(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:974

Scope (from outer to inner):

file
class        class FSceneCullingBuilder
function     FSceneCullingBuilder

Source code excerpt:

		SceneCulling.PrimitiveStates.SetNum(SceneCulling.Scene.GetMaxPersistentPrimitiveIndex());

		bUsePrecomputed = CVarSceneCullingPrecomputed.GetValueOnAnyThread() != 0;

		if (CVarTreatDynamicInstancedAsUncullable.GetValueOnRenderThread() != 0)
		{
			// Flip dynamic stuff into the uncullabe bucket. 
			DynamicInstancedPrimitiveState = FPrimitiveState::UnCullable;
		}