r.GTSyncType

r.GTSyncType

#Overview

name: r.GTSyncType

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.GTSyncType is to determine how the game thread synchronizes with other threads and the GPU in Unreal Engine 5. It’s primarily used for managing frame synchronization and latency in the rendering system.

This setting variable is relied upon by the rendering subsystem of Unreal Engine, specifically in the RenderCore and Engine modules. It’s used to control the synchronization behavior between different threads (game thread, render thread, RHI thread) and the GPU.

The value of this variable is set through the console variable system. It can be set programmatically using the SetSyncTypeCVar function in the UGameUserSettings class, or through the console command system.

The r.GTSyncType variable interacts closely with the r.VSync variable. When r.GTSyncType is set to 2 (sync with GPU swap chain flip), the engine also checks if VSync is enabled.

Developers must be aware that changing this variable can significantly impact frame timing and latency. Different sync types can be more suitable for different scenarios or platforms. For example, syncing to the GPU swap chain flip (type 2) can allow for lower frame latency but may not be supported on all platforms.

Best practices when using this variable include:

  1. Testing different sync types to find the optimal setting for your specific game and target platforms.
  2. Being aware of the interaction with VSync settings.
  3. Considering the trade-offs between latency and consistency when choosing a sync type.

Regarding the associated variable CVarGTSyncType:

The purpose of CVarGTSyncType is to provide a programmatic interface to the r.GTSyncType setting within the C++ code of Unreal Engine.

It’s used in the RenderCore module to define the console variable and in various parts of the engine to read the current sync type setting.

The value of CVarGTSyncType is set when the r.GTSyncType console variable is defined, and it’s read using the GetValueOnAnyThread() or GetInt() methods.

CVarGTSyncType interacts directly with r.GTSyncType, essentially serving as its in-code representation.

Developers should be aware that CVarGTSyncType provides thread-safe access to the sync type setting, which is important when dealing with multi-threaded rendering code.

Best practices for using CVarGTSyncType include:

  1. Using GetValueOnAnyThread() when accessing the value from potentially any thread.
  2. Caching the IConsoleVariable* pointer for repeated access rather than looking it up each time.
  3. Being aware that changes to this variable can affect rendering behavior significantly, so it should be used carefully in performance-critical code paths.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderingThread.cpp:1102

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarGTSyncType(
	TEXT("r.GTSyncType"),
	0,
	TEXT("Determines how the game thread syncs with the render thread, RHI thread and GPU.\n")
	TEXT("Syncing to the GPU swap chain flip allows for lower frame latency.\n")
	TEXT(" 0 - Sync the game thread with the render thread (default).\n")
	TEXT(" 1 - Sync the game thread with the RHI thread.\n")
	TEXT(" 2 - Sync the game thread with the GPU swap chain flip (only on supported platforms).\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameUserSettings.cpp:340

Scope (from outer to inner):

file
function     void UGameUserSettings::SetSyncTypeCVar

Source code excerpt:

void UGameUserSettings::SetSyncTypeCVar(int32 InType)
{
	static IConsoleVariable* SyncIntervalCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GTSyncType"));
	if (ensure(SyncIntervalCVar))
	{
		SyncIntervalCVar->Set(InType, ECVF_SetByCode);
	}
}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:679

Scope (from outer to inner):

file
function     void CalculateFPSTimings

Source code excerpt:

	float FrameTimeMS = (float)((CurrentTime - LastTime) * 1000.0);

	static auto CVarGTSyncType = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GTSyncType"));
	static auto CVarVsync = IConsoleManager::Get().FindConsoleVariable(TEXT("r.VSync"));
	if (CVarGTSyncType->GetInt() == 2 && CVarVsync->GetInt() != 0)
	{
		float RHIFrameTime = RHIGetFrameTime();
		if (RHIFrameTime != 0)
		{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:679

Scope (from outer to inner):

file
function     void CalculateFPSTimings

Source code excerpt:

	float FrameTimeMS = (float)((CurrentTime - LastTime) * 1000.0);

	static auto CVarGTSyncType = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GTSyncType"));
	static auto CVarVsync = IConsoleManager::Get().FindConsoleVariable(TEXT("r.VSync"));
	if (CVarGTSyncType->GetInt() == 2 && CVarVsync->GetInt() != 0)
	{
		float RHIFrameTime = RHIGetFrameTime();
		if (RHIFrameTime != 0)
		{
			FrameTimeMS = RHIFrameTime;
		}

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderingThread.cpp:1101

Scope: file

Source code excerpt:

}

TAutoConsoleVariable<int32> CVarGTSyncType(
	TEXT("r.GTSyncType"),
	0,
	TEXT("Determines how the game thread syncs with the render thread, RHI thread and GPU.\n")
	TEXT("Syncing to the GPU swap chain flip allows for lower frame latency.\n")
	TEXT(" 0 - Sync the game thread with the render thread (default).\n")
	TEXT(" 1 - Sync the game thread with the RHI thread.\n")

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderingThread.cpp:1209

Scope (from outer to inner):

file
function     void FRenderCommandFence::BeginFence

Source code excerpt:

	}

	const int32 GTSyncType = CVarGTSyncType.GetValueOnAnyThread();

	if (bSyncToRHIAndGPU)
	{
		// Don't sync to the RHI and GPU if GtSyncType is disabled, or we're not vsyncing
		//@TODO: do this logic in the caller?
		static auto CVarVsync = IConsoleManager::Get().FindConsoleVariable(TEXT("r.VSync"));