p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit

p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit

#Overview

name: p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit

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.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit is to control the number of breaks allowed to be rescheduled for the next frame in the Chaos physics system’s clustering functionality.

This setting variable is part of Unreal Engine’s Chaos physics system, specifically within the clustering module. It is used in the Experimental Chaos namespace, indicating that it’s part of the experimental features of the Chaos physics engine.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files. It’s initialized to the maximum value of int32, allowing for an unlimited number of breaks to be rescheduled by default.

The associated variable GPerAdvanceBreaksRescheduleLimit directly interacts with this setting. They share the same value, with the console variable acting as an interface to modify the internal GPerAdvanceBreaksRescheduleLimit variable.

Developers must be aware that this variable affects the performance and behavior of the Chaos physics system, particularly in scenarios involving breaking clusters. Setting a lower value might improve performance but could lead to less accurate physics simulations if many breaks are occurring.

Best practices when using this variable include:

  1. Monitoring performance and adjusting the value based on the specific needs of the game or simulation.
  2. Testing with different values to find the right balance between performance and physics accuracy.
  3. Considering the complexity of the scenes and the frequency of cluster breaks when setting this value.

Regarding the associated variable GPerAdvanceBreaksRescheduleLimit:

The purpose of GPerAdvanceBreaksRescheduleLimit is to store the actual value used by the Chaos physics system to limit the number of breaks rescheduled per frame.

This variable is used directly in the AdvanceClustering function of the FRigidClustering class. It controls a loop that reschedules unprocessed parent clusters for the next tick, effectively limiting the number of breaks that can be processed in a single frame.

The value of this variable is set by the console variable p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit.

Developers should be aware that this variable directly impacts the physics simulation’s behavior and performance. A lower value might improve frame-to-frame performance but could lead to delayed breaking of clusters if there are many breaks occurring simultaneously.

Best practices for using this variable include:

  1. Profiling the physics simulation to understand the typical number of breaks occurring per frame in your scenes.
  2. Adjusting the value based on the target hardware capabilities and desired frame rate.
  3. Considering the visual impact of delayed cluster breaks when setting a lower value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClustering.cpp:1660

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	static int32 GPerAdvanceBreaksRescheduleLimit = TNumericLimits<int32>::Max();
	FAutoConsoleVariableRef CVarPerAdvanceBreaksRescheduleLimit(TEXT("p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit"), GPerAdvanceBreaksRescheduleLimit,
		TEXT("Number of breaks allowed to be rescheduled for next frame if any "));

	static int32 GDumpClusterAndReleaseStats = 0;
	FAutoConsoleVariableRef CVarDumpClusterAndReleaseStats(TEXT("p.Chaos.Clustering.DumpClusterAndReleaseStats"), GDumpClusterAndReleaseStats,
		TEXT("Report the number of cluster processes and released particles per frame, on/off 1/0"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClustering.cpp:1659

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

		TEXT("Number of breaks allowed to occur for each invokation of AdvanceClustering"));

	static int32 GPerAdvanceBreaksRescheduleLimit = TNumericLimits<int32>::Max();
	FAutoConsoleVariableRef CVarPerAdvanceBreaksRescheduleLimit(TEXT("p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit"), GPerAdvanceBreaksRescheduleLimit,
		TEXT("Number of breaks allowed to be rescheduled for next frame if any "));

	static int32 GDumpClusterAndReleaseStats = 0;
	FAutoConsoleVariableRef CVarDumpClusterAndReleaseStats(TEXT("p.Chaos.Clustering.DumpClusterAndReleaseStats"), GDumpClusterAndReleaseStats,
		TEXT("Report the number of cluster processes and released particles per frame, on/off 1/0"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClustering.cpp:1858

Scope (from outer to inner):

file
namespace    Chaos
function     void FRigidClustering::AdvanceClustering

Source code excerpt:


					// Add back the rest of the particles to process back in the strained array for later processing
					if (GPerAdvanceBreaksRescheduleLimit > 0)
					{
						// Add back the non processed parent clusters for next tick
						for (int32 Index = 0; Index < GPerAdvanceBreaksRescheduleLimit; Index++)
						{
							const int32 ParticleToProcessIndex = Index + LastProcessedIndex + 1;
							if (ParticleToProcessIndex >= ParticlesToProcess.Num())
							{
								break;
							}