t.HitchFrameTimeThreshold

t.HitchFrameTimeThreshold

#Overview

name: t.HitchFrameTimeThreshold

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 t.HitchFrameTimeThreshold is to define the threshold for identifying a hitchy frame in the Unreal Engine’s performance monitoring system. It is used primarily for reporting purposes, such as in FPS charts, and is not intended for use in scalability code.

This setting variable is primarily used by the Engine’s performance monitoring and statistics subsystems. Based on the callsites, it’s utilized in the Core and Engine modules of Unreal Engine.

The value of this variable is set through a console variable (CVar) named “t.HitchFrameTimeThreshold”. It’s associated with the engine-wide variable GHitchThresholdMS, which shares the same value.

The variable interacts closely with GHitchThresholdMS, which is defined in the engine’s core globals. It’s used in various parts of the engine to determine if a frame should be considered a hitch.

Developers should be aware that this variable is primarily for reporting purposes and should not be used for game logic or scalability code. It’s important to note that changing this value will affect what the engine considers a “hitchy” frame, which could impact performance reports and diagnostics.

Best practices when using this variable include:

  1. Leaving it at its default value (60.0 ms) unless there’s a specific need to change it.
  2. Using it only for performance monitoring and debugging purposes.
  3. Being consistent across the project if the value is changed, to ensure uniform hitch detection.

Regarding the associated variable GHitchThresholdMS:

The purpose of GHitchThresholdMS is to store the actual threshold value for identifying hitchy frames. It’s a float value representing the threshold in milliseconds.

This variable is used in the Core module of Unreal Engine, particularly in performance monitoring and statistics gathering systems.

The value of GHitchThresholdMS is set through the t.HitchFrameTimeThreshold console variable, which allows for runtime modification.

GHitchThresholdMS interacts directly with t.HitchFrameTimeThreshold and is used in various parts of the engine to determine if a frame should be considered a hitch.

Developers should be aware that this variable is used directly in performance-critical code, such as in the stats system for identifying hitches.

Best practices for GHitchThresholdMS include:

  1. Avoiding direct modification of this variable in code; instead, use the t.HitchFrameTimeThreshold console variable.
  2. Being cautious when changing this value, as it directly affects how the engine identifies performance issues.
  3. Considering the target platform and game requirements when adjusting this value, as what constitutes a “hitch” may vary depending on the context.

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

Scope: file

Source code excerpt:

// (*cosmetic only* for reporting purposes such as FPS charts, should not be used in scalability code)
FAutoConsoleVariableRef GHitchFrameTimeThresholdCVar(
	TEXT("t.HitchFrameTimeThreshold"),
	GHitchThresholdMS,
	TEXT("Definition of a hitchy frame (in ms)\n")
	TEXT(" default: 60.0 ms"),
	ECVF_Scalability);

// Minimum time passed before we'll record a new hitch

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/CoreGlobals.cpp:421

Scope: file

Source code excerpt:

PRAGMA_ENABLE_DEPRECATION_WARNINGS
/** Threshold for a frame to be considered a hitch (in milliseconds). */
float GHitchThresholdMS = 60.0f;
/** Size to break up data into when saving compressed data													*/
int32					GSavingCompressionChunkSize		= SAVING_COMPRESSION_CHUNK_SIZE;
/** Thread ID of the main/game thread																		*/
uint32					GGameThreadId					= 0;
uint32					GRenderThreadId					= 0;
uint32					GSlateLoadingThreadId			= 0;

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Stats/StatsCommand.cpp:680

Scope (from outer to inner):

file
function     static void DumpHitch

Source code excerpt:

	const double GameThreadTime = FPlatformTime::ToSeconds((uint32)Stats.GetFastThreadFrameTime(Frame, EThreadType::Game));
	const double RenderThreadTime = FPlatformTime::ToSeconds((uint32)Stats.GetFastThreadFrameTime(Frame, EThreadType::Renderer));
	const float HitchThresholdSecs = GHitchThresholdMS * 0.001f;

	if ((GameThreadTime > HitchThresholdSecs) || (RenderThreadTime > HitchThresholdSecs))
	{
		HitchIndex++;
		double ThisHitch = FMath::Max<double>(GameThreadTime, RenderThreadTime) * 1000.0;
		TotalHitchTime += ThisHitch;

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/CoreGlobals.h:541

Scope: file

Source code excerpt:


/** Threshold for a frame to be considered a hitch (in milliseconds). */
extern CORE_API float GHitchThresholdMS;

/** Size to break up data into when saving compressed data */
extern CORE_API int32 GSavingCompressionChunkSize;

/** Thread ID of the main/game thread */
extern CORE_API uint32 GGameThreadId;

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

Scope: file

Source code excerpt:

FAutoConsoleVariableRef GHitchFrameTimeThresholdCVar(
	TEXT("t.HitchFrameTimeThreshold"),
	GHitchThresholdMS,
	TEXT("Definition of a hitchy frame (in ms)\n")
	TEXT(" default: 60.0 ms"),
	ECVF_Scalability);

// Minimum time passed before we'll record a new hitch
TAutoConsoleVariable<float> GHitchDeadTimeWindowCVar(

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

Scope (from outer to inner):

file
function     float FEnginePerformanceTargets::GetHitchFrameTimeThresholdMS

Source code excerpt:

float FEnginePerformanceTargets::GetHitchFrameTimeThresholdMS()
{
	return GHitchThresholdMS;
}

float FEnginePerformanceTargets::GetMinTimeBetweenHitchesMS()
{
	return GHitchDeadTimeWindowCVar.GetValueOnGameThread();
}