r.Shadow.UseOctreeForCulling

r.Shadow.UseOctreeForCulling

#Overview

name: r.Shadow.UseOctreeForCulling

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.UseOctreeForCulling is to control whether the primitive octree is used for shadow subject culling in the rendering system. This setting variable is part of Unreal Engine’s shadow rendering optimization system.

The Unreal Engine’s Renderer module relies on this setting variable, specifically in the shadow setup process. This can be seen from the file path “Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp” where the variable is defined and used.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 1 (enabled) and can be changed at runtime through console commands or configuration files.

This variable interacts directly with its associated C++ variable GUseOctreeForShadowCulling. They share the same value, and GUseOctreeForShadowCulling is used in the actual code logic to determine whether to use the octree for shadow culling.

Developers must be aware that enabling this feature (which is the default) can improve performance by culling large groups of primitives at once, but it may also introduce cache misses when walking the octree data structure. This trade-off should be considered based on the specific needs of the project and the target hardware.

Best practices when using this variable include:

  1. Profiling the game with this feature both enabled and disabled to determine which setting provides better performance for your specific use case.
  2. Consider disabling it if your game has a large number of small, dispersed objects that might not benefit from octree culling.
  3. Be aware that changing this setting may affect shadow quality and performance, so it should be tested thoroughly across different scenes and hardware configurations.

Regarding the associated variable GUseOctreeForShadowCulling:

The purpose of GUseOctreeForShadowCulling is to serve as the C++ representation of the r.Shadow.UseOctreeForCulling console variable. It’s used directly in the rendering code to determine whether to use the octree for shadow culling.

This variable is used in the Renderer module, specifically in the shadow setup process. It’s checked in the AnyThreadTask function, which is likely part of the shadow rendering pipeline.

The value of GUseOctreeForShadowCulling is set by the console variable system when r.Shadow.UseOctreeForCulling is modified.

Developers should be aware that this variable directly affects the shadow culling logic in the rendering pipeline. Changing its value at runtime will immediately affect how shadows are processed.

Best practices for using GUseOctreeForShadowCulling include:

  1. Avoid modifying this variable directly in C++ code. Instead, use the console variable r.Shadow.UseOctreeForCulling to ensure consistency.
  2. When profiling or debugging shadow rendering issues, check the value of this variable to understand whether octree culling is currently in use.
  3. Consider exposing r.Shadow.UseOctreeForCulling as a user-configurable setting in graphics options if shadow performance is a critical concern in your game.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:294

Scope: file

Source code excerpt:

int32 GUseOctreeForShadowCulling = 1;
FAutoConsoleVariableRef CVarUseOctreeForShadowCulling(
	TEXT("r.Shadow.UseOctreeForCulling"),
	GUseOctreeForShadowCulling,
	TEXT("Whether to use the primitive octree for shadow subject culling.  The octree culls large groups of primitives at a time, but introduces cache misses walking the data structure."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

static TAutoConsoleVariable<int32> CVarAlwaysAllocateMaxResolutionAtlases(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:292

Scope: file

Source code excerpt:

	);

int32 GUseOctreeForShadowCulling = 1;
FAutoConsoleVariableRef CVarUseOctreeForShadowCulling(
	TEXT("r.Shadow.UseOctreeForCulling"),
	GUseOctreeForShadowCulling,
	TEXT("Whether to use the primitive octree for shadow subject culling.  The octree culls large groups of primitives at a time, but introduces cache misses walking the data structure."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

static TAutoConsoleVariable<int32> CVarAlwaysAllocateMaxResolutionAtlases(
	TEXT("r.Shadow.AlwaysAllocateMaxResolutionAtlases"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:5160

Scope (from outer to inner):

file
function     void AnyThreadTask

Source code excerpt:

		TaskData.GatherStats.AddDefaulted(TaskData.ViewDependentWholeSceneShadows.Num());

		if (GUseOctreeForShadowCulling)
		{
			QUICK_SCOPE_CYCLE_COUNTER(STAT_ShadowSceneOctreeTraversal);

			TaskData.Packets.Reserve(100);

			// Find primitives that are in a shadow frustum in the octree.