r.GPUStatsChildTimesIncluded

r.GPUStatsChildTimesIncluded

#Overview

name: r.GPUStatsChildTimesIncluded

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GPUStatsChildTimesIncluded is to control whether child stat timings are included in their parents’ times when recording GPU statistics. This setting is primarily used for GPU profiling and performance analysis.

This setting variable is utilized by the Unreal Engine’s rendering and profiling subsystems, specifically within the RenderCore module. It’s primarily used in the RealtimeGPUProfiler component, which is responsible for collecting and analyzing GPU performance data.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0 (disabled) but can be changed at runtime through console commands or configuration files.

The associated variable CVarGPUStatsChildTimesIncluded directly interacts with r.GPUStatsChildTimesIncluded. They share the same value and purpose, with CVarGPUStatsChildTimesIncluded being the actual TAutoConsoleVariable object used in the code to access and modify the setting.

Developers must be aware that enabling this variable (setting it to 1) can lead to potential issues when analyzing non-hierarchical stats. When enabled, the total GPU time calculated may not accurately represent the sum of individual stat timings, as child timings would be counted multiple times (in both their own stat and their parent’s stat).

Best practices when using this variable include:

  1. Keeping it disabled (set to 0) for most performance analysis scenarios, especially when working with non-hierarchical stats.
  2. Only enabling it when a detailed hierarchical view of GPU stats is required and the potential double-counting of time is accounted for in the analysis.
  3. Being cautious when comparing total GPU times with this setting enabled versus disabled, as the results will differ.
  4. Documenting clearly when this setting is enabled during performance profiling sessions to avoid misinterpretation of results.

Regarding the associated variable CVarGPUStatsChildTimesIncluded:

The purpose of CVarGPUStatsChildTimesIncluded is to provide a programmatic interface to control the r.GPUStatsChildTimesIncluded setting within the Unreal Engine codebase.

This variable is used directly in the RenderCore module, specifically in the RealtimeGPUProfiler component. It’s accessed in the UpdateStats function of the FRealtimeGPUProfilerFrame class to determine how GPU stat timings should be calculated and reported.

The value of CVarGPUStatsChildTimesIncluded is set through the TAutoConsoleVariable system, which allows it to be modified at runtime via console commands or configuration files.

CVarGPUStatsChildTimesIncluded interacts directly with the r.GPUStatsChildTimesIncluded setting, effectively serving as its in-code representation.

Developers should be aware that this variable is accessed on the render thread (GetValueOnRenderThread()), which implies that changes to this setting may not take effect immediately and could be subject to frame delays.

Best practices for using CVarGPUStatsChildTimesIncluded include:

  1. Accessing its value using the GetValueOnRenderThread() method when used within rendering code to ensure thread-safe access.
  2. Considering the performance implications of frequently querying this value in performance-critical code paths.
  3. Using this variable in conjunction with other GPU profiling tools and settings to get a comprehensive view of GPU performance.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int> CVarGPUStatsChildTimesIncluded(
	TEXT("r.GPUStatsChildTimesIncluded"),
	0,
	TEXT("If this is enabled, the child stat timings will be included in their parents' times.\n")
	TEXT("This presents problems for non-hierarchical stats if we're expecting them to add up\n")
	TEXT("to the total GPU time, so we probably want this disabled.\n")
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	TEXT("Enables or disables GPU stat recording to tracing profiler"));

static TAutoConsoleVariable<int> CVarGPUStatsChildTimesIncluded(
	TEXT("r.GPUStatsChildTimesIncluded"),
	0,
	TEXT("If this is enabled, the child stat timings will be included in their parents' times.\n")
	TEXT("This presents problems for non-hierarchical stats if we're expecting them to add up\n")
	TEXT("to the total GPU time, so we probably want this disabled.\n")
);

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

Scope (from outer to inner):

file
class        class FRealtimeGPUProfilerFrame
function     bool UpdateStats

Source code excerpt:

		FCsvProfiler* CsvProfiler = bCsvStatsEnabled ? FCsvProfiler::Get() : nullptr;
#endif
		const bool GPUStatsChildTimesIncluded = !!CVarGPUStatsChildTimesIncluded.GetValueOnRenderThread();
		uint64 TotalUs = 0llu;
		FNameSet StatSeenSet;

		for (int32 Idx = 1; Idx < NumEventsThisFramePlusOne; ++Idx)
		{
			const FRealtimeGPUProfilerEvent& Event = GpuProfilerEvents[Idx];