p.Clustering.ParticleReleaseThrottlingMaxCount

p.Clustering.ParticleReleaseThrottlingMaxCount

#Overview

name: p.Clustering.ParticleReleaseThrottlingMaxCount

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

• type: Var
• help: Maximum number of active geometry collection to reach before all released clustering disable all released particle instantly

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Clustering.ParticleReleaseThrottlingMaxCount is to control the maximum number of active geometry collections before all released clustering disables all released particles instantly. This setting variable is part of the particle clustering system in Unreal Engine’s Chaos physics engine.

• The Chaos physics engine, specifically the PBDRigidClustering module, relies on this setting variable.
• The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through the console or configuration files.
• This variable interacts closely with another variable called ClusteringParticleReleaseThrottlingMinCount. Together, they define a range for throttling particle release.
• Developers must be aware that this variable is used in conjunction with ClusteringParticleReleaseThrottlingMinCount to determine when and how much to throttle particle release in clustered simulations.
• Best practices when using this variable include:
  1. Ensure it’s set to a value greater than or equal to ClusteringParticleReleaseThrottlingMinCount.
  2. Use it to fine-tune performance in scenes with many active geometry collections.
  3. Monitor its impact on simulation quality and performance to find the optimal value for your specific use case.

Regarding the associated variable ClusteringParticleReleaseThrottlingMaxCount:

• It serves the same purpose as p.Clustering.ParticleReleaseThrottlingMaxCount, acting as the internal representation of the console variable.
• This variable is used directly in the code to perform calculations and checks related to particle release throttling.
• It’s initialized to INDEX_NONE, which likely represents an unset or default state.
• The variable is used in the CVarShouldThrottleParticleRelease() function to determine if particle release throttling should be active.
• It’s also used in the GetRatioOfReleasedParticlesToDisable() function to calculate the ratio of particles to disable based on the current number of active particles.

Developers should treat this associated variable as read-only within their code, as its value is managed by the console variable system. Any modifications to this value should be done through the console variable p.Clustering.ParticleReleaseThrottlingMaxCount 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/Chaos/PBDRigidClustering.cpp:70

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	int32 ClusteringParticleReleaseThrottlingMaxCount = INDEX_NONE;
	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMaxCount(TEXT("p.Clustering.ParticleReleaseThrottlingMaxCount"), ClusteringParticleReleaseThrottlingMaxCount, TEXT("Maximum number of active geometry collection to reach before all released clustering disable all released particle instantly"));

	namespace CVars
	{
		extern CHAOS_API bool bChaosConvexSimplifyUnion;
	}

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMinCount(TEXT("p.Clustering.ParticleReleaseThrottlingMinCount"), ClusteringParticleReleaseThrottlingMinCount, TEXT("Minimum number of active geometry collection to reach before clustering start to disable a percentage of the released particle per cluster"));

	int32 ClusteringParticleReleaseThrottlingMaxCount = INDEX_NONE;
	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMaxCount(TEXT("p.Clustering.ParticleReleaseThrottlingMaxCount"), ClusteringParticleReleaseThrottlingMaxCount, TEXT("Maximum number of active geometry collection to reach before all released clustering disable all released particle instantly"));

	namespace CVars
	{
		extern CHAOS_API bool bChaosConvexSimplifyUnion;
	}

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    anonymous
function     bool CVarShouldThrottleParticleRelease

Source code excerpt:

		bool CVarShouldThrottleParticleRelease()
		{
			return (ClusteringParticleReleaseThrottlingMinCount >= 0 && ClusteringParticleReleaseThrottlingMaxCount >= 0);
		}

		// compute a ratio (between 0 and 1) of released particles to release
		float GetRatioOfReleasedParticlesToDisable(const FRigidClustering::FRigidEvolution& Evolution)
		{
			const FPBDRigidsSOAs& ParticleStructures = Evolution.GetParticles();

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    anonymous
function     float GetRatioOfReleasedParticlesToDisable

Source code excerpt:

			NumActiveParticles += ParticleStructures.GetDynamicGeometryCollectionArray().Num();

			const int32 Range = FMath::Max(0, (ClusteringParticleReleaseThrottlingMaxCount - ClusteringParticleReleaseThrottlingMinCount));
			const int32 OverMinCount = FMath::Max(0, (NumActiveParticles - ClusteringParticleReleaseThrottlingMinCount));

			if (Range > 0)
			{
				// clamp to 1, as OverMinCount can get larger than Range
				return FMath::Min(1.f, ((float)OverMinCount / (float)Range));