r.HDR.EnableHDROutput

r.HDR.EnableHDROutput

#Overview

name: r.HDR.EnableHDROutput

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

It is referenced in 12 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HDR.EnableHDROutput is to control the creation of an HDR-compatible swap chain and enable HDR display output in Unreal Engine 5. This setting variable is primarily used for the rendering system, specifically for High Dynamic Range (HDR) output.

This setting variable is relied upon by several Unreal Engine subsystems and modules:

  1. The RenderCore module, where it’s defined and used to determine if HDR is enabled.
  2. The Engine module, particularly in the GameUserSettings class for managing HDR display output settings.
  3. The BinkMediaPlayer plugin, which uses this variable to adjust its rendering based on HDR settings.

The value of this variable is set in multiple places:

  1. It’s initially defined with a default value of 0 (disabled) in RenderCore.cpp.
  2. It can be set through the game’s user settings (GameUserSettings.cpp).
  3. It can be modified through console commands or game code.

This variable interacts with several other variables related to HDR settings, such as:

Developers must be aware of the following when using this variable:

  1. It’s render thread safe, meaning it can be accessed safely from the render thread.
  2. The actual enabling of HDR output depends on hardware support (GRHISupportsHDROutput).
  3. Changing this setting may require recreating the swap chain, which can be a heavyweight operation.

Best practices when using this variable include:

  1. Check for hardware support before enabling HDR output.
  2. Consider the performance implications of enabling HDR, especially on lower-end hardware.
  3. Provide user options to enable/disable HDR in the game settings.
  4. Test the game thoroughly with both HDR enabled and disabled to ensure correct rendering in all scenarios.

Regarding the associated variable CVarHDROutputEnabled:

This is the actual console variable object that corresponds to the r.HDR.EnableHDROutput setting. It’s used throughout the code to access and modify the HDR output setting. The purpose and usage are the same as r.HDR.EnableHDROutput, but CVarHDROutputEnabled provides the programmatic interface to interact with the setting.

Developers should use CVarHDROutputEnabled when they need to read or write the HDR output setting in C++ code. For example, to check if HDR is enabled, they would use:

if (CVarHDROutputEnabled->GetValueOnRenderThread() != 0)
{
    // HDR is enabled
}

Or to enable HDR programmatically:

CVarHDROutputEnabled->Set(1, ECVF_SetByCode);

It’s important to use the appropriate thread-safe getter (GetValueOnRenderThread, GetValueOnAnyThread, etc.) depending on the context where the variable is being accessed.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarHDROutputEnabled(
	TEXT("r.HDR.EnableHDROutput"),
	0,
	TEXT("Creates an HDR compatible swap-chain and enables HDR display output.")
	TEXT("0: Disabled (default)\n")
	TEXT("1: Enable hardware-specific implementation\n"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Plugins/Media/BinkMedia/Source/BinkMediaPlayer/Private/BinkMovieStreamer.cpp:128

Scope (from outer to inner):

file
function     bool FBinkMovieStreamer::Tick

Source code excerpt:

		float lry = destLowerRight.Y;

		static const auto CVarHDROutputEnabled = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.EnableHDROutput"));
		static const auto CVarDisplayOutputDevice = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.Display.OutputDevice"));
		if (GRHISupportsHDROutput && CVarHDROutputEnabled->GetValueOnRenderThread() != 0)
		{
			EDisplayOutputFormat outDev = static_cast<EDisplayOutputFormat>(CVarDisplayOutputDevice->GetValueOnRenderThread());
			float DisplayMaxLuminance = HDRGetDisplayMaximumLuminance();
			switch (outDev)

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

Scope (from outer to inner):

file
function     void UGameUserSettings::PreloadResolutionSettings

Source code excerpt:

	{
		// Set the user-preference HDR switch
		static auto CVarHDROutputEnabled = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.EnableHDROutput"));
		if (CVarHDROutputEnabled)
		{
			CVarHDROutputEnabled->Set(bUseHDR ? 1 : 0, ECVF_SetByGameSetting);
		}
	}
#endif

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

Scope (from outer to inner):

file
function     void UGameUserSettings::EnableHDRDisplayOutputInternal

Source code excerpt:

void UGameUserSettings::EnableHDRDisplayOutputInternal(bool bEnable, int32 DisplayNits, bool bFromUserSettings)
{
	static IConsoleVariable* CVarHDROutputEnabled = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.EnableHDROutput"));

	if (CVarHDROutputEnabled)
	{
		if (bEnable && !(GRHISupportsHDROutput && IsHDRAllowed()))
		{
			UE_LOG(LogConsoleResponse, Display, TEXT("Tried to enable HDR display output but unsupported or disallowed, forcing off."));

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

Scope (from outer to inner):

file
function     void HDRSettingChangedSinkCallback

Source code excerpt:

void ENGINE_API HDRSettingChangedSinkCallback()
{
	static const auto CVarHDROutputEnabled = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.EnableHDROutput"));
	check(CVarHDROutputEnabled);
	static const auto CVarHDRMinLuminanceLog10 = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Display.MinLuminanceLog10"));
	static const auto CVarHDRMidLuminance = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Display.MidLuminance"));
	static const auto CVarHDRMaxLuminance = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.Display.MaxLuminance"));
	static const auto CVarHDRSceneColorMultiplier = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Aces.SceneColorMultiplier"));
	static const auto CVarHDRGamutCompression = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Aces.GamutCompression"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Media/BinkMedia/Source/BinkMediaPlayer/Private/BinkMovieStreamer.cpp:128

Scope (from outer to inner):

file
function     bool FBinkMovieStreamer::Tick

Source code excerpt:

		float lry = destLowerRight.Y;

		static const auto CVarHDROutputEnabled = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.EnableHDROutput"));
		static const auto CVarDisplayOutputDevice = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.Display.OutputDevice"));
		if (GRHISupportsHDROutput && CVarHDROutputEnabled->GetValueOnRenderThread() != 0)
		{
			EDisplayOutputFormat outDev = static_cast<EDisplayOutputFormat>(CVarDisplayOutputDevice->GetValueOnRenderThread());
			float DisplayMaxLuminance = HDRGetDisplayMaximumLuminance();
			switch (outDev)
			{
			// LDR

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

Scope (from outer to inner):

file
function     void UGameUserSettings::PreloadResolutionSettings

Source code excerpt:

	{
		// Set the user-preference HDR switch
		static auto CVarHDROutputEnabled = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.EnableHDROutput"));
		if (CVarHDROutputEnabled)
		{
			CVarHDROutputEnabled->Set(bUseHDR ? 1 : 0, ECVF_SetByGameSetting);
		}
	}
#endif

	RequestResolutionChange(ResolutionX, ResolutionY, WindowMode, bAllowCmdLineOverrides);

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

Scope (from outer to inner):

file
function     void UGameUserSettings::EnableHDRDisplayOutputInternal

Source code excerpt:

void UGameUserSettings::EnableHDRDisplayOutputInternal(bool bEnable, int32 DisplayNits, bool bFromUserSettings)
{
	static IConsoleVariable* CVarHDROutputEnabled = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.EnableHDROutput"));

	if (CVarHDROutputEnabled)
	{
		if (bEnable && !(GRHISupportsHDROutput && IsHDRAllowed()))
		{
			UE_LOG(LogConsoleResponse, Display, TEXT("Tried to enable HDR display output but unsupported or disallowed, forcing off."));
			bEnable = false;
		}

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

Scope (from outer to inner):

file
function     void UGameUserSettings::EnableHDRDisplayOutputInternal

Source code excerpt:

			}
#endif
			CVarHDROutputEnabled->Set(1, bFromUserSettings ? ECVF_SetByGameSetting : ECVF_SetByCode);
		}

		// Always test this branch as can be used to flush errors
		if (!bEnable)
		{
			CVarHDROutputEnabled->Set(0, bFromUserSettings ? ECVF_SetByGameSetting : ECVF_SetByCode);
		}

		// Update final requested state for saved config
#if !PLATFORM_USES_FIXED_HDR_SETTING
		// Do not override the user setting on console (we rely on the OS setting)
		bUseHDRDisplayOutput = bEnable;

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

Scope (from outer to inner):

file
function     void HDRSettingChangedSinkCallback

Source code excerpt:

void ENGINE_API HDRSettingChangedSinkCallback()
{
	static const auto CVarHDROutputEnabled = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.EnableHDROutput"));
	check(CVarHDROutputEnabled);
	static const auto CVarHDRMinLuminanceLog10 = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Display.MinLuminanceLog10"));
	static const auto CVarHDRMidLuminance = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Display.MidLuminance"));
	static const auto CVarHDRMaxLuminance = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.Display.MaxLuminance"));
	static const auto CVarHDRSceneColorMultiplier = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Aces.SceneColorMultiplier"));
	static const auto CVarHDRGamutCompression = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Aces.GamutCompression"));

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarHDROutputEnabled(
	TEXT("r.HDR.EnableHDROutput"),
	0,
	TEXT("Creates an HDR compatible swap-chain and enables HDR display output.")
	TEXT("0: Disabled (default)\n")
	TEXT("1: Enable hardware-specific implementation\n"),
	ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     bool IsHDREnabled

Source code excerpt:

RENDERCORE_API bool IsHDREnabled()
{
	return GRHISupportsHDROutput && CVarHDROutputEnabled.GetValueOnAnyThread() != 0;
}

RENDERCORE_API bool IsHDRAllowed()
{
	// HDR can be forced on or off on the commandline. Otherwise we check the cvar r.AllowHDR
	if (FParse::Param(FCommandLine::Get(), TEXT("hdr")))