r.GPUStatsMaxQueriesPerFrame

r.GPUStatsMaxQueriesPerFrame

#Overview

name: r.GPUStatsMaxQueriesPerFrame

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 r.GPUStatsMaxQueriesPerFrame is to limit the number of GPU timestamp queries allocated per frame for performance profiling and debugging. This setting is part of Unreal Engine’s rendering and profiling system.

This variable is primarily used in the RenderCore module, specifically within the RealtimeGPUProfiler system. It’s also referenced in the D3D12RHI (Direct3D 12 Rendering Hardware Interface) module and the Slate module.

The value of this variable is set through the console variable system. It can be modified at runtime using console commands or through code. By default, it’s set to -1, which means there’s no limit on the number of queries per frame.

The associated variable CVarGPUStatsMaxQueriesPerFrame directly interacts with r.GPUStatsMaxQueriesPerFrame. They share the same value and are used interchangeably in the code.

Developers should be aware of several important points when using this variable:

  1. Setting a limit can help prevent performance issues caused by excessive GPU queries, especially on lower-end hardware.
  2. The variable is render thread safe, meaning it can be safely modified from different threads.
  3. During Blueprint debugging, the Slate system sets this value to 0 to prevent memory leaks.
  4. In the D3D12RHI initialization, the value is set to 8192 if the variable exists.

Best practices for using this variable include:

  1. Leave it at -1 (unlimited) during development for comprehensive profiling data.
  2. Set a reasonable limit (e.g., 8192 as used in D3D12RHI) for release builds to prevent potential performance issues.
  3. Consider dynamically adjusting the value based on the target hardware capabilities.
  4. Be cautious when setting it to 0, as this disables GPU profiling entirely.

Regarding the associated variable CVarGPUStatsMaxQueriesPerFrame:

The purpose of CVarGPUStatsMaxQueriesPerFrame is to provide a programmatic interface to the r.GPUStatsMaxQueriesPerFrame setting. It’s used internally by the RealtimeGPUProfiler system to control the number of GPU queries.

This variable is used in the RenderCore module, specifically within the RealtimeGPUProfiler system. It’s used to determine whether to allocate new GPU profiler events and to initialize the render query pool.

The value is set through the console variable system, mirroring r.GPUStatsMaxQueriesPerFrame.

Developers should be aware that this variable directly affects the allocation of GPU profiler events and the size of the render query pool. Setting it too low might result in incomplete profiling data, while setting it too high might impact performance.

Best practices for CVarGPUStatsMaxQueriesPerFrame are similar to those for r.GPUStatsMaxQueriesPerFrame, as they represent the same setting. Developers should use this variable when they need programmatic access to the setting within C++ code, particularly within the rendering and profiling systems.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ProfilingDebugging/RealtimeGPUProfiler.cpp:24

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int> CVarGPUStatsMaxQueriesPerFrame(
	TEXT("r.GPUStatsMaxQueriesPerFrame"),
	-1,
	TEXT("Limits the number of timestamps allocated per frame. -1 = no limit"), 
	ECVF_RenderThreadSafe);


static TAutoConsoleVariable<int> CVarGPUCsvStatsEnabled(

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12RHI.cpp:237

Scope (from outer to inner):

file
function     FD3D12DynamicRHI::FD3D12DynamicRHI

Source code excerpt:

		// a bit.
		//
		static IConsoleVariable* GPUStatsEnabledCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUStatsMaxQueriesPerFrame"));
		if (GPUStatsEnabledCVar)
		{
			GPUStatsEnabledCVar->Set(8192);
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/Slate/Private/Framework/Application/SlateApplication.cpp:3729

Scope (from outer to inner):

file
function     void FSlateApplication::EnterDebuggingMode

Source code excerpt:


	//Disable GPU Profiler during BluePrint Debugging to prevent leaking memory.
	IConsoleVariable* CvarMaxQueriesPerFrame = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUStatsMaxQueriesPerFrame"));
	int MaxQueriesPerFrame = CvarMaxQueriesPerFrame->GetInt();
	CvarMaxQueriesPerFrame->Set(0);

	// Tick slate from here in the event that we should not return until the modal window is closed.
	while (!bRequestLeaveDebugMode)
	{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ProfilingDebugging/RealtimeGPUProfiler.cpp:23

Scope: file

Source code excerpt:



static TAutoConsoleVariable<int> CVarGPUStatsMaxQueriesPerFrame(
	TEXT("r.GPUStatsMaxQueriesPerFrame"),
	-1,
	TEXT("Limits the number of timestamps allocated per frame. -1 = no limit"), 
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ProfilingDebugging/RealtimeGPUProfiler.cpp:492

Scope (from outer to inner):

file
class        class FRealtimeGPUProfilerFrame
function     FRealtimeGPUProfilerQuery PushEvent

Source code excerpt:

		if (NextEventIdx >= GpuProfilerEvents.Num())
		{
			const int32 MaxNumQueries = CVarGPUStatsMaxQueriesPerFrame.GetValueOnRenderThread();

			if (MaxNumQueries < 0 || QueryCount < (uint32)MaxNumQueries)
			{
				GpuProfilerEvents.Emplace(*RenderQueryPool);
				QueryCount += FRealtimeGPUProfilerEvent::GetNumRHIQueriesPerEvent();
			}

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ProfilingDebugging/RealtimeGPUProfiler.cpp:951

Scope (from outer to inner):

file
function     FRealtimeGPUProfiler::FRealtimeGPUProfiler

Source code excerpt:

	if (GSupportsTimestampRenderQueries)
	{
		const int MaxGPUQueries = CVarGPUStatsMaxQueriesPerFrame.GetValueOnRenderThread();
		RenderQueryPool = RHICreateRenderQueryPool(RQT_AbsoluteTime, (MaxGPUQueries > 0) ? MaxGPUQueries : UINT32_MAX);
		for (int Index = 0; Index < NumGPUProfilerBufferedFrames; Index++)
		{
			Frames.Add(new FRealtimeGPUProfilerFrame(RenderQueryPool, QueryCount));
		}
	}