r.HFShadowQuality

r.HFShadowQuality

#Overview

name: r.HFShadowQuality

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 r.HFShadowQuality is to define the quality level of height field shadows in Unreal Engine’s rendering system. This setting variable allows developers to adjust the trade-off between shadow quality and performance.

The Unreal Engine subsystem that relies on this setting variable is primarily the rendering system, specifically the distance field shadowing module. This can be seen from the file locations where the variable is referenced, such as “DistanceFieldShadowing.cpp” and “DistanceFieldObjectManagement.cpp”.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 2 (medium quality) and can be changed at runtime using console commands or through configuration files.

The variable interacts directly with its associated variable GHFShadowQuality. They share the same value, with r.HFShadowQuality being the console-accessible name and GHFShadowQuality being the actual C++ variable used in the code.

Developers must be aware that this variable has four possible values: 0: Off (no height field shadows) 1: Low quality (8 steps) 2: Medium quality (16 steps, default) 3: High quality (32 steps, hole aware)

The higher the quality, the more computationally expensive the shadowing becomes. Additionally, the highest quality setting (3) enables a “hole aware” feature, which likely provides more accurate shadows for complex geometries.

Best practices when using this variable include:

  1. Use the default medium quality (2) as a starting point.
  2. Adjust based on the specific needs of your scene and target hardware.
  3. Consider using lower quality settings for less powerful hardware or in scenes where shadow quality is less critical.
  4. Use the highest quality setting judiciously, as it may have a significant performance impact.

Regarding the associated variable GHFShadowQuality: This is the internal C++ variable that directly controls the height field shadow quality in the rendering code. It’s used in various parts of the distance field shadowing system to determine the number of steps and features to use in shadow calculations.

Developers should note that while GHFShadowQuality can be accessed directly in C++ code, it’s generally better practice to use the console variable r.HFShadowQuality for runtime adjustments and configuration. The GetHFShadowQuality() function provides a safe way to access this value, ensuring it’s clamped between 0 and 3.

When the quality is set to the highest level (3), additional features like visibility texture atlas updates are triggered, which may have performance implications but provide higher quality shadows.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldShadowing.cpp:105

Scope: file

Source code excerpt:

int32 GHFShadowQuality = 2;
FAutoConsoleVariableRef CVarHFShadowQuality(
	TEXT("r.HFShadowQuality"),
	GHFShadowQuality,
	TEXT("Defines the height field shadow method which allows to adjust for quality or performance.\n")
	TEXT(" 0:off, 1:low (8 steps), 2:medium (16 steps, default), 3:high (32 steps, hole aware)"),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static float GMinDirectionalLightAngleForRTHF = 27.f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldObjectManagement.cpp:912

Scope (from outer to inner):

file
function     void FSceneRenderer::PrepareDistanceFieldScene

Source code excerpt:

	if (bShouldPrepareHeightFieldScene)
	{
		extern int32 GHFShadowQuality;
		if (GHFShadowQuality > 2)
		{
			GHFVisibilityTextureAtlas.UpdateAllocations(GraphBuilder, FeatureLevel);
		}
		GHeightFieldTextureAtlas.UpdateAllocations(GraphBuilder, FeatureLevel);

		UpdateGlobalHeightFieldObjectBuffers(GraphBuilder, IndicesToUpdateInHeightFieldObjectBuffers);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldShadowing.cpp:103

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

int32 GHFShadowQuality = 2;
FAutoConsoleVariableRef CVarHFShadowQuality(
	TEXT("r.HFShadowQuality"),
	GHFShadowQuality,
	TEXT("Defines the height field shadow method which allows to adjust for quality or performance.\n")
	TEXT(" 0:off, 1:low (8 steps), 2:medium (16 steps, default), 3:high (32 steps, hole aware)"),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static float GMinDirectionalLightAngleForRTHF = 27.f;
static FAutoConsoleVariableRef CVarMinDirectionalLightAngleForRTHF(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldShadowing.cpp:698

Scope (from outer to inner):

file
function     int32 GetHFShadowQuality

Source code excerpt:

int32 GetHFShadowQuality()
{
	return FMath::Clamp(GHFShadowQuality, 0, 3);
}

bool SupportsDistanceFieldShadows(ERHIFeatureLevel::Type FeatureLevel, EShaderPlatform ShaderPlatform)
{
	return GDistanceFieldShadowing 
		&& GetDFShadowQuality() > 0