r.Shadow.OcclusionCullCascadedShadowMaps

r.Shadow.OcclusionCullCascadedShadowMaps

#Overview

name: r.Shadow.OcclusionCullCascadedShadowMaps

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

• type: Var
• help: Whether to use occlusion culling on cascaded shadow maps. Disabled by default because rapid view changes reveal new regions too quickly for latent occlusion queries to work with.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.OcclusionCullCascadedShadowMaps is to control whether occlusion culling is used on cascaded shadow maps in the Unreal Engine 5 rendering system.

This setting variable is primarily used by the rendering subsystem, specifically in the shadow rendering and occlusion culling modules. The variable is defined and used in the SceneOcclusion.cpp file, which is part of the Renderer module.

The value of this variable is set through the Unreal Engine console system. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

The associated variable GOcclusionCullCascadedShadowMaps directly interacts with r.Shadow.OcclusionCullCascadedShadowMaps. They share the same value, with GOcclusionCullCascadedShadowMaps being the actual int32 variable used in the code.

Developers must be aware that this feature is disabled by default. The reason for this, as stated in the code comments, is that “rapid view changes reveal new regions too quickly for latent occlusion queries to work with.” This means that enabling this feature might cause visual artifacts or performance issues in scenarios with fast-moving cameras or dynamic environments.

Best practices when using this variable include:

1. Testing thoroughly in various scenarios, especially with fast-moving cameras or dynamic lighting conditions.
2. Monitoring performance impact, as occlusion culling can have both positive and negative effects on performance depending on the scene complexity.
3. Considering the trade-off between potential performance gains and the risk of visual artifacts.

Regarding the associated variable GOcclusionCullCascadedShadowMaps:

The purpose of GOcclusionCullCascadedShadowMaps is to store the actual value of the r.Shadow.OcclusionCullCascadedShadowMaps setting within the C++ code.

This variable is used directly in the rendering code to determine whether to perform occlusion culling on cascaded shadow maps. It’s checked in the AllocateOcclusionTests function to decide whether to allocate occlusion queries for shadow cascades beyond the first one.

The value of GOcclusionCullCascadedShadowMaps is set by the console variable system when r.Shadow.OcclusionCullCascadedShadowMaps is modified.

Developers should be aware that this variable is of type int32, but it’s used as a boolean check in the code. Any non-zero value will enable the feature.

Best practices include using this variable consistently throughout the codebase when checking for this feature, rather than directly accessing the console variable, to ensure consistent behavior and easier maintenance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:55

Scope: file

Source code excerpt:

int32 GOcclusionCullCascadedShadowMaps = 0;
FAutoConsoleVariableRef CVarOcclusionCullCascadedShadowMaps(
	TEXT("r.Shadow.OcclusionCullCascadedShadowMaps"),
	GOcclusionCullCascadedShadowMaps,
	TEXT("Whether to use occlusion culling on cascaded shadow maps.  Disabled by default because rapid view changes reveal new regions too quickly for latent occlusion queries to work with."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

static TAutoConsoleVariable<bool> CVarMobileEnableOcclusionExtraFrame(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:53

Scope: file

Source code excerpt:

	);

int32 GOcclusionCullCascadedShadowMaps = 0;
FAutoConsoleVariableRef CVarOcclusionCullCascadedShadowMaps(
	TEXT("r.Shadow.OcclusionCullCascadedShadowMaps"),
	GOcclusionCullCascadedShadowMaps,
	TEXT("Whether to use occlusion culling on cascaded shadow maps.  Disabled by default because rapid view changes reveal new regions too quickly for latent occlusion queries to work with."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

static TAutoConsoleVariable<bool> CVarMobileEnableOcclusionExtraFrame(
	TEXT("r.Mobile.EnableOcclusionExtraFrame"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:1136

Scope (from outer to inner):

file
function     static void AllocateOcclusionTests

Source code excerpt:

						{
							// Don't query the first cascade, it is always visible
							if (GOcclusionCullCascadedShadowMaps && ProjectedShadowInfo.CascadeSettings.ShadowSplitIndex > 0)
							{
								FRHIRenderQuery* ShadowOcclusionQuery;
								if (AllocateProjectedShadowOcclusionQuery(View, ProjectedShadowInfo, NumBufferedFrames, SOQ_None, ShadowOcclusionQuery))
								{
									ViewQuery.CSMQueryInfos.Add(&ProjectedShadowInfo);
									ViewQuery.CSMQueries.Add(ShadowOcclusionQuery);