p.gc.ReportHighParticleFraction

p.gc.ReportHighParticleFraction

#Overview

name: p.gc.ReportHighParticleFraction

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

• type: Var
• help: Report any objects with particle fraction above this threshold

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.gc.ReportHighParticleFraction is to set a threshold for reporting objects with a high particle fraction in the Chaos physics system, specifically for Geometry Collections. This setting is part of Unreal Engine’s experimental Chaos physics system and is used in the geometry collection physics proxy.

The Unreal Engine subsystem that relies on this setting variable is the Chaos physics system, particularly the Geometry Collection module within the Experimental Chaos runtime.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of -1.f and can be modified at runtime using console commands.

This variable interacts directly with its associated variable ReportHighParticleFraction. They share the same value, with ReportHighParticleFraction being the actual float variable used in the code, while p.gc.ReportHighParticleFraction is the console variable name used to modify it.

Developers must be aware that:

1. This variable is used for debugging and performance monitoring purposes.
2. A value of -1.f (the default) effectively disables the reporting feature.
3. Setting a value greater than 0 will enable reporting for objects with a particle fraction above the specified threshold.

Best practices when using this variable include:

1. Use it during development and testing phases to identify potential performance issues related to high particle counts in Geometry Collections.
2. Set it to a reasonable threshold (e.g., 0.5 to 0.9) to catch only significant cases.
3. Disable it (set to -1.f) in release builds to avoid unnecessary performance overhead.

Regarding the associated variable ReportHighParticleFraction:

• Its purpose is identical to p.gc.ReportHighParticleFraction, serving as the actual float variable used in the code.
• It’s used within the FGeometryCollectionPhysicsProxy::Initialize function to check and report Geometry Collections with high particle fractions.
• The value is compared against the CollisionParticlesFraction of each CollisionShapesData in the Geometry Collection.
• If the CollisionParticlesFraction is greater than or equal to ReportHighParticleFraction (when ReportHighParticleFraction > 0), a warning message is logged.
• Developers should use this variable through the console variable system (p.gc.ReportHighParticleFraction) rather than modifying it directly in the code.

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

Scope: file

Source code excerpt:

float ReportHighParticleFraction = -1.f;
FAutoConsoleVariableRef CVarReportHighParticleFraction(TEXT("p.gc.ReportHighParticleFraction"), ReportHighParticleFraction, TEXT("Report any objects with particle fraction above this threshold"));

CHAOS_API bool bBuildGeometryForChildrenOnPT = true;
FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnPT(TEXT("p.gc.BuildGeometryForChildrenOnPT"), bBuildGeometryForChildrenOnPT, TEXT("If true build all children geometry on Physics Thread at initilaization time, otherwise wait until destruction occurs."));

bool bBuildGeometryForChildrenOnGT = true;
FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnGT(TEXT("p.gc.BuildGeometryForChildrenOnGT"), bBuildGeometryForChildrenOnGT, TEXT("If true build all children geometry  on Game Thread at initilaization time, otherwise wait until destruction occurs."));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

{}

float ReportHighParticleFraction = -1.f;
FAutoConsoleVariableRef CVarReportHighParticleFraction(TEXT("p.gc.ReportHighParticleFraction"), ReportHighParticleFraction, TEXT("Report any objects with particle fraction above this threshold"));

CHAOS_API bool bBuildGeometryForChildrenOnPT = true;
FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnPT(TEXT("p.gc.BuildGeometryForChildrenOnPT"), bBuildGeometryForChildrenOnPT, TEXT("If true build all children geometry on Physics Thread at initilaization time, otherwise wait until destruction occurs."));

bool bBuildGeometryForChildrenOnGT = true;
FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnGT(TEXT("p.gc.BuildGeometryForChildrenOnGT"), bBuildGeometryForChildrenOnGT, TEXT("If true build all children geometry  on Game Thread at initilaization time, otherwise wait until destruction occurs."));

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::Initialize

Source code excerpt:

	//
	CollisionParticlesPerObjectFraction = Parameters.CollisionSampleFraction * CollisionParticlesPerObjectFractionDefault;
	if (ReportHighParticleFraction > 0)
	{
		for (const FSharedSimulationSizeSpecificData& Data : Parameters.Shared.SizeSpecificData)
		{
			if (ensure(Data.CollisionShapesData.Num()))
			{
				if (Data.CollisionShapesData[0].CollisionParticleData.CollisionParticlesFraction >= ReportHighParticleFraction)
				{
					ensureMsgf(false, TEXT("Collection with small particle fraction"));
					UE_LOG(LogChaos, Warning, TEXT("Collection with small particle fraction(%f):%s"), Data.CollisionShapesData[0].CollisionParticleData.CollisionParticlesFraction, *Parameters.Name);
				}
			}
		}