foliage.InstanceRuns

foliage.InstanceRuns

#Overview

name: foliage.InstanceRuns

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

• type: Var
• help: Whether to use the InstanceRuns feature of FMeshBatch to compress foliage draw call data sent to the renderer. Not supported by the Mesh Draw Command pipeline.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of foliage.InstanceRuns is to control the use of the InstanceRuns feature of FMeshBatch for compressing foliage draw call data sent to the renderer. This setting is specifically related to the rendering system, particularly for optimizing the rendering of foliage in Unreal Engine 5.

This setting variable is primarily used in the Engine module, specifically within the Hierarchical Instanced Static Mesh (HISM) system. The HISM system is responsible for efficiently rendering large numbers of identical static mesh instances, which is particularly useful for foliage and other repetitive environmental elements.

The value of this variable is set through a console variable (CVar) named CVarFoliageUseInstanceRuns. It is initialized with a default value of 0, meaning the feature is disabled by default.

The associated variable CVarFoliageUseInstanceRuns directly interacts with foliage.InstanceRuns. They share the same value and purpose.

Developers must be aware of the following when using this variable:

1. The InstanceRuns feature is not supported by the Mesh Draw Command pipeline.
2. Enabling this feature may affect performance and memory usage, depending on the specific use case and hardware.
3. The setting is accessed on the render thread, which means changes to this value will be applied in the next frame.

Best practices when using this variable include:

1. Test the performance impact of enabling this feature in your specific use case before using it in production.
2. Consider enabling this feature only when dealing with large amounts of foliage that could benefit from draw call compression.
3. Be cautious when using this feature alongside other rendering optimizations, as it may interact with other systems.

Regarding the associated variable CVarFoliageUseInstanceRuns:

• Its purpose is identical to foliage.InstanceRuns, serving as the C++ representation of the console variable.
• It is used within the FHierarchicalStaticMeshSceneProxy::GetDynamicMeshElements function to determine whether to use instance runs when rendering foliage.
• The value is retrieved using GetValueOnRenderThread(), ensuring thread-safe access in the rendering pipeline.
• Developers should be aware that changes to this variable will only take effect on the next frame due to its use on the render thread.
• Best practices include using this variable consistently with foliage.InstanceRuns and considering its impact on rendering performance and memory usage.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarFoliageUseInstanceRuns(
	TEXT("foliage.InstanceRuns"),
	0,
	TEXT("Whether to use the InstanceRuns feature of FMeshBatch to compress foliage draw call data sent to the renderer.  Not supported by the Mesh Draw Command pipeline."));

#if RHI_RAYTRACING
static TAutoConsoleVariable<int32> CVarRayTracingHISM(
	TEXT("r.RayTracing.Geometry.HierarchicalInstancedStaticMesh"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarFoliageUseInstanceRuns(
	TEXT("foliage.InstanceRuns"),
	0,
	TEXT("Whether to use the InstanceRuns feature of FMeshBatch to compress foliage draw call data sent to the renderer.  Not supported by the Mesh Draw Command pipeline."));

#if RHI_RAYTRACING
static TAutoConsoleVariable<int32> CVarRayTracingHISM(

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

Scope (from outer to inner):

file
function     void FHierarchicalStaticMeshSceneProxy::GetDynamicMeshElements

Source code excerpt:

			ElementParams.bIsWireframe = ViewFamily.EngineShowFlags.Wireframe;
			ElementParams.bUseHoveredMaterial = IsHovered();
			ElementParams.bUseInstanceRuns = (CVarFoliageUseInstanceRuns.GetValueOnRenderThread() > 0);
			ElementParams.FeatureLevel = InstancedRenderData.FeatureLevel;
			ElementParams.ViewIndex = ViewIndex;
			ElementParams.View = View;

			// Render built instances
			if (ClusterTree.Num())