rhi.PresentThreshold.Top

rhi.PresentThreshold.Top

#Overview

name: rhi.PresentThreshold.Top

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of rhi.PresentThreshold.Top is to specify the percentage of the screen from the top where tearing is allowed during frame presentation. This setting is part of the Rendering Hardware Interface (RHI) subsystem in Unreal Engine 5.

This setting variable is primarily used by the RHI module, which is responsible for abstracting the graphics hardware interface. It’s specifically related to the frame presentation and vsync mechanisms.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with a default value of 0.0f, and it can be changed at runtime through console commands or configuration files.

This variable interacts closely with another variable called rhi.PresentThreshold.Bottom. Together, they define a region of the screen where tearing is allowed during frame presentation.

Developers must be aware that this setting is only effective on supported platforms. The valid range for this variable is between 0.0 and 1.0, representing the percentage of the screen height from the top.

Best practices when using this variable include:

  1. Only modify it if you understand the implications on frame presentation and tearing.
  2. Use it in conjunction with rhi.PresentThreshold.Bottom for consistent results.
  3. Be aware that values outside the 0.0 to 1.0 range will be clamped.

The associated variable CVarRHIPresentThresholdTop is the actual console variable object that stores and manages the value of rhi.PresentThreshold.Top. It’s used internally by the engine to access and modify the setting.

The purpose of CVarRHIPresentThresholdTop is to provide a programmatic interface for the rhi.PresentThreshold.Top setting. It allows the engine to read and write the value, as well as register it with the console variable system.

This variable is used in the RHI module, specifically in the RHIGetPresentThresholds function, which retrieves both the top and bottom thresholds for present operations.

The value of CVarRHIPresentThresholdTop is set when the console variable is registered, and it can be modified through the console or programmatically.

CVarRHIPresentThresholdTop interacts with CVarRHIPresentThresholdBottom, as they are often used together to define the full present threshold range.

Developers should be aware that accessing CVarRHIPresentThresholdTop directly bypasses any potential clamping or validation that might be done when accessing rhi.PresentThreshold.Top through other means.

Best practices for using CVarRHIPresentThresholdTop include:

  1. Prefer using engine-provided functions like RHIGetPresentThresholds instead of accessing the CVar directly when possible.
  2. When reading the value, use the GetValueOnAnyThread() method for thread-safe access.
  3. Be cautious when modifying this variable directly, as it could affect the engine’s rendering behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHIUtilities.cpp:87

Scope: file

Source code excerpt:


TAutoConsoleVariable<float> CVarRHIPresentThresholdTop(
	TEXT("rhi.PresentThreshold.Top"),
	0.0f,
	TEXT("Specifies the percentage of the screen from the top where tearing is allowed.\n")
	TEXT("Only effective on supported platforms.\n")
	TEXT("Range: 0.0 - 1.0\n"),
	ECVF_Default
);

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Public/RHIUtilities.h:621

Scope: file

Source code excerpt:

extern RHI_API float RHIGetSyncSlackMS();

/** Returns the top and bottom vsync present thresholds (the values of rhi.PresentThreshold.Top and rhi.PresentThreshold.Bottom) */
extern RHI_API void RHIGetPresentThresholds(float& OutTopPercent, float& OutBottomPercent);

/** Returns the value of the rhi.SyncAllowVariable CVar. */
extern RHI_API bool RHIGetSyncAllowVariable();

/** Signals the completion of the specified task graph event when the given frame has flipped. */

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHIUtilities.cpp:86

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<float> CVarRHIPresentThresholdTop(
	TEXT("rhi.PresentThreshold.Top"),
	0.0f,
	TEXT("Specifies the percentage of the screen from the top where tearing is allowed.\n")
	TEXT("Only effective on supported platforms.\n")
	TEXT("Range: 0.0 - 1.0\n"),
	ECVF_Default

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHIUtilities.cpp:536

Scope (from outer to inner):

file
function     void RHIGetPresentThresholds

Source code excerpt:

void RHIGetPresentThresholds(float& OutTopPercent, float& OutBottomPercent)
{
	OutTopPercent = FMath::Clamp(CVarRHIPresentThresholdTop.GetValueOnAnyThread(), 0.0f, 1.0f);
	OutBottomPercent = FMath::Clamp(CVarRHIPresentThresholdBottom.GetValueOnAnyThread(), 0.0f, 1.0f);
}

void RHITriggerTaskEventOnFlip(uint64 PresentIndex, const UE::Tasks::FTaskEvent& Event)
{
	FRHIFrameFlipTrackingRunnable::TriggerTaskEventOnFlip(PresentIndex, Event);