p.GeometryCollection.PositionUpdateTolerance

p.GeometryCollection.PositionUpdateTolerance

#Overview

name: p.GeometryCollection.PositionUpdateTolerance

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

• type: Var
• help: Tolerance to detect if particle position has changed has changed when syncing PT to GT

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.GeometryCollection.PositionUpdateTolerance is to set a tolerance value for detecting changes in particle positions when synchronizing the Physics Thread (PT) to the Game Thread (GT) in the Geometry Collection system.

This setting variable is primarily used in the Geometry Collection physics system, which is part of the Chaos physics engine in Unreal Engine 5. It’s specifically utilized in the GeometryCollectionPhysicsProxy module.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. It’s initialized with the value of UE_KINDA_SMALL_NUMBER, which is a very small floating-point number used to avoid floating-point precision issues.

This variable interacts closely with its associated variable GeometryCollectionPositionUpdateTolerance. They share the same value and are used interchangeably in the code.

Developers must be aware that this tolerance value affects the sensitivity of position change detection in Geometry Collections. A smaller value will detect more subtle changes, while a larger value might miss small movements but could potentially improve performance by reducing unnecessary updates.

Best practices when using this variable include:

1. Adjusting it carefully based on the scale and movement patterns of your Geometry Collections.
2. Testing thoroughly to ensure that the chosen tolerance doesn’t cause visual artifacts or unexpected behavior.
3. Consider performance implications when setting very low tolerance values.

Regarding the associated variable GeometryCollectionPositionUpdateTolerance:

This variable is directly used in the UpdateGTParticleXR function to determine if a particle’s position has changed enough to warrant an update. It’s compared against the difference between the old and new positions using the Equals function with a tolerance.

The purpose of this variable is the same as p.GeometryCollection.PositionUpdateTolerance - to provide a threshold for detecting position changes in Geometry Collection particles.

It’s used within the Chaos physics engine, specifically in the Geometry Collection physics proxy.

The value is set at the file scope and can be modified through the console variable system.

Developers should be aware that this variable directly affects the frequency of position updates for Geometry Collection particles. A balance needs to be struck between accuracy (detecting small movements) and performance (avoiding unnecessary updates).

Best practices for using this variable include:

1. Adjusting it based on the specific requirements of your Geometry Collections.
2. Monitoring performance and visual fidelity when changing this value.
3. Considering using different tolerance values for different types of Geometry Collections if needed.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GeometryCollectionPositionUpdateTolerance = UE_KINDA_SMALL_NUMBER;
FAutoConsoleVariableRef CVarGeometryCollectionPositionUpdateTolerance(
	TEXT("p.GeometryCollection.PositionUpdateTolerance"),
	GeometryCollectionPositionUpdateTolerance,
	TEXT("Tolerance to detect if particle position has changed has changed when syncing PT to GT"));

float GeometryCollectionRotationUpdateTolerance = UE_KINDA_SMALL_NUMBER;
FAutoConsoleVariableRef CVarGeometryCollectionRotationUpdateTolerance(
	TEXT("p.GeometryCollection.RotationUpdateTolerance"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	TEXT("Tolerance to detect if a transform has changed"));

float GeometryCollectionPositionUpdateTolerance = UE_KINDA_SMALL_NUMBER;
FAutoConsoleVariableRef CVarGeometryCollectionPositionUpdateTolerance(
	TEXT("p.GeometryCollection.PositionUpdateTolerance"),
	GeometryCollectionPositionUpdateTolerance,
	TEXT("Tolerance to detect if particle position has changed has changed when syncing PT to GT"));

float GeometryCollectionRotationUpdateTolerance = UE_KINDA_SMALL_NUMBER;
FAutoConsoleVariableRef CVarGeometryCollectionRotationUpdateTolerance(
	TEXT("p.GeometryCollection.RotationUpdateTolerance"),
	GeometryCollectionRotationUpdateTolerance,

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

Scope (from outer to inner):

file
function     static inline bool UpdateGTParticleXR

Source code excerpt:

	const Chaos::FVec3 OldX = GTParticle.GetX();
	const bool bNeedUpdateX = (!NewX.Equals(OldX, GeometryCollectionPositionUpdateTolerance));
	if (bNeedUpdateX)
	{
		GTParticle.SetX(NewX, false);
	}

	const Chaos::FRotation3 OldR = GTParticle.R();