foliage.MinInstancesPerOcclusionQuery

foliage.MinInstancesPerOcclusionQuery

#Overview

name: foliage.MinInstancesPerOcclusionQuery

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

• type: Var
• help: Controls the granualrity of occlusion culling. 1024 to 65536 is a reasonable range. This is not exact, actual minimum might be off by a factor of two.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of foliage.MinInstancesPerOcclusionQuery is to control the granularity of occlusion culling for foliage instances in Unreal Engine 5. This setting variable is primarily used in the rendering system, specifically for optimizing the rendering of large numbers of foliage instances.

This setting variable is utilized in the Engine module, particularly within the HierarchicalInstancedStaticMesh component. It’s part of the optimization mechanism for rendering foliage and other instanced static meshes.

The value of this variable is set using a console variable (CVar) system. It’s initialized with a default value of 256, but can be changed at runtime through console commands or configuration files.

The associated variable CVarMinInstancesPerOcclusionQuery directly interacts with foliage.MinInstancesPerOcclusionQuery. They share the same value and purpose.

Developers must be aware that this variable affects the performance and visual quality trade-off in foliage rendering. A lower value will result in more fine-grained occlusion culling, potentially improving visual accuracy but at the cost of performance. A higher value will improve performance but might result in less accurate culling.

Best practices when using this variable include:

1. Experimentation to find the optimal value for your specific use case.
2. Consider the density and distribution of your foliage when setting this value.
3. Be aware that the actual minimum might be off by a factor of two from the set value.
4. Use values within the recommended range of 1024 to 65536 for most scenarios.

Regarding the associated variable CVarMinInstancesPerOcclusionQuery:

• It serves the same purpose as foliage.MinInstancesPerOcclusionQuery.
• It’s used internally in the C++ code to access and modify the value of the console variable.
• The value is retrieved using the GetValueOnAnyThread() method, which allows for thread-safe access to the variable’s value.
• It’s used in the initialization of the FClusterBuilder for the HierarchicalInstancedStaticMeshComponent, directly influencing how instances are grouped for occlusion queries.

When working with CVarMinInstancesPerOcclusionQuery, developers should be aware that changes to this variable will immediately affect the foliage rendering system’s behavior. It’s important to profile and test different values to find the optimal balance between performance and visual quality for your specific project.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarMinInstancesPerOcclusionQuery(
	TEXT("foliage.MinInstancesPerOcclusionQuery"),
	256,
	TEXT("Controls the granualrity of occlusion culling. 1024 to 65536 is a reasonable range. This is not exact, actual minimum might be off by a factor of two."));

static TAutoConsoleVariable<float> CVarFoliageDensityScale(
	TEXT("foliage.DensityScale"),
	1.0,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	TEXT("Controls the granularity of occlusion culling. 2 should be the Min."));

static TAutoConsoleVariable<int32> CVarMinInstancesPerOcclusionQuery(
	TEXT("foliage.MinInstancesPerOcclusionQuery"),
	256,
	TEXT("Controls the granualrity of occlusion culling. 1024 to 65536 is a reasonable range. This is not exact, actual minimum might be off by a factor of two."));

static TAutoConsoleVariable<float> CVarFoliageDensityScale(
	TEXT("foliage.DensityScale"),

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

Scope (from outer to inner):

file
function     void UHierarchicalInstancedStaticMeshComponent::FClusterBuilder::Init

Source code excerpt:

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

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