foliage.DensityScale

foliage.DensityScale

#Overview

name: foliage.DensityScale

The value of this variable can be defined or overridden in .ini config files. 23 .ini config files referencing this setting variable.

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of foliage.DensityScale is to control the amount of foliage rendered in the game world. It’s primarily used for the rendering system, specifically for managing the density of foliage instances.

This setting variable is primarily used by the Unreal Engine’s Hierarchical Instanced Static Mesh (HISM) system, which is part of the engine’s rendering and foliage modules. It’s referenced in the HierarchicalInstancedStaticMesh.cpp file, indicating its importance in managing instanced static meshes, particularly for foliage.

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

The associated variable CVarFoliageDensityScale interacts directly with foliage.DensityScale. It’s used to retrieve the current value of the density scale in various parts of the code.

Developers should be aware of several important aspects when using this variable:

  1. The scale affects only foliage that opts-in to density scaling through the foliage type settings.
  2. The value is clamped between 0.0 and 1.0, where 0.0 means no foliage is rendered, and 1.0 means full density.
  3. Changes to this value can trigger rebuilding of the foliage instance tree, which may have performance implications.

Best practices when using this variable include:

  1. Use it for performance optimization, especially on lower-end hardware.
  2. Be cautious about frequently changing this value, as it can lead to frequent tree rebuilds.
  3. Consider the visual impact of reduced foliage density on your game’s aesthetics.

Regarding the associated variable CVarFoliageDensityScale:

The purpose of CVarFoliageDensityScale is to provide programmatic access to the foliage.DensityScale value within the C++ code.

It’s used in the same HISM system and is directly tied to the foliage rendering process. The value is typically retrieved using the GetValueOnGameThread() method.

This variable is set automatically when foliage.DensityScale is changed, as they share the same underlying value.

Other variables that interact with it include CachedFoliageDensityScale, which is used to detect changes in the density scale value, and CurrentDensityScaling, which applies the density scale to specific HISM components.

Developers should be aware that this variable is used in both editor and runtime contexts, with slightly different behavior in each.

Best practices include using this variable for real-time adjustments to foliage density, such as for dynamic performance scaling or environmental effects. However, frequent changes should be avoided due to the potential performance impact of tree rebuilds.

#Setting Variables

#References In INI files

<Workspace>/Engine/Config/BaseScalability.ini:752, section: [FoliageQuality@0]
<Workspace>/Engine/Config/BaseScalability.ini:758, section: [FoliageQuality@1]
<Workspace>/Engine/Config/BaseScalability.ini:764, section: [FoliageQuality@2]
<Workspace>/Engine/Config/BaseScalability.ini:770, section: [FoliageQuality@3]
<Workspace>/Engine/Config/BaseScalability.ini:776, section: [FoliageQuality@Cine]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:6, section: [FoliageQuality@0]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:12, section: [FoliageQuality@1]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:17, section: [FoliageQuality@2]
<Workspace>/Engine/Config/Android/AndroidScalability.ini:22, section: [FoliageQuality@3]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:6, section: [FoliageQuality@0]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:12, section: [FoliageQuality@1]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:17, section: [FoliageQuality@2]
<Workspace>/Engine/Config/IOS/IOSScalability.ini:22, section: [FoliageQuality@3]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:73, section: [FoliageQuality@0]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:77, section: [FoliageQuality@1]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:81, section: [FoliageQuality@2]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:85, section: [FoliageQuality@3]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:89, section: [FoliageQuality@Cine]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:94, section: [ViewDistanceQuality@0]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:98, section: [ViewDistanceQuality@1]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:102, section: [ViewDistanceQuality@2]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:106, section: [ViewDistanceQuality@3]
<Workspace>/Projects/Lyra/Config/DefaultScalability.ini:110, section: [ViewDistanceQuality@Cine]

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarFoliageDensityScale(
	TEXT("foliage.DensityScale"),
	1.0,
	TEXT("Controls the amount of foliage to render. Foliage must opt-in to density scaling through the foliage type."),
	ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarFoliageUseInstanceRuns(
	TEXT("foliage.InstanceRuns"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	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,
	TEXT("Controls the amount of foliage to render. Foliage must opt-in to density scaling through the foliage type."),
	ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarFoliageUseInstanceRuns(

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

Scope (from outer to inner):

file
function     static void FoliageCVarSinkFunction

Source code excerpt:

{
	static float CachedFoliageDensityScale = 1.0f;
	float FoliageDensityScale = CVarFoliageDensityScale.GetValueOnGameThread();

	if (FoliageDensityScale != CachedFoliageDensityScale)
	{
		CachedFoliageDensityScale = FoliageDensityScale;
		FoliageDensityScale = FMath::Clamp(FoliageDensityScale, 0.0f, 1.0f);

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

Scope (from outer to inner):

file
function     void UHierarchicalInstancedStaticMeshComponent::UpdateDensityScaling

Source code excerpt:


#if WITH_EDITOR
	CurrentDensityScaling = bCanEnableDensityScaling && bEnableDensityScaling ? CVarFoliageDensityScale.GetValueOnGameThread() : 1.0f;
#else
	CurrentDensityScaling = bEnableDensityScaling ? CVarFoliageDensityScale.GetValueOnGameThread() : 1.0f;
#endif

	CurrentDensityScaling = FMath::Clamp(CurrentDensityScaling, 0.0f, 1.0f);
	BuildTreeIfOutdated(/*Async*/true, /*ForceUpdate*/OldDensityScaling != CurrentDensityScaling);
}

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

Scope (from outer to inner):

file
function     void UHierarchicalInstancedStaticMeshComponent::OnPostLoadPerInstanceData

Source code excerpt:

		if (bEnableDensityScaling && GetWorld() && GetWorld()->IsGameWorld())
		{
			CurrentDensityScaling = FMath::Clamp(CVarFoliageDensityScale.GetValueOnGameThread(), 0.0f, 1.0f);
			bForceTreeBuild = CurrentDensityScaling < 1.0f;
		}

		if (CurrentDensityScaling == 0.f)
		{
			// Not going to render anything