p.ShallowCopyOnClusterUnionUpdate

p.ShallowCopyOnClusterUnionUpdate

#Overview

name: p.ShallowCopyOnClusterUnionUpdate

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 p.ShallowCopyOnClusterUnionUpdate is to control the copying behavior of cluster union geometry when it updates in the Chaos physics system of Unreal Engine 5. This setting is specifically related to the physics simulation and optimization of clustered objects.

This setting variable is primarily used in the Chaos physics module, which is an experimental physics system in Unreal Engine 5. It’s referenced in the ClusterUnionPhysicsProxy.cpp file, indicating its relevance to the cluster union physics simulation.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 1.

The associated variable GShallowCopyClusterUnionGeometryOnUpdate directly interacts with p.ShallowCopyOnClusterUnionUpdate. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the performance and memory usage of physics simulations involving cluster unions. When set to 1 (default), it performs a shallow copy of the root union geometry during updates. When set to 0, it performs a deep copy of the entire geometry hierarchy.

Best practices when using this variable include:

  1. Leave it at the default value (1) unless specific issues arise with cluster union physics.
  2. If experiencing inconsistencies in physics behavior, try setting it to 0 for a more thorough but potentially more resource-intensive update.
  3. Profile the performance impact when changing this setting, especially in scenes with many clustered objects.

Regarding the associated variable GShallowCopyClusterUnionGeometryOnUpdate:

The purpose of GShallowCopyClusterUnionGeometryOnUpdate is to serve as the actual storage for the p.ShallowCopyOnClusterUnionUpdate setting. It’s an integer variable that directly controls the behavior in the code.

This variable is used in the Chaos physics module, specifically in the ClusterUnionPhysicsProxy class.

Its value is set through the console variable system, initialized to 1 by default.

It directly interacts with p.ShallowCopyOnClusterUnionUpdate, effectively being the implementation of that setting.

Developers should be aware that this variable is used in conditional statements to determine the copying behavior during physics updates. Its value (0 or 1) directly affects the physics simulation performance and accuracy.

Best practices for GShallowCopyClusterUnionGeometryOnUpdate align with those of p.ShallowCopyOnClusterUnionUpdate, as they are essentially the same setting. Developers should avoid modifying this variable directly in code, instead using the console variable system to ensure consistency across the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/ClusterUnionPhysicsProxy.cpp:13

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

{
	static int32 GShallowCopyClusterUnionGeometryOnUpdate = 1;
	FAutoConsoleVariableRef CVar_ShallowCopyClusterUnionGeometryOnUpdate(TEXT("p.ShallowCopyOnClusterUnionUpdate"), GShallowCopyClusterUnionGeometryOnUpdate, TEXT("If 1, shallow copy the root union geometry of a cluster union when its geometry updates, otherwise deep copy the geometry hierarchy"));

	namespace
	{
		FPBDRigidsEvolutionGBF* GetEvolution(FClusterUnionPhysicsProxy* Proxy)
		{
			if (!Proxy)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/ClusterUnionPhysicsProxy.cpp:12

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

namespace Chaos
{
	static int32 GShallowCopyClusterUnionGeometryOnUpdate = 1;
	FAutoConsoleVariableRef CVar_ShallowCopyClusterUnionGeometryOnUpdate(TEXT("p.ShallowCopyOnClusterUnionUpdate"), GShallowCopyClusterUnionGeometryOnUpdate, TEXT("If 1, shallow copy the root union geometry of a cluster union when its geometry updates, otherwise deep copy the geometry hierarchy"));

	namespace
	{
		FPBDRigidsEvolutionGBF* GetEvolution(FClusterUnionPhysicsProxy* Proxy)
		{
			if (!Proxy)

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/ClusterUnionPhysicsProxy.cpp:694

Scope (from outer to inner):

file
namespace    Chaos
function     void FClusterUnionPhysicsProxy::BufferPhysicsResults_Internal

Source code excerpt:

			{
				if(FImplicitObjectUnion* AsUnion = ClusterUnion->Geometry->AsA<FImplicitObjectUnion>();
				   GShallowCopyClusterUnionGeometryOnUpdate && AsUnion)
				{
					// Shallow copy the root union for the GT update
					// This ensures the GT has a snapshot of the union as it is now for this results data. The PT is free to
					// continue modifying its geometry without potentially disrupting GT reads. Internally we don't want
					// to duplicate all the geometry - we essentially just need the list of objects in the root union to
					// point to the correct internal geometries, but have a separate list on GT and PT.