foliage.DiscardDataOnLoad

foliage.DiscardDataOnLoad

#Overview

name: foliage.DiscardDataOnLoad

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

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of foliage.DiscardDataOnLoad is to control whether foliage data should be discarded on load for specific foliage types in Unreal Engine 5. This setting is primarily used for performance optimization and scalability in the foliage rendering system.

This setting variable is used in the Foliage module of Unreal Engine 5, specifically within the InstancedFoliage system. It is implemented as a console variable (CVarFoliageDiscardDataOnLoad) in the Foliage runtime.

The value of this variable is set through the console command system. By default, it is set to 0, meaning foliage data is kept regardless of the foliage type settings. When set to 1, it enables the discarding of foliage data on load for foliage types that have the feature enabled.

This variable interacts closely with the ‘bEnableDiscardOnLoad’ property of the UFoliageType class. When foliage.DiscardDataOnLoad is set to 1, the engine checks this property for each foliage type to determine whether its data should be discarded.

Developers must be aware that:

  1. This setting only takes effect when the game is not in editor mode (checked with !GIsEditor).
  2. Changes to this setting require reloading the level to take effect.
  3. It can significantly impact performance and memory usage, especially in large open-world scenarios.

Best practices when using this variable include:

  1. Use it in conjunction with the ‘bEnableDiscardOnLoad’ property on individual foliage types for fine-grained control.
  2. Test thoroughly to ensure that discarding foliage data doesn’t negatively impact visual quality or gameplay.
  3. Consider using this feature for distant or less important foliage to optimize performance.

Regarding the associated variable CVarFoliageDiscardDataOnLoad:

The purpose of CVarFoliageDiscardDataOnLoad is to provide programmatic access to the foliage.DiscardDataOnLoad setting within the C++ code of the Unreal Engine.

This console variable is defined in the Foliage module and is used internally by the engine to check the current state of the foliage.DiscardDataOnLoad setting.

The value of this variable is set automatically by the engine’s console variable system based on the foliage.DiscardDataOnLoad setting.

It interacts directly with the AInstancedFoliageActor class, specifically in the PostLoad() function, where it’s used to determine whether foliage data should be discarded.

Developers should be aware that:

  1. This is an internal engine variable and should not be modified directly.
  2. Its value is accessed using the GetValueOnGameThread() method, ensuring thread-safe access.

Best practices when working with this variable include:

  1. Use the foliage.DiscardDataOnLoad console command to change its value, rather than attempting to modify CVarFoliageDiscardDataOnLoad directly.
  2. When reading its value in code, always use the GetValueOnGameThread() method to ensure thread safety.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultDeviceProfiles.ini:116, section: [IOS_Mid DeviceProfile]

Location: <Workspace>/Projects/Lyra/Config/DefaultDeviceProfiles.ini:529, section: [Android_Mid DeviceProfile]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Foliage/Private/InstancedFoliage.cpp:75

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarFoliageDiscardDataOnLoad(
	TEXT("foliage.DiscardDataOnLoad"),
	0,
	TEXT("1: Discard foliage data on load if the foliage type has it enabled; 0: Keep foliage data regardless of whether the foliage type has it enabled or not (requires reloading level)"),
	ECVF_Scalability);

static TAutoConsoleVariable<float> CVarFoliageCullDistanceScale(
	TEXT("foliage.CullDistanceScale"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Foliage/Private/InstancedFoliage.cpp:74

Scope: file

Source code excerpt:

DECLARE_CYCLE_STAT(TEXT("FoliageMeshInfo_CreateComponent"), STAT_FoliageCreateComponent, STATGROUP_Foliage);

static TAutoConsoleVariable<int32> CVarFoliageDiscardDataOnLoad(
	TEXT("foliage.DiscardDataOnLoad"),
	0,
	TEXT("1: Discard foliage data on load if the foliage type has it enabled; 0: Keep foliage data regardless of whether the foliage type has it enabled or not (requires reloading level)"),
	ECVF_Scalability);

static TAutoConsoleVariable<float> CVarFoliageCullDistanceScale(

#Loc: <Workspace>/Engine/Source/Runtime/Foliage/Private/InstancedFoliage.cpp:4797

Scope (from outer to inner):

file
function     void AInstancedFoliageActor::PostLoad

Source code excerpt:

	if (!GIsEditor)
	{
		const bool bFoliageDiscardOnLoad = !!CVarFoliageDiscardDataOnLoad.GetValueOnGameThread();
		const float FoliageCullDistanceScale = FMath::Clamp(CVarFoliageCullDistanceScale.GetValueOnGameThread(), 0.0f, 1.0f);

		bool bHasISMFoliage = false;
		for (auto& Pair : FoliageInfos)
		{
			if (bFoliageDiscardOnLoad && (!Pair.Key || Pair.Key->bEnableDiscardOnLoad))

#Loc: <Workspace>/Engine/Source/Runtime/Foliage/Public/FoliageType.h:584

Scope (from outer to inner):

file
class        class UFoliageType : public UObject

Source code excerpt:


	/**
	* Whether this foliage type should be discarded when CVarFoliageDiscardDataOnLoad is enabled.
	*/
	UPROPERTY(EditAnywhere, Category=Scalability)
	uint32 bEnableDiscardOnLoad:1;

	/*
	 * Whether this foliage type should be affected by the Engine's "foliage.CullDistanceScale" setting 
	 */
	UPROPERTY(EditAnywhere, Category = Scalability)