foliage.MinOcclusionQueriesPerComponent

foliage.MinOcclusionQueriesPerComponent

#Overview

name: foliage.MinOcclusionQueriesPerComponent

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 foliage.MinOcclusionQueriesPerComponent is to control the granularity of occlusion culling for hierarchical instanced static meshes, particularly in the context of foliage rendering. This setting variable is part of the rendering system, specifically focusing on performance optimization for foliage and other instanced meshes.

This setting variable is primarily used in the Engine module, specifically within the HierarchicalInstancedStaticMesh component. Based on the callsites, it’s clear that this variable is integral to the occlusion culling system for instanced static meshes.

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

The foliage.MinOcclusionQueriesPerComponent variable interacts with another variable called CVarMinInstancesPerOcclusionQuery. Together, these variables determine how occlusion queries are distributed among instances in a hierarchical instanced static mesh component.

Developers should be aware that this variable directly affects the performance and visual quality trade-off in foliage rendering. Setting it too low might result in more granular occlusion culling but could increase the performance overhead, while setting it too high might reduce the effectiveness of occlusion culling.

Best practices when using this variable include:

  1. Keeping the value at 2 or higher, as suggested in the comment.
  2. Experimenting with values between 2 and the default 6 to find the optimal balance between performance and visual quality for specific use cases.
  3. Considering the relationship between this variable and MinInstancesPerOcclusionQuery when adjusting occlusion culling behavior.

Regarding the associated variable CVarMinOcclusionQueriesPerComponent:

The purpose of CVarMinOcclusionQueriesPerComponent is to provide a programmatic interface to the foliage.MinOcclusionQueriesPerComponent setting. It allows the engine to access and modify the value at runtime.

This variable is used within the Engine module, specifically in the HierarchicalInstancedStaticMesh component implementation.

The value of CVarMinOcclusionQueriesPerComponent is set to match foliage.MinOcclusionQueriesPerComponent, initialized with a default value of 6.

CVarMinOcclusionQueriesPerComponent interacts directly with the OcclusionLayerTarget calculation in the FClusterBuilder::Init() function of the UHierarchicalInstancedStaticMeshComponent class.

Developers should be aware that modifying CVarMinOcclusionQueriesPerComponent will have the same effect as changing foliage.MinOcclusionQueriesPerComponent. It’s important to use the appropriate interface (console commands or code) depending on the specific use case.

Best practices for using CVarMinOcclusionQueriesPerComponent include:

  1. Using GetValueOnAnyThread() when accessing the value, as shown in the code example.
  2. Considering thread safety when modifying this value, especially in multi-threaded rendering scenarios.
  3. Documenting any runtime modifications to this variable to ensure consistency across the 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:117

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMinOcclusionQueriesPerComponent(
	TEXT("foliage.MinOcclusionQueriesPerComponent"),
	6,
	TEXT("Controls the granularity of occlusion culling. 2 should be the Min."));

static TAutoConsoleVariable<int32> CVarMinInstancesPerOcclusionQuery(
	TEXT("foliage.MinInstancesPerOcclusionQuery"),
	256,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	TEXT("Controls the granularity of occlusion culling. 16-128 is a reasonable range."));

static TAutoConsoleVariable<int32> CVarMinOcclusionQueriesPerComponent(
	TEXT("foliage.MinOcclusionQueriesPerComponent"),
	6,
	TEXT("Controls the granularity of occlusion culling. 2 should be the Min."));

static TAutoConsoleVariable<int32> CVarMinInstancesPerOcclusionQuery(
	TEXT("foliage.MinInstancesPerOcclusionQuery"),

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

Scope (from outer to inner):

file
function     void UHierarchicalInstancedStaticMeshComponent::FClusterBuilder::Init

Source code excerpt:

	{
		OcclusionLayerTarget = Num / MinInstancesPerOcclusionQuery;
		if (OcclusionLayerTarget < CVarMinOcclusionQueriesPerComponent.GetValueOnAnyThread())
		{
			OcclusionLayerTarget = 0;
		}
	}
	InternalNodeBranchingFactor = CVarFoliageSplitFactor.GetValueOnAnyThread();