r.GPUParticle.Simulate

r.GPUParticle.Simulate

#Overview

name: r.GPUParticle.Simulate

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 r.GPUParticle.Simulate is to enable or disable GPU particle simulation in Unreal Engine 5. This setting variable is primarily used for controlling the particle system’s performance and behavior.

The Unreal Engine subsystem that relies on this setting variable is the particle simulation system, specifically the GPU-based particle simulation module. This can be inferred from the file name “ParticleGpuSimulation.cpp” and the various function names referencing particle simulation.

The value of this variable is set using a console variable (CVar) system. It is initialized with a default value of 1, which means GPU particle simulation is enabled by default. Users can change this value at runtime using console commands or through configuration files.

The associated variable CVarSimulateGPUParticles directly interacts with r.GPUParticle.Simulate. They share the same value and purpose, with CVarSimulateGPUParticles being the actual C++ variable used in the code to check the setting’s value.

Developers must be aware that disabling this variable (setting it to 0) will completely turn off GPU particle simulation. This can significantly impact the visual quality and performance of particle effects in the game or application.

Best practices when using this variable include:

  1. Only disable it if there’s a specific need, such as debugging CPU-based particle systems or if GPU particle simulation is causing issues on certain hardware configurations.
  2. Consider exposing this setting to end-users in graphics options menus, allowing them to disable GPU particle simulation if they experience performance issues.
  3. When disabled, ensure that fallback mechanisms for CPU-based particle simulation are in place and functioning correctly.
  4. Be aware that changing this setting at runtime may require reinitialization of particle systems for the changes to take effect.

Regarding the associated variable CVarSimulateGPUParticles:

The purpose of CVarSimulateGPUParticles is to provide a programmatic way to access and check the value of the r.GPUParticle.Simulate setting within the C++ code.

This variable is used in various functions within the GPU particle simulation system to conditionally execute code based on whether GPU particle simulation is enabled or not. For example, it’s checked in the ExecuteSimulationCommands, ClearTiles, and InjectNewParticles functions to determine if the GPU simulation code should be run.

The value of CVarSimulateGPUParticles is set automatically by the CVar system when r.GPUParticle.Simulate is modified.

Developers should use CVarSimulateGPUParticles.GetValueOnAnyThread() to check the current state of GPU particle simulation in their code. This allows for runtime toggling of GPU particle simulation features without requiring a game restart.

Best practices for using CVarSimulateGPUParticles include:

  1. Use it as a conditional check before executing GPU particle simulation code.
  2. Consider caching its value if checked frequently, but be aware that it can change at runtime.
  3. When adding new GPU particle simulation features, always wrap them in a check of this variable to ensure they respect the user’s settings.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarGPUParticleMaxNumIterations(TEXT("r.GPUParticle.MaxNumIterations"),3,TEXT("Max number of iteration when using a fix delta seconds."));

static TAutoConsoleVariable<int32> CVarSimulateGPUParticles(TEXT("r.GPUParticle.Simulate"), 1, TEXT("Enable or disable GPU particle simulation"));

/*-----------------------------------------------------------------------------
	Allocators used to manage GPU particle resources.
-----------------------------------------------------------------------------*/

/**

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarGPUParticleMaxNumIterations(TEXT("r.GPUParticle.MaxNumIterations"),3,TEXT("Max number of iteration when using a fix delta seconds."));

static TAutoConsoleVariable<int32> CVarSimulateGPUParticles(TEXT("r.GPUParticle.Simulate"), 1, TEXT("Enable or disable GPU particle simulation"));

/*-----------------------------------------------------------------------------
	Allocators used to manage GPU particle resources.
-----------------------------------------------------------------------------*/

/**

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

Scope (from outer to inner):

file
function     void ExecuteSimulationCommands

Source code excerpt:

	bool bUseFixDT)
{
	if (!CVarSimulateGPUParticles.GetValueOnAnyThread())
	{
		return;
	}

	SCOPE_CYCLE_COUNTER(STAT_GPUParticlesSimulationCommands);
	SCOPED_DRAW_EVENT(RHICmdList, ParticleSimulation);

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

Scope (from outer to inner):

file
function     void ClearTiles

Source code excerpt:

void ClearTiles(FRHICommandList& RHICmdList, FGraphicsPipelineStateInitializer& GraphicsPSOInit, ERHIFeatureLevel::Type FeatureLevel, const TArray<uint32>& Tiles, const FParticleSimulationResources* ParticleSimulationResources)
{
	if (!CVarSimulateGPUParticles.GetValueOnAnyThread())
	{
		return;
	}

	SCOPED_DRAW_EVENT(RHICmdList, ClearTiles);
	SCOPED_GPU_STAT(RHICmdList, ParticleSimulation);

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

Scope (from outer to inner):

file
function     void InjectNewParticles

Source code excerpt:

void InjectNewParticles(FRHICommandList& RHICmdList, FGraphicsPipelineStateInitializer& GraphicsPSOInit,  ERHIFeatureLevel::Type FeatureLevel, const TArray<FNewParticle>& NewParticles, const FParticleSimulationResources* ParticleSimulationResources)
{
	if (GIsRenderingThreadSuspended.Load(EMemoryOrder::Relaxed) || !CVarSimulateGPUParticles.GetValueOnAnyThread())
	{
		return;
	}

	const int32 MaxParticlesPerDrawCall = GParticleScratchVertexBufferSize / sizeof(FNewParticle);
	FRHIBuffer* ScratchVertexBufferRHI = GParticleScratchVertexBuffer.VertexBufferRHI;