p.Chaos.Clustering.DumpClusterAndReleaseStats

p.Chaos.Clustering.DumpClusterAndReleaseStats

#Overview

name: p.Chaos.Clustering.DumpClusterAndReleaseStats

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Clustering.DumpClusterAndReleaseStats is to control the reporting of cluster processing and particle release statistics in the Chaos physics system of Unreal Engine 5. This setting variable is used for debugging and performance analysis of the rigid body clustering mechanism.

This setting variable is primarily used in the Chaos module, which is part of Unreal Engine’s experimental physics system. Specifically, it’s used in the rigid body clustering functionality within the Chaos system.

The value of this variable is set through a console variable (CVar) system. It’s initialized as a static integer (GDumpClusterAndReleaseStats) and then linked to the console variable “p.Chaos.Clustering.DumpClusterAndReleaseStats” using FAutoConsoleVariableRef.

This variable interacts with several other variables used for tracking clustering statistics, such as AdvanceCount, TotalProcessedClusters, TotalReleasedChildren, FrameProcessedClusters, and FrameReleasedChildren.

Developers should be aware that this is a debug feature and should be used primarily during development and testing. Enabling this variable will cause additional logging output, which could impact performance in a shipping build.

Best practices for using this variable include:

  1. Use it during development and testing phases to monitor clustering behavior.
  2. Disable it in shipping builds to avoid unnecessary performance overhead.
  3. When enabled, monitor the logs to understand the clustering patterns and identify any potential issues or inefficiencies in the physics simulation.

Regarding the associated variable GDumpClusterAndReleaseStats:

The purpose of GDumpClusterAndReleaseStats is to serve as the actual storage for the console variable value. It’s a static integer that holds the on/off state for the cluster and release statistics dumping feature.

This variable is used directly in the Chaos physics system, specifically in the FRigidClustering::AdvanceClustering function. When set to 1, it triggers the logging of clustering statistics.

The value of GDumpClusterAndReleaseStats is set through the console variable system, allowing it to be changed at runtime.

It interacts directly with the p.Chaos.Clustering.DumpClusterAndReleaseStats console variable, effectively serving as its backing store.

Developers should be aware that changes to this variable will immediately affect the logging behavior of the clustering system. They should also note that this variable is not thread-safe, so care should be taken when modifying it in a multi-threaded environment.

Best practices for using GDumpClusterAndReleaseStats include:

  1. Avoid direct modification of this variable; instead, use the console variable system to change its value.
  2. Be mindful of the performance impact when enabling this feature, especially in performance-critical scenarios.
  3. Use this variable in conjunction with other debugging tools to get a comprehensive view of the clustering system’s behavior.

#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:1664

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	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"));

	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::AdvanceClustering"), STAT_AdvanceClustering, STATGROUP_Chaos);
	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::Update Impulse from Strain"), STAT_UpdateImpulseStrain, STATGROUP_Chaos);
	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::Update Dirty Impulses"), STAT_UpdateDirtyImpulses, STATGROUP_Chaos);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/PBDRigidClustering.h:579

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

private:

	// Cluster release stats for debugging with CVar p.Chaos.Clustering.DumpClusterAndReleaseStats
	uint32 AdvanceCount = 0;
	uint32 TotalProcessedClusters = 0;
	uint32 TotalReleasedChildren = 0;
	uint32 FrameProcessedClusters = 0;
	uint32 FrameReleasedChildren = 0;

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

		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"));

	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::AdvanceClustering"), STAT_AdvanceClustering, STATGROUP_Chaos);
	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::Update Impulse from Strain"), STAT_UpdateImpulseStrain, STATGROUP_Chaos);
	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::Update Dirty Impulses"), STAT_UpdateDirtyImpulses, STATGROUP_Chaos);

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FRigidClustering::AdvanceClustering

Source code excerpt:

		Timer.Start();

		if(GDumpClusterAndReleaseStats == 1)
		{
			if(AdvanceCount > 0 && FrameReleasedChildren > 0)
			{
				UE_LOG(LogChaos, Display, TEXT("Clustering | Frame %.5u | Clusters: %.3u, Released: %.4u (TotalClusters: %.3u, TotalReleased: %.4u)"),
					   AdvanceCount,
					   FrameProcessedClusters,