FX.GPUSpawnWarningThreshold

FX.GPUSpawnWarningThreshold

#Overview

name: FX.GPUSpawnWarningThreshold

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of FX.GPUSpawnWarningThreshold is to set a warning threshold for spawning GPU particles in Unreal Engine’s particle system. It is primarily used for performance monitoring and debugging in the engine’s visual effects (FX) system.

This setting variable is mainly relied upon by the Unreal Engine’s particle system, specifically the GPU-based particle simulation subsystem. It is part of the Engine module and is used in the FXSystem and particle simulation components.

The value of this variable is set in the FXConsoleVariables namespace, initialized to 20000 particles. It can be modified at runtime through the console variable system, as indicated by the FAutoConsoleVariableRef declaration.

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

Developers must be aware that this variable is used to trigger warning logs when the number of GPU particles spawned in a single frame exceeds the threshold. This can help identify potential performance issues or unintended behavior in particle systems.

Best practices when using this variable include:

  1. Monitoring logs for warnings related to excessive particle spawning.
  2. Adjusting the threshold value based on the specific needs and performance characteristics of the game or application.
  3. Using it in conjunction with other particle system optimizations to ensure efficient GPU particle usage.

Regarding the associated variable GPUSpawnWarningThreshold:

The purpose of GPUSpawnWarningThreshold is identical to FX.GPUSpawnWarningThreshold, serving as the internal representation of the warning threshold for GPU particle spawning.

It is used directly in the particle system code, specifically in the FGPUSpriteParticleEmitterInstance class, to check if the number of newly spawned particles exceeds the threshold.

The value is set in the FXConsoleVariables namespace and can be modified through the console variable system.

GPUSpawnWarningThreshold interacts with the FX.GPUSpawnWarningThreshold console variable, sharing the same value.

Developers should be aware that this variable is used in the actual comparison logic within the particle system code, and any changes to it will directly affect when warnings are triggered.

Best practices for GPUSpawnWarningThreshold include:

  1. Considering it when optimizing particle systems, especially those with high spawn rates.
  2. Using it as a metric for performance tuning of GPU-based particle effects.
  3. Adjusting its value in tandem with FX.GPUSpawnWarningThreshold to maintain consistency in the warning system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Particles/FXSystem.cpp:192

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

		);
	FAutoConsoleVariableRef CVarGPUSpawnWarningThreshold(
		TEXT("FX.GPUSpawnWarningThreshold"),
		GPUSpawnWarningThreshold,
		TEXT("Warning threshold for spawning of GPU particles."),
		ECVF_Cheat
		);
	FAutoConsoleVariableRef CVarGPUCollisionDepthBounds(
		TEXT("FX.GPUCollisionDepthBounds"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Particles/FXSystem.cpp:131

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	int32 MaxCPUParticlesPerEmitter = 1000;
	int32 MaxGPUParticlesSpawnedPerFrame = 1024 * 1024;
	int32 GPUSpawnWarningThreshold = 20000;
	float GPUCollisionDepthBounds = 500.0f;
	TAutoConsoleVariable<int32> TestGPUSort(TEXT("FX.TestGPUSort"),0,TEXT("Test GPU sort. 1: Small, 2: Large, 3: Exhaustive, 4: Random"),ECVF_Cheat);

	/** Register references to flags. */
	FAutoConsoleVariableRef CVarVisualizeGPUSimulation(
		TEXT("FX.VisualizeGPUSimulation"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Particles/FXSystem.cpp:193

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	FAutoConsoleVariableRef CVarGPUSpawnWarningThreshold(
		TEXT("FX.GPUSpawnWarningThreshold"),
		GPUSpawnWarningThreshold,
		TEXT("Warning threshold for spawning of GPU particles."),
		ECVF_Cheat
		);
	FAutoConsoleVariableRef CVarGPUCollisionDepthBounds(
		TEXT("FX.GPUCollisionDepthBounds"),
		GPUCollisionDepthBounds,

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Particles/ParticleGpuSimulation.cpp:3694

Scope (from outer to inner):

file
class        class FGPUSpriteParticleEmitterInstance : public FParticleEmitterInstance
function     virtual void Tick

Source code excerpt:

				INC_DWORD_STAT_BY(STAT_GPUSpritesSpawned, NewParticleCount);
	#if STATS
				if (NewParticleCount > FXConsoleVariables::GPUSpawnWarningThreshold)
				{
					UE_LOG(LogParticles,Warning,TEXT("Spawning %d GPU particles in one frame[%d]: %s/%s"),
						NewParticleCount,
						GFrameNumber,
						*SpriteTemplate->GetOuter()->GetName(),
						*SpriteTemplate->EmitterName.ToString()

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/FXSystem.h:81

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	extern int32 MaxGPUParticlesSpawnedPerFrame;
	/** Warning threshold for spawning of GPU particles. */
	extern int32 GPUSpawnWarningThreshold;
	/** Depth bounds for GPU collision checks. */
	extern float GPUCollisionDepthBounds;
	/** Specify a sorting test to run. */
	extern TAutoConsoleVariable<int32> TestGPUSort;
	/** true if GPU particles are allowed. */
	extern int32 bAllowGPUParticles;