r.ISMPool.ShadowCopyCustomData

r.ISMPool.ShadowCopyCustomData

#Overview

name: r.ISMPool.ShadowCopyCustomData

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 r.ISMPool.ShadowCopyCustomData is to control whether a copy of custom instance data should be kept for Instanced Static Mesh (ISM) pools in the Geometry Collection system. This setting is primarily used in the rendering system, specifically for managing instance data in Geometry Collections.

This setting variable is used in the Experimental GeometryCollectionEngine module of Unreal Engine 5. It’s particularly relevant to the GeometryCollectionISMPoolComponent, which is part of the Geometry Collection system used for efficient rendering of multiple instances of static meshes.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

The r.ISMPool.ShadowCopyCustomData variable interacts directly with the GShadowCopyCustomData boolean variable. They share the same value, with GShadowCopyCustomData being the actual boolean used in the code logic.

Developers must be aware that enabling this setting can increase memory usage, as it keeps a copy of custom instance data. This is useful when instances might be removed and re-added, as it allows for the restoration of the custom data.

Best practices when using this variable include:

  1. Only enable it when necessary, as it increases memory usage.
  2. Use it in scenarios where instances are frequently removed and re-added, and preserving custom data is important.
  3. Be mindful of the performance impact, especially with large numbers of instances.

Regarding the associated variable GShadowCopyCustomData:

The purpose of GShadowCopyCustomData is to serve as the actual boolean flag used in the code logic to determine whether custom instance data should be shadow copied.

This variable is used directly in the GeometryCollectionISMPoolComponent to control the behavior of custom data handling. It’s checked in the AddMesh function of FGeometryCollectionMeshGroup to determine whether to perform a shadow copy of custom data.

The value of GShadowCopyCustomData is set by the r.ISMPool.ShadowCopyCustomData console variable.

GShadowCopyCustomData interacts with the bAllowPerInstanceRemoval flag in the AddMesh function. Both conditions must be true for the shadow copy to occur.

Developers should be aware that this variable directly affects the behavior of the Geometry Collection system, particularly in scenarios involving instance removal and re-addition.

Best practices for using GShadowCopyCustomData include:

  1. Ensure it’s only set to true when the additional memory usage is acceptable.
  2. Use it in conjunction with bAllowPerInstanceRemoval for effective instance management.
  3. Consider the impact on performance and memory when enabling this feature, especially in systems with many instances.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:39

Scope: file

Source code excerpt:

static bool GShadowCopyCustomData = false;
FAutoConsoleVariableRef CVarShadowCopyCustomData(
	TEXT("r.ISMPool.ShadowCopyCustomData"),
	GShadowCopyCustomData,
	TEXT("Keeps a copy of custom instance data so it can be restored if the instance is removed and readded."));


void FGeometryCollectionMeshInfo::ShadowCopyCustomData(int32 InstanceCount, int32 NumCustomDataFloatsPerInstance, TArrayView<const float> CustomDataFloats)
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:37

Scope: file

Source code excerpt:

	TEXT("Target size for number of ISM components in the recycling free list."));

static bool GShadowCopyCustomData = false;
FAutoConsoleVariableRef CVarShadowCopyCustomData(
	TEXT("r.ISMPool.ShadowCopyCustomData"),
	GShadowCopyCustomData,
	TEXT("Keeps a copy of custom instance data so it can be restored if the instance is removed and readded."));


void FGeometryCollectionMeshInfo::ShadowCopyCustomData(int32 InstanceCount, int32 NumCustomDataFloatsPerInstance, TArrayView<const float> CustomDataFloats)
{
	CustomData.SetNum(InstanceCount * NumCustomDataFloatsPerInstance + NumCustomDataFloatsPerInstance);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionISMPoolComponent.cpp:65

Scope (from outer to inner):

file
function     FGeometryCollectionMeshGroup::FMeshId FGeometryCollectionMeshGroup::AddMesh

Source code excerpt:

	const FMeshId MeshInfoIndex = MeshInfos.Emplace(ISMInstanceInfo);

	if (bAllowPerInstanceRemoval && GShadowCopyCustomData)
	{
		FGeometryCollectionMeshInfo& MeshInfo = MeshInfos[MeshInfoIndex];
		MeshInfo.ShadowCopyCustomData(InstanceCount, MeshInstance.Desc.NumCustomDataFloats, CustomDataFloats);
	}

	return MeshInfoIndex;