foliage.MaxOcclusionQueriesPerComponent

foliage.MaxOcclusionQueriesPerComponent

#Overview

name: foliage.MaxOcclusionQueriesPerComponent

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

• type: Var
• help: Controls the granularity of occlusion culling. 16-128 is a reasonable range.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of foliage.MaxOcclusionQueriesPerComponent is to control the granularity of occlusion culling for foliage components in Unreal Engine 5. This setting variable is primarily used in the rendering system, specifically for optimizing the rendering of hierarchical instanced static meshes, which are commonly used for foliage in game environments.

This setting variable is utilized within the Engine module, specifically in the HierarchicalInstancedStaticMesh component. Based on the callsites, it’s evident that this variable is crucial for the occlusion culling system of instanced foliage.

The value of this variable is set as a console variable (CVar) with a default value of 16. It can be modified at runtime through the console or configuration files.

The associated variable CVarMaxOcclusionQueriesPerComponent directly interacts with foliage.MaxOcclusionQueriesPerComponent. They share the same value and purpose.

Developers must be aware that this variable affects the trade-off between culling accuracy and CPU performance. A higher value will result in more granular occlusion culling, potentially improving visual accuracy but at the cost of increased CPU usage.

Best practices when using this variable include:

1. Keeping the value within the recommended range of 16-128, as mentioned in the comment.
2. Adjusting the value based on the specific needs of the project, considering the balance between visual fidelity and performance.
3. Testing different values to find the optimal setting for the particular scene and target hardware.

Regarding the associated variable CVarMaxOcclusionQueriesPerComponent:

The purpose of CVarMaxOcclusionQueriesPerComponent is identical to foliage.MaxOcclusionQueriesPerComponent, as they share the same value and are used interchangeably in the code.

This variable is used within the Engine module, specifically in the HierarchicalInstancedStaticMesh component’s occlusion culling system.

The value is set when the CVar is initialized, with a default value of 16. It can be accessed and potentially modified at runtime using the GetValueOnAnyThread() method.

CVarMaxOcclusionQueriesPerComponent interacts directly with foliage.MaxOcclusionQueriesPerComponent and is also used in conjunction with other variables like CVarMinOcclusionQueriesPerComponent and CVarMinInstancesPerOcclusionQuery to determine the optimal number of occlusion queries for a given component.

Developers should be aware that this variable is used in performance-critical code paths and can significantly impact rendering performance and visual quality.

Best practices for using CVarMaxOcclusionQueriesPerComponent are the same as those for foliage.MaxOcclusionQueriesPerComponent, with an additional note to consider its interaction with other related variables when fine-tuning occlusion culling behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:112

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarMaxOcclusionQueriesPerComponent(
	TEXT("foliage.MaxOcclusionQueriesPerComponent"),
	16,
	TEXT("Controls the granularity of occlusion culling. 16-128 is a reasonable range."));

static TAutoConsoleVariable<int32> CVarMinOcclusionQueriesPerComponent(
	TEXT("foliage.MinOcclusionQueriesPerComponent"),
	6,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:111

Scope: file

Source code excerpt:

	TEXT("Controls the accuracy between culling and LOD accuracy and culling and CPU performance."));

static TAutoConsoleVariable<int32> CVarMaxOcclusionQueriesPerComponent(
	TEXT("foliage.MaxOcclusionQueriesPerComponent"),
	16,
	TEXT("Controls the granularity of occlusion culling. 16-128 is a reasonable range."));

static TAutoConsoleVariable<int32> CVarMinOcclusionQueriesPerComponent(
	TEXT("foliage.MinOcclusionQueriesPerComponent"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:344

Scope (from outer to inner):

file
function     void UHierarchicalInstancedStaticMeshComponent::FClusterBuilder::Init

Source code excerpt:

	Num = SortIndex.Num();

	OcclusionLayerTarget = CVarMaxOcclusionQueriesPerComponent.GetValueOnAnyThread();
	int32 MinInstancesPerOcclusionQuery = CVarMinInstancesPerOcclusionQuery.GetValueOnAnyThread();

	if (Num / MinInstancesPerOcclusionQuery < OcclusionLayerTarget)
	{
		OcclusionLayerTarget = Num / MinInstancesPerOcclusionQuery;
		if (OcclusionLayerTarget < CVarMinOcclusionQueriesPerComponent.GetValueOnAnyThread())