GPUSort.DebugOffsets

GPUSort.DebugOffsets

#Overview

name: GPUSort.DebugOffsets

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 GPUSort.DebugOffsets is to enable debugging of GPU sort offsets in Unreal Engine 5’s GPU sorting system. This setting variable is primarily used for the rendering system, specifically for debugging the GPU-based sorting algorithm.

The Unreal Engine subsystem that relies on this setting variable is the GPU sorting system, which is likely part of the rendering module. This can be inferred from the file location (Engine/Source/Runtime/Engine/Private/GPUSort.cpp) and the nature of the operations being performed.

The value of this variable is set through the console variable system. It’s defined as a static TAutoConsoleVariable with an initial value of 0, which means it’s disabled by default. Developers can change this value at runtime using console commands.

This variable interacts closely with another variable named CVarDebugSort, which is used for debugging the overall GPU sorting process. Both variables are often checked together in the code to determine whether to enable various debugging features.

Developers must be aware that enabling this debug variable may impact performance, as it’s likely to introduce additional debugging overhead in the GPU sorting process. It should primarily be used during development and debugging phases, not in production builds.

Best practices when using this variable include:

  1. Only enable it when actively debugging GPU sort offset issues.
  2. Disable it when performance testing or preparing for release builds.
  3. Use it in conjunction with CVarDebugSort for a more comprehensive debugging experience.

Regarding the associated variable CVarDebugOffsets:

The purpose of CVarDebugOffsets is the same as GPUSort.DebugOffsets, as they are directly linked. It’s the C++ representation of the console variable.

This variable is used throughout the GPU sorting system to check whether offset debugging is enabled. It’s typically accessed using the GetValueOnRenderThread() method, which suggests it’s designed to be safely read from render thread code.

The value of CVarDebugOffsets is set when the console variable GPUSort.DebugOffsets is modified, either through console commands or programmatically.

Developers should be aware that changes to this variable take effect immediately on the render thread, which could affect ongoing GPU sort operations.

Best practices for CVarDebugOffsets are similar to those for GPUSort.DebugOffsets, with the addition that developers should use the appropriate methods (like GetValueOnRenderThread()) when accessing its value to ensure thread safety.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

------------------------------------------------------------------------------*/

static TAutoConsoleVariable<int32> CVarDebugOffsets(TEXT("GPUSort.DebugOffsets"),0,TEXT("Debug GPU sort offsets."));
static TAutoConsoleVariable<int32> CVarDebugSort(TEXT("GPUSort.DebugSort"),0,TEXT("Debug GPU sorting."));

#define GPUSORT_BITCOUNT 32
#define RADIX_BITS 4
#define DIGIT_COUNT (1 << RADIX_BITS)
#define KEYS_PER_LOOP 8

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

Scope (from outer to inner):

file
function     static void RunGPUSortTestWithDebug

Source code excerpt:

static void RunGPUSortTestWithDebug(FRHICommandListImmediate& RHICmdList, int32 TestSize, ERHIFeatureLevel::Type FeatureLevel)
{
	static IConsoleVariable* IVarDebugOffsets = IConsoleManager::Get().FindConsoleVariable(TEXT("GPUSort.DebugOffsets"));
	static IConsoleVariable* IVarDebugSort = IConsoleManager::Get().FindConsoleVariable(TEXT("GPUSort.DebugSort"));
	const bool bWasDebuggingOffsets = CVarDebugOffsets.GetValueOnRenderThread() != 0;
	const bool bWasDebuggingSort = CVarDebugSort.GetValueOnRenderThread() != 0;
	IVarDebugOffsets->Set(1, ECVF_SetByCode);
	IVarDebugSort->Set(1, ECVF_SetByCode);
	RunGPUSortTest(RHICmdList, TestSize, FeatureLevel);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

------------------------------------------------------------------------------*/

static TAutoConsoleVariable<int32> CVarDebugOffsets(TEXT("GPUSort.DebugOffsets"),0,TEXT("Debug GPU sort offsets."));
static TAutoConsoleVariable<int32> CVarDebugSort(TEXT("GPUSort.DebugSort"),0,TEXT("Debug GPU sorting."));

#define GPUSORT_BITCOUNT 32
#define RADIX_BITS 4
#define DIGIT_COUNT (1 << RADIX_BITS)
#define KEYS_PER_LOOP 8

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

Scope (from outer to inner):

file
function     int32 SortGPUBuffers

Source code excerpt:

	FRadixSortParameters SortParameters;
	FRadixSortUniformBufferRef SortUniformBufferRef;
	const bool bDebugOffsets = CVarDebugOffsets.GetValueOnRenderThread() != 0;
	const bool bDebugSort = CVarDebugSort.GetValueOnRenderThread() != 0;

	SCOPED_DRAW_EVENTF(RHICmdList, SortGPU, TEXT("Sort(%d)"), Count);

	// Determine how many tiles need to be sorted.
	const int32 TileCount = Count / TILE_SIZE;

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

Scope (from outer to inner):

file
function     static bool RunGPUSortTest

Source code excerpt:

	int32 IncorrectKeyIndex = 0;
	const int32 BufferSize = TestSize * sizeof(uint32);
	const bool bDebugOffsets = CVarDebugOffsets.GetValueOnRenderThread() != 0;
	const bool bDebugSort = CVarDebugSort.GetValueOnRenderThread() != 0;

	// Generate the test keys.
	Keys.Reserve(TestSize);
	Keys.AddUninitialized(TestSize);
	for (int32 KeyIndex = 0; KeyIndex < TestSize; ++KeyIndex)

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

Scope (from outer to inner):

file
function     static void RunGPUSortTestWithDebug

Source code excerpt:

	static IConsoleVariable* IVarDebugOffsets = IConsoleManager::Get().FindConsoleVariable(TEXT("GPUSort.DebugOffsets"));
	static IConsoleVariable* IVarDebugSort = IConsoleManager::Get().FindConsoleVariable(TEXT("GPUSort.DebugSort"));
	const bool bWasDebuggingOffsets = CVarDebugOffsets.GetValueOnRenderThread() != 0;
	const bool bWasDebuggingSort = CVarDebugSort.GetValueOnRenderThread() != 0;
	IVarDebugOffsets->Set(1, ECVF_SetByCode);
	IVarDebugSort->Set(1, ECVF_SetByCode);
	RunGPUSortTest(RHICmdList, TestSize, FeatureLevel);
	IVarDebugOffsets->Set(bWasDebuggingOffsets ? 1 : 0, ECVF_SetByCode);
	IVarDebugSort->Set(bWasDebuggingSort ? 1 : 0, ECVF_SetByCode);