t.TargetFrameTimeThreshold

t.TargetFrameTimeThreshold

#Overview

name: t.TargetFrameTimeThreshold

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of t.TargetFrameTimeThreshold is to set a target frame time threshold for performance monitoring in Unreal Engine 5. It is primarily used for visual feedback in the engine’s performance display system.

This setting variable is mainly utilized by the Engine module, specifically in the performance monitoring and display subsystems. It’s referenced in the Engine’s performance targets (EnginePerformanceTargets.cpp) and the UnrealClient system (UnrealClient.cpp).

The value of this variable is set as a console variable with a default value of 33.9 milliseconds, which corresponds to approximately 30 frames per second. It can be modified at runtime through the console or programmatically.

This variable interacts closely with another variable called GUnacceptableFrameTimeThresholdCVar (not shown in the provided code snippets). Together, they define the thresholds for acceptable, warning, and unacceptable frame times.

Developers should be aware that this variable is primarily used for cosmetic purposes in fps/stat displays and should not be used directly in scalability code. It’s important to note that changing this value will only affect how performance is visually represented and not the actual performance of the game.

Best practices when using this variable include:

  1. Use it as a visual guide for performance optimization rather than a hard limit.
  2. Consider adjusting it based on your target platform and desired frame rate.
  3. Use in conjunction with GUnacceptableFrameTimeThresholdCVar for a more comprehensive performance monitoring setup.

Regarding the associated variable GTargetFrameTimeThresholdCVar:

The purpose of GTargetFrameTimeThresholdCVar is to provide a programmatic interface to the t.TargetFrameTimeThreshold console variable. It’s an instance of TAutoConsoleVariable, which allows for easy access and modification of the threshold value in C++ code.

This variable is used in the Engine module, specifically in the performance monitoring and display systems. It’s defined in EnginePerformanceTargets.cpp and used in UnrealClient.cpp.

The value of this variable is set when it’s initialized, but it can be changed at runtime using console commands or through C++ code.

GTargetFrameTimeThresholdCVar interacts directly with t.TargetFrameTimeThreshold, as they represent the same value. It’s also used in conjunction with a similar variable for unacceptable frame times.

Developers should be aware that this variable provides a C++ interface to the console variable, allowing for programmatic access and modification of the threshold.

Best practices when using this variable include:

  1. Use GetValueOnGameThread() to retrieve the current value safely.
  2. Consider caching the value if it’s accessed frequently, as reading console variables can have a performance cost.
  3. Be cautious when modifying this value, as it affects how performance is visually represented in the engine’s debug tools.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Performance/EnginePerformanceTargets.cpp:17

Scope: file

Source code excerpt:

// Values below this will be green, values between this and the unacceptable threshold will be yellow, and values above that will be red
TAutoConsoleVariable<float> GTargetFrameTimeThresholdCVar(
	TEXT("t.TargetFrameTimeThreshold"),
	33.9f,
	TEXT("The target frame time (in ms); values below this will be drawn in green, values above will be yellow or red depending on the severity\n")
	TEXT(" default: 33.9 ms"),
	ECVF_Scalability);

// The threshold that would be considered so bad that it would cause a hitch in gameplay

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/Engine.h:2446

Scope: file

Source code excerpt:


	/**
	 * Returns the display color for a given frame time (based on t.TargetFrameTimeThreshold and t.UnacceptableFrameTimeThreshold)
	 */
	ENGINE_API FColor GetFrameTimeDisplayColor(float FrameTimeMS) const;

	/**
	 * @return true to throttle CPU usage based on current state (usually editor minimized or not in foreground)
	 */
	ENGINE_API virtual bool ShouldThrottleCPUUsage() const;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Performance/EnginePerformanceTargets.cpp:16

Scope: file

Source code excerpt:

// The target threshold for frame time in miliseconds (*cosmetic only* and used for fps/stat display, should not be used in scalability code)
// Values below this will be green, values between this and the unacceptable threshold will be yellow, and values above that will be red
TAutoConsoleVariable<float> GTargetFrameTimeThresholdCVar(
	TEXT("t.TargetFrameTimeThreshold"),
	33.9f,
	TEXT("The target frame time (in ms); values below this will be drawn in green, values above will be yellow or red depending on the severity\n")
	TEXT(" default: 33.9 ms"),
	ECVF_Scalability);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Performance/EnginePerformanceTargets.cpp:53

Scope (from outer to inner):

file
function     float FEnginePerformanceTargets::GetTargetFrameTimeThresholdMS

Source code excerpt:

float FEnginePerformanceTargets::GetTargetFrameTimeThresholdMS()
{
	return GTargetFrameTimeThresholdCVar.GetValueOnGameThread();
}

float FEnginePerformanceTargets::GetUnacceptableFrameTimeThresholdMS()
{
	return GUnacceptableFrameTimeThresholdCVar.GetValueOnGameThread();
}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealClient.cpp:911

Scope (from outer to inner):

file
function     int32 FStatUnitData::DrawStat

Source code excerpt:


		// Threshold where graph lines will pulsate for slow frames
		extern TAutoConsoleVariable<float> GTargetFrameTimeThresholdCVar;
		const float TargetTimeMS = GTargetFrameTimeThresholdCVar.GetValueOnGameThread();

		const float AlertTimeMS = TargetTimeMS;

		// Graph layout
		const float GraphHeight = (bSmallGraph ? 120.0f : 350.0f);
#if PLATFORM_ANDROID || PLATFORM_IOS