FX.TestGPUSort

FX.TestGPUSort

#Overview

name: FX.TestGPUSort

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of FX.TestGPUSort is to test the GPU sorting functionality in Unreal Engine’s particle system. It is primarily used for debugging and performance testing of the GPU-based particle sorting algorithm.

This setting variable is mainly used in the Engine module, specifically within the particle system and GPU sorting subsystems. The code references are found in the FXSystem.cpp and GPUSort.cpp files, which are part of the core engine’s particle effects system.

The value of this variable is set through a console command. It’s defined as a TAutoConsoleVariable with default value 0, and can be changed at runtime. The variable accepts integer values from 0 to 4, each representing a different test case for GPU sorting: 0: No test (default) 1: Small test 2: Large test 3: Exhaustive test 4: Random test

FX.TestGPUSort interacts with the TestGPUSort function, which is called in the FFXSystem::Tick method when the variable’s value is non-zero. After running the test, the variable is reset to 0.

Developers should be aware that:

  1. This is a cheat command (ECVF_Cheat), meant for testing and debugging purposes only.
  2. Using this variable will trigger a GPU sort test, which may impact performance while running.
  3. The test is executed on the render thread, so results may not be immediately visible.

Best practices for using this variable include:

  1. Use it only for debugging or performance testing purposes.
  2. Be cautious when using it in production builds, as it may affect game performance.
  3. Remember to reset the value to 0 after testing, although the engine does this automatically.

Regarding the associated variable TestGPUSort:

This is the actual function that performs the GPU sorting test. It takes an EGPUSortTest enum value (corresponding to the console variable’s integer value) and the current feature level as parameters. The function enqueues a render command to execute the sorting test on the render thread.

Developers should note that this function is called directly by the FXSystem when the console variable is set. There’s no need to call it manually unless implementing custom GPU sorting tests.

Best practices for TestGPUSort include:

  1. Ensure it’s only called in appropriate debugging or testing scenarios.
  2. Be aware of the potential performance impact, especially for larger or more exhaustive tests.
  3. Use the results to optimize GPU particle sorting in your specific use cases.

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	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"),
		VisualizeGPUSimulation,
		TEXT("Visualize the current state of GPU simulation.\n")

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

Scope (from outer to inner):

file
function     void FFXSystem::Tick

Source code excerpt:

			TestGPUSort((EGPUSortTest)FXConsoleVariables::TestGPUSort.GetValueOnGameThread(), GetFeatureLevel());
			// Reset CVar
			static IConsoleVariable* CVarTestGPUSort = IConsoleManager::Get().FindConsoleVariable(TEXT("FX.TestGPUSort"));

			// todo: bad use of console variables, this should be a console command 
			CVarTestGPUSort->Set(0, ECVF_SetByCode);
		}

		// Before ticking GPU particles, ensure any pending curves have been

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GPUSort.cpp:919

Scope (from outer to inner):

file
function     void TestGPUSort

Source code excerpt:

 * @param TestToRun - The test to run.
 */
void TestGPUSort(EGPUSortTest TestToRun, ERHIFeatureLevel::Type FeatureLevel)
{
	ENQUEUE_RENDER_COMMAND(FTestGPUSortCommand)(
		[TestToRun, FeatureLevel](FRHICommandListImmediate& RHICmdList)
		{
			TestGPUSort_RenderThread(RHICmdList, TestToRun, FeatureLevel);
		});

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	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"),
		VisualizeGPUSimulation,
		TEXT("Visualize the current state of GPU simulation.\n")

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

Scope (from outer to inner):

file
function     void FFXSystem::Tick

Source code excerpt:

	{
		// Test GPU sorting if requested.
		if (FXConsoleVariables::TestGPUSort.GetValueOnGameThread() != 0)
		{
			TestGPUSort((EGPUSortTest)FXConsoleVariables::TestGPUSort.GetValueOnGameThread(), GetFeatureLevel());
			// Reset CVar
			static IConsoleVariable* CVarTestGPUSort = IConsoleManager::Get().FindConsoleVariable(TEXT("FX.TestGPUSort"));

			// todo: bad use of console variables, this should be a console command 
			CVarTestGPUSort->Set(0, ECVF_SetByCode);
		}

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

Scope (from outer to inner):

file
namespace    FXConsoleVariables

Source code excerpt:

	extern float GPUCollisionDepthBounds;
	/** Specify a sorting test to run. */
	extern TAutoConsoleVariable<int32> TestGPUSort;
	/** true if GPU particles are allowed. */
	extern int32 bAllowGPUParticles;
}

/**
 * Returns true if the shader platform supports GPU particles.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/GPUSort.h:69

Scope: file

Source code excerpt:

 * @param TestToRun - The test to run.
 */
void TestGPUSort(EGPUSortTest TestToRun, ERHIFeatureLevel::Type FeatureLevel);