FX.FreezeGPUSimulation

FX.FreezeGPUSimulation

#Overview

name: FX.FreezeGPUSimulation

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of FX.FreezeGPUSimulation is to control the freezing of GPU-simulated particles in Unreal Engine’s particle system. This setting variable is primarily used for debugging and performance analysis purposes within the engine’s visual effects (FX) system.

This setting variable is primarily used by the particle simulation system within Unreal Engine, specifically in the GPU-based particle simulation module. It is referenced in the FXSystem and ParticleGpuSimulation components of the engine.

The value of this variable is set through the console variable system in Unreal Engine. It is defined as an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands or configuration files.

FX.FreezeGPUSimulation interacts closely with another variable, bFreezeGPUSimulation. They share the same value and are used interchangeably in the code. Additionally, it often works in conjunction with FX.FreezeParticleSimulation (bFreezeParticleSimulation) to control overall particle simulation behavior.

Developers must be aware that this variable is marked with ECVF_Cheat flag, indicating it’s intended for debugging or cheats and should not be used in normal gameplay. When enabled, it will stop the simulation of GPU particles, which can significantly affect the visual fidelity and performance of particle effects in the game.

Best practices for using this variable include:

  1. Use it primarily for debugging and performance analysis.
  2. Be cautious when enabling it in production builds, as it can dramatically alter the game’s visual effects.
  3. Consider using it in conjunction with FX.FreezeParticleSimulation for a complete freeze of all particle simulations.
  4. Reset it to its default value (false) after debugging to ensure normal particle behavior.

Regarding the associated variable bFreezeGPUSimulation:

The purpose of bFreezeGPUSimulation is to serve as the internal representation of the FX.FreezeGPUSimulation console variable within the engine’s code. It directly controls whether GPU particle simulation is frozen.

This variable is used in the same subsystems as FX.FreezeGPUSimulation, primarily in the FXSystem and GPU particle simulation modules.

The value of bFreezeGPUSimulation is set by the console variable system when FX.FreezeGPUSimulation is modified. It’s initialized as false by default.

bFreezeGPUSimulation interacts closely with bFreezeParticleSimulation in conditional checks to determine if particle simulation should proceed.

Developers should be aware that this variable directly affects the behavior of GPU particle simulations and should be handled with care in production code.

Best practices for using bFreezeGPUSimulation include:

  1. Avoid modifying it directly in code; instead, use the FX.FreezeGPUSimulation console variable.
  2. When reading its value, consider also checking bFreezeParticleSimulation for a complete understanding of the particle simulation state.
  3. Be mindful of its performance implications when enabled in performance-critical sections of code.

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

		);
	FAutoConsoleVariableRef CVarFreezeGPUSimulation(
		TEXT("FX.FreezeGPUSimulation"),
		bFreezeGPUSimulation,
		TEXT("Freeze particles simulated on the GPU."),
		ECVF_Cheat
		);
	FAutoConsoleVariableRef CVarFreezeParticleSimulation(
		TEXT("FX.FreezeParticleSimulation"),

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	int32 bAllowGPUSorting = true;
	int32 bAllowCulling = true;
	int32 bFreezeGPUSimulation = false;
	int32 bFreezeParticleSimulation = false;
	int32 bAllowAsyncTick = !WITH_EDITOR;
	float ParticleSlackGPU = 0.02f;
	int32 MaxParticleTilePreAllocation = 100;
	int32 MaxCPUParticlesPerEmitter = 1000;
	int32 MaxGPUParticlesSpawnedPerFrame = 1024 * 1024;

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	FAutoConsoleVariableRef CVarFreezeGPUSimulation(
		TEXT("FX.FreezeGPUSimulation"),
		bFreezeGPUSimulation,
		TEXT("Freeze particles simulated on the GPU."),
		ECVF_Cheat
		);
	FAutoConsoleVariableRef CVarFreezeParticleSimulation(
		TEXT("FX.FreezeParticleSimulation"),
		bFreezeParticleSimulation,

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

Scope (from outer to inner):

file
class        class FGPUSpriteParticleEmitterInstance : public FParticleEmitterInstance
function     virtual FDynamicEmitterDataBase* GetDynamicData

Source code excerpt:


		const bool bSimulateGPUParticles = 
			FXConsoleVariables::bFreezeGPUSimulation == false &&
			FXConsoleVariables::bFreezeParticleSimulation == false &&
			RHISupportsGPUParticles();

		if (bSimulateGPUParticles)
		{
			float& DeltaSecondsInFix = DynamicData->PerFrameSimulationParameters.DeltaSecondsInFix;

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

Scope (from outer to inner):

file
class        class FGPUSpriteParticleEmitterInstance : public FParticleEmitterInstance
function     virtual void Tick

Source code excerpt:

		check(AllocatedTiles.Num() == TileTimeOfDeath.Num());

		if (FXConsoleVariables::bFreezeGPUSimulation ||
			FXConsoleVariables::bFreezeParticleSimulation ||
			!RHISupportsGPUParticles())
		{
			return;
		}

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	extern int32 bAllowCulling;
	/** true if GPU particle simulation is frozen. */
	extern int32 bFreezeGPUSimulation;
	/** true if particle simulation is frozen. */
	extern int32 bFreezeParticleSimulation;
	/** true if we allow async ticks */
	extern int32 bAllowAsyncTick;
	/** Amount of slack to allocate for GPU particles to prevent tile churn as percentage of total particles. */
	extern float ParticleSlackGPU;