ClusterUnion.UseAccelerationStructure

ClusterUnion.UseAccelerationStructure

#Overview

name: ClusterUnion.UseAccelerationStructure

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 ClusterUnion.UseAccelerationStructure is to determine whether component-level sweeps and overlaps against cluster unions should use an acceleration structure. This setting is primarily used in the physics engine, specifically for the ClusterUnion component.

This setting variable is used in the Unreal Engine’s physics engine module, particularly within the ClusterUnionComponent system. It’s referenced in the Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp file.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. By default, it’s set to true.

The associated variable bUseClusterUnionAccelerationStructure directly interacts with this setting. They share the same value and are used interchangeably in the code.

Developers must be aware that this setting affects the performance and behavior of physics calculations involving cluster unions. When enabled, it uses an acceleration structure for sweeps and overlaps, which can potentially improve performance for complex cluster unions.

Best practices when using this variable include:

  1. Consider the complexity of your cluster unions when deciding whether to enable or disable this feature.
  2. Profile your game’s performance with this setting both enabled and disabled to determine the optimal configuration for your specific use case.
  3. Be aware that changing this setting at runtime may have immediate effects on physics calculations.

Regarding the associated variable bUseClusterUnionAccelerationStructure:

This boolean variable is directly tied to the ClusterUnion.UseAccelerationStructure setting. It’s used within the ClusterUnionComponent’s code to determine whether to create and use an acceleration structure.

The variable is checked in the OnCreatePhysicsState function of the UClusterUnionComponent class. If true, it creates an empty acceleration structure.

Developers should be aware that this variable directly controls the creation and use of the acceleration structure in the ClusterUnionComponent. Changing its value will affect the component’s behavior and potentially its performance.

Best practices for using this variable include:

  1. Ensure consistency between this variable and the console variable setting.
  2. Consider the implications on memory usage and performance when enabling or disabling the acceleration structure.
  3. Test thoroughly when modifying this value, as it can significantly impact the physics behavior of cluster unions in your game.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:24

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

{
	bool bUseClusterUnionAccelerationStructure = true;
	FAutoConsoleVariableRef CVarUseClusterUnionAccelerationStructure(TEXT("ClusterUnion.UseAccelerationStructure"), bUseClusterUnionAccelerationStructure, TEXT("Whether component level sweeps and overlaps against cluster unions should use an acceleration structure instead."));

	bool bUseLocalRoleForAuthorityCheck = true;
	FAutoConsoleVariableRef CVarUseLocalRoleForAuthorityCheck(TEXT("ClusterUnion.UseLocalRoleForAuthorityCheck"), bUseLocalRoleForAuthorityCheck, TEXT("If true, we will only check this component's owner local role to determine authority"));

	bool bPreAllocateLocalBoneDataMap = true;
	FAutoConsoleVariableRef CVarPreAllocateLocalBoneDataMap(TEXT("ClusterUnion.PreAllocateLocalBoneDataMap"), bPreAllocateLocalBoneDataMap, TEXT("If true, it will reserve an expected size for the local map used to cache updated bone data"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:23

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

namespace
{
	bool bUseClusterUnionAccelerationStructure = true;
	FAutoConsoleVariableRef CVarUseClusterUnionAccelerationStructure(TEXT("ClusterUnion.UseAccelerationStructure"), bUseClusterUnionAccelerationStructure, TEXT("Whether component level sweeps and overlaps against cluster unions should use an acceleration structure instead."));

	bool bUseLocalRoleForAuthorityCheck = true;
	FAutoConsoleVariableRef CVarUseLocalRoleForAuthorityCheck(TEXT("ClusterUnion.UseLocalRoleForAuthorityCheck"), bUseLocalRoleForAuthorityCheck, TEXT("If true, we will only check this component's owner local role to determine authority"));

	bool bPreAllocateLocalBoneDataMap = true;
	FAutoConsoleVariableRef CVarPreAllocateLocalBoneDataMap(TEXT("ClusterUnion.PreAllocateLocalBoneDataMap"), bPreAllocateLocalBoneDataMap, TEXT("If true, it will reserve an expected size for the local map used to cache updated bone data"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:730

Scope (from outer to inner):

file
function     void UClusterUnionComponent::OnCreatePhysicsState

Source code excerpt:

	}
	
	if (bUseClusterUnionAccelerationStructure)
	{
		AccelerationStructure = CreateEmptyAccelerationStructure();
		check(AccelerationStructure != nullptr);
	}

	// It's just logically easier to be consistent on the client to go through the replication route.