t.HitchVersusNonHitchRatio

t.HitchVersusNonHitchRatio

#Overview

name: t.HitchVersusNonHitchRatio

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 t.HitchVersusNonHitchRatio is to define a threshold for identifying frame hitches in the game’s performance. It is used by the engine’s performance monitoring system to detect when a frame takes significantly longer to process than the previous frame, potentially causing a noticeable stutter or “hitch” in gameplay.

This setting variable is primarily used by the Engine module, specifically within the performance monitoring and targeting subsystem. It’s part of the engine’s efforts to maintain smooth frame rates and identify performance issues.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 1.5, meaning a frame must take at least 1.5 times longer than the previous frame to be considered a hitch.

The t.HitchVersusNonHitchRatio interacts with other performance-related variables, particularly t.HitchFrameTimeThreshold and t.TargetFrameTimeThreshold. These variables work together to determine the final ratio used for hitch detection.

Developers should be aware that the actual ratio used for hitch detection is clamped between the value of t.HitchVersusNonHitchRatio and the ratio of t.HitchFrameTimeThreshold to t.TargetFrameTimeThreshold. This ensures that the hitch detection remains within reasonable bounds.

Best practices when using this variable include:

  1. Adjusting it carefully based on the specific needs of your game.
  2. Considering it in conjunction with other performance-related settings.
  3. Using it as part of a broader performance monitoring strategy.

The associated variable GHitchVersusNonHitchMinimumRatioCVar is the actual CVar object that stores and manages the t.HitchVersusNonHitchRatio value. It’s used internally by the engine to access and modify the ratio value. This variable is of type TAutoConsoleVariable, which allows it to be easily accessed and modified through the console or code.

The GHitchVersusNonHitchMinimumRatioCVar is used in the FEnginePerformanceTargets::GetHitchToNonHitchRatio function to retrieve the current value of the ratio. This function also applies the clamping behavior mentioned earlier, ensuring the final ratio used for hitch detection is within the appropriate range.

When working with GHitchVersusNonHitchMinimumRatioCVar, developers should:

  1. Use the GetValueOnGameThread() method to safely retrieve its value.
  2. Be aware that changes to this variable will affect the engine’s hitch detection sensitivity.
  3. Consider exposing it to game settings if fine-tuning performance is important for your project.

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

Scope: file

Source code excerpt:

// For the current frame to be considered a hitch, it must have run at least this many times slower than the previous frame
TAutoConsoleVariable<float> GHitchVersusNonHitchMinimumRatioCVar(
	TEXT("t.HitchVersusNonHitchRatio"),
	1.5f,
	TEXT("For the current frame to be considered a hitch, it must have run at least this many times slower than the previous frame.\nThe actual ratio is clamped to be between this and t.HitchFrameTimeThreshold/t.TargetFrameTimeThreshold\n")
	TEXT(" default: 1.5"),
	ECVF_Scalability);

//////////////////////////////////////////////////////////////////////

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


// For the current frame to be considered a hitch, it must have run at least this many times slower than the previous frame
TAutoConsoleVariable<float> GHitchVersusNonHitchMinimumRatioCVar(
	TEXT("t.HitchVersusNonHitchRatio"),
	1.5f,
	TEXT("For the current frame to be considered a hitch, it must have run at least this many times slower than the previous frame.\nThe actual ratio is clamped to be between this and t.HitchFrameTimeThreshold/t.TargetFrameTimeThreshold\n")
	TEXT(" default: 1.5"),
	ECVF_Scalability);

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

Scope (from outer to inner):

file
function     float FEnginePerformanceTargets::GetHitchToNonHitchRatio

Source code excerpt:

	const float MaximumRatio = GetHitchFrameTimeThresholdMS() / GetTargetFrameTimeThresholdMS();

	return FMath::Clamp(GHitchVersusNonHitchMinimumRatioCVar.GetValueOnGameThread(), MinimumRatio, MaximumRatio);
}