r.HDR.UI.Luminance

r.HDR.UI.Luminance

#Overview

name: r.HDR.UI.Luminance

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HDR.UI.Luminance is to set the base luminance in nits for UI elements when compositing them into an HDR framebuffer. This setting is primarily used in the rendering system, specifically for handling UI elements in HDR environments.

This setting variable is relied upon by the Unreal Engine’s rendering subsystem, particularly in the SlateRHIRenderer module and the PostProcess module. It’s used in the process of compositing UI elements into HDR framebuffers and in selection outline post-processing.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 300.0f nits, but can be changed at runtime through console commands or programmatically.

The r.HDR.UI.Luminance variable interacts closely with another variable called r.HDR.UI.Level. The luminance value gets multiplied by the UI level to determine the final luminance of UI elements in HDR.

Developers should be aware that this variable directly affects the brightness of UI elements in HDR rendering. Incorrect values could lead to UI elements being too bright or too dim in HDR displays.

Best practices when using this variable include:

  1. Carefully tuning the value to ensure UI readability across different HDR displays.
  2. Testing the UI appearance on various HDR-capable devices to ensure consistency.
  3. Considering the interaction with r.HDR.UI.Level when adjusting this value.

Regarding the associated variable CVarHDRUILuminance:

This is the actual console variable object that holds the r.HDR.UI.Luminance value. It’s used throughout the codebase to retrieve the current value of r.HDR.UI.Luminance.

The purpose of CVarHDRUILuminance is to provide a programmatic interface to access and modify the r.HDR.UI.Luminance value. It’s used in various parts of the rendering pipeline to fetch the current luminance value for UI elements.

This variable is typically used in shader parameter setting functions and in post-processing passes. It’s important for developers to use this variable to access the luminance value, rather than hardcoding values, to ensure consistency with user or runtime adjustments to the setting.

Best practices for using CVarHDRUILuminance include:

  1. Always use GetValueOnRenderThread() when accessing the value in render thread code.
  2. Be aware that the value can change at runtime, so fetch it every frame if needed, rather than caching it.
  3. Use this variable in conjunction with other HDR-related variables for a cohesive HDR rendering setup.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/SlateRHIRenderer/Private/SlateRHIRenderer.cpp:78

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarHDRUILuminance(
	TEXT("r.HDR.UI.Luminance"),
	300.0f,
	TEXT("Base Luminance in nits for UI elements when compositing into HDR framebuffer. Gets multiplied by r.HDR.UI.Level"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarUICompositeMode(
	TEXT("r.HDR.UI.CompositeMode"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessSelectionOutline.cpp:299

Scope: file

Source code excerpt:

		}

		static const auto CVarHDRUILuminance = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.UI.Luminance"));
		float UILuminance = CVarHDRUILuminance ? CVarHDRUILuminance->GetValueOnRenderThread() : 300.0f;
		PassParameters->UILuminanceAndIsSCRGB = bIsSCRGB ? UILuminance : -UILuminance;

		FSelectionOutlinePS::FPermutationDomain PermutationVector;
		FCompositePrimitiveShaderBase::FPermutationDomain PermutationVectorBase;
		PermutationVectorBase.Set<FSelectionOutlinePS::FSampleCountDimension>(NumSamples);

#Loc: <Workspace>/Engine/Source/Runtime/SlateRHIRenderer/Private/SlatePostProcessor.cpp:91

Scope (from outer to inner):

file
class        class FBlitUIToHDRPSBase : public FGlobalShader
function     void SetParameters

Source code excerpt:

		SetTextureParameter(BatchedParameters, UITexture, UISampler, TStaticSamplerState<SF_Bilinear>::GetRHI(), UITextureRHI);
		static auto CVarHDRUILevel = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.UI.Level"));
		static auto CVarHDRUILuminance = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.UI.Luminance"));
		SetShaderValue(BatchedParameters, UILevel, CVarHDRUILevel ? CVarHDRUILevel->GetFloat() : 1.0f);
		SetShaderValue(BatchedParameters, UILuminance, CVarHDRUILuminance ? CVarHDRUILuminance->GetFloat() : 300.0f);
		SetShaderValue(BatchedParameters, UITextureSize, InUITextureSize);
		if (UITextureWriteMaskRHI != nullptr)
		{
			SetTextureParameter(BatchedParameters, UIWriteMaskTexture, UITextureWriteMaskRHI);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessSelectionOutline.cpp:299

Scope: file

Source code excerpt:

		}

		static const auto CVarHDRUILuminance = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.UI.Luminance"));
		float UILuminance = CVarHDRUILuminance ? CVarHDRUILuminance->GetValueOnRenderThread() : 300.0f;
		PassParameters->UILuminanceAndIsSCRGB = bIsSCRGB ? UILuminance : -UILuminance;

		FSelectionOutlinePS::FPermutationDomain PermutationVector;
		FCompositePrimitiveShaderBase::FPermutationDomain PermutationVectorBase;
		PermutationVectorBase.Set<FSelectionOutlinePS::FSampleCountDimension>(NumSamples);
		PermutationVector.Set<FCompositePrimitiveShaderBase::FPermutationDomain>(PermutationVectorBase);

#Loc: <Workspace>/Engine/Source/Runtime/SlateRHIRenderer/Private/SlatePostProcessor.cpp:91

Scope (from outer to inner):

file
class        class FBlitUIToHDRPSBase : public FGlobalShader
function     void SetParameters

Source code excerpt:

		SetTextureParameter(BatchedParameters, UITexture, UISampler, TStaticSamplerState<SF_Bilinear>::GetRHI(), UITextureRHI);
		static auto CVarHDRUILevel = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.UI.Level"));
		static auto CVarHDRUILuminance = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HDR.UI.Luminance"));
		SetShaderValue(BatchedParameters, UILevel, CVarHDRUILevel ? CVarHDRUILevel->GetFloat() : 1.0f);
		SetShaderValue(BatchedParameters, UILuminance, CVarHDRUILuminance ? CVarHDRUILuminance->GetFloat() : 300.0f);
		SetShaderValue(BatchedParameters, UITextureSize, InUITextureSize);
		if (UITextureWriteMaskRHI != nullptr)
		{
			SetTextureParameter(BatchedParameters, UIWriteMaskTexture, UITextureWriteMaskRHI);
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/SlateRHIRenderer/Private/SlateRHIRenderer.cpp:77

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarHDRUILuminance(
	TEXT("r.HDR.UI.Luminance"),
	300.0f,
	TEXT("Base Luminance in nits for UI elements when compositing into HDR framebuffer. Gets multiplied by r.HDR.UI.Level"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarUICompositeMode(

#Loc: <Workspace>/Engine/Source/Runtime/SlateRHIRenderer/Private/SlateRHIRenderer.cpp:775

Scope (from outer to inner):

file
class        class FCompositeShaderBase : public FGlobalShader
function     void SetParametersBase

Source code excerpt:

		SetShaderValue(BatchedParameters, UILevel, CVarUILevel.GetValueOnRenderThread());
		SetShaderValue(BatchedParameters, OutputDevice, CVarOutputDevice->GetValueOnRenderThread());
		SetShaderValue(BatchedParameters, UILuminance, CVarHDRUILuminance.GetValueOnRenderThread());

		if (UITextureWriteMaskRHI != nullptr)
		{
			SetTextureParameter(BatchedParameters, UIWriteMaskTexture, UITextureWriteMaskRHI);
		}
	}