foliage.SplitFactor

foliage.SplitFactor

#Overview

name: foliage.SplitFactor

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.SplitFactor is to control the branching factor of the foliage tree in Unreal Engine 5. This setting variable is primarily used in the rendering system, specifically for managing hierarchical instanced static meshes, which are commonly used for foliage and other repetitive environmental elements.

The Unreal Engine subsystem that relies on this setting variable is the Hierarchical Instanced Static Mesh Component, which is part of the Engine module. This can be seen from the file path where the variable is defined and used: Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp.

The value of this variable is set as a console variable with a default value of 16. It can be changed at runtime through the console or programmatically.

The foliage.SplitFactor variable interacts directly with the CVarFoliageSplitFactor variable. They share the same value, as CVarFoliageSplitFactor is the actual TAutoConsoleVariable that stores and provides access to the foliage.SplitFactor value.

Developers must be aware that this variable directly affects the performance and memory usage of foliage rendering. A higher split factor will result in more branching in the foliage tree, which can lead to better culling and rendering performance in some cases, but may also increase memory usage.

Best practices when using this variable include:

  1. Experiment with different values to find the optimal balance between performance and memory usage for your specific use case.
  2. Monitor performance metrics when adjusting this value, as its impact can vary depending on the complexity and density of your foliage.
  3. Consider adjusting this value dynamically based on the current scene complexity or performance requirements.

Regarding the associated variable CVarFoliageSplitFactor:

The purpose of CVarFoliageSplitFactor is to provide a programmatic interface to access and modify the foliage.SplitFactor value within the C++ code of Unreal Engine.

This variable is used directly in the Hierarchical Instanced Static Mesh Component’s cluster building process. Specifically, it’s used in the FClusterBuilder::Init function to determine the InternalNodeBranchingFactor.

The value of CVarFoliageSplitFactor is set when the console variable foliage.SplitFactor is initialized or changed.

CVarFoliageSplitFactor interacts with the InternalNodeBranchingFactor and indirectly with MaxInstancesPerLeaf in the cluster building process.

Developers should be aware that changes to CVarFoliageSplitFactor will immediately affect the foliage rendering system, potentially impacting performance and memory usage.

Best practices for using CVarFoliageSplitFactor include:

  1. Use GetValueOnAnyThread() when accessing the value, as shown in the code example.
  2. Consider the impact on the entire foliage system when modifying this value, as it affects the structure of the foliage tree.
  3. Use this variable in conjunction with other foliage-related settings to fine-tune the rendering performance and quality of your foliage system.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarFoliageSplitFactor(
	TEXT("foliage.SplitFactor"),
	16,
	TEXT("This controls the branching factor of the foliage tree."));

static TAutoConsoleVariable<int32> CVarForceLOD(
	TEXT("foliage.ForceLOD"),
	-1,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#endif

static TAutoConsoleVariable<int32> CVarFoliageSplitFactor(
	TEXT("foliage.SplitFactor"),
	16,
	TEXT("This controls the branching factor of the foliage tree."));

static TAutoConsoleVariable<int32> CVarForceLOD(
	TEXT("foliage.ForceLOD"),

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

Scope (from outer to inner):

file
function     void UHierarchicalInstancedStaticMeshComponent::FClusterBuilder::Init

Source code excerpt:

		}
	}
	InternalNodeBranchingFactor = CVarFoliageSplitFactor.GetValueOnAnyThread();
		
	if (Num / MaxInstancesPerLeaf < InternalNodeBranchingFactor) // if there are less than InternalNodeBranchingFactor leaf nodes
	{
		MaxInstancesPerLeaf = FMath::Clamp<int32>(Num / InternalNodeBranchingFactor, 1, 1024); // then make sure we have at least InternalNodeBranchingFactor leaves
	}
}