r.HeightFieldShadowing

r.HeightFieldShadowing

#Overview

name: r.HeightFieldShadowing

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.HeightFieldShadowing is to control whether the height field shadowing feature is allowed in the rendering system. This setting variable is part of Unreal Engine’s rendering subsystem and is specifically related to shadow rendering techniques.

The Unreal Engine subsystems that rely on this setting variable are primarily the Renderer module and the Engine module, as evidenced by the callsites in DistanceFieldShadowing.cpp and DirectionalLightComponent.cpp.

The value of this variable is set through the console variable system. It’s defined as a static integer GHeightFieldShadowing and linked to the console variable “r.HeightFieldShadowing” using FAutoConsoleVariableRef.

This variable interacts with other rendering-related variables, particularly r.DistanceFieldShadowing. In the DirectionalLightComponent.cpp file, we can see that both these variables are checked to determine whether to create a ray-traced cascade for directional lights.

Developers must be aware that this variable is a scalability setting (ECVF_Scalability) and is render thread safe (ECVF_RenderThreadSafe). It’s a boolean flag (0 or 1) that determines if height field shadowing is allowed.

Best practices when using this variable include:

  1. Consider performance implications when enabling height field shadowing.
  2. Use in conjunction with other shadow-related settings for optimal results.
  3. Be aware of the platform and feature level requirements (SM5 and above) when utilizing this feature.

Regarding the associated variable GHeightFieldShadowing:

The purpose of GHeightFieldShadowing is to store the actual value of the r.HeightFieldShadowing setting within the C++ code. It’s an internal representation of the console variable.

This variable is used in the Renderer module, specifically in the DistanceFieldShadowing.cpp file.

The value of GHeightFieldShadowing is set by the console variable system when r.HeightFieldShadowing is modified.

GHeightFieldShadowing interacts directly with the SupportsHeightFieldShadows function, which checks if height field shadows are supported based on this variable and other conditions.

Developers should be aware that GHeightFieldShadowing is the actual variable used in the code logic, while r.HeightFieldShadowing is the exposed console variable.

Best practices for GHeightFieldShadowing include:

  1. Use it for internal checks rather than modifying it directly.
  2. Remember that it reflects the current state of the r.HeightFieldShadowing setting.
  3. Consider it in conjunction with other requirements (feature level, shader platform) when determining if height field shadows are supported.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 GHeightFieldShadowing = 0;
FAutoConsoleVariableRef CVarHeightFieldShadowing(
	TEXT("r.HeightFieldShadowing"),
	GHeightFieldShadowing,
	TEXT("Whether the height field shadowing feature is allowed."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

int32 GHFShadowQuality = 2;
FAutoConsoleVariableRef CVarHFShadowQuality(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/DirectionalLightComponent.cpp:550

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     virtual bool ShouldCreateRayTracedCascade

Source code excerpt:

	{
		static auto CVarDistanceFieldShadowing = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DistanceFieldShadowing"));
		static IConsoleVariable* CVarHFShadowing = IConsoleManager::Get().FindConsoleVariable(TEXT("r.HeightFieldShadowing"));

		if (CVarDistanceFieldShadowing != nullptr && CVarDistanceFieldShadowing->GetInt() == 0 && (!CVarHFShadowing || !CVarHFShadowing->GetInt()))
		{
			return false;
		}

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static int32 GHeightFieldShadowing = 0;
FAutoConsoleVariableRef CVarHeightFieldShadowing(
	TEXT("r.HeightFieldShadowing"),
	GHeightFieldShadowing,
	TEXT("Whether the height field shadowing feature is allowed."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

int32 GHFShadowQuality = 2;
FAutoConsoleVariableRef CVarHFShadowQuality(
	TEXT("r.HFShadowQuality"),

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

Scope (from outer to inner):

file
function     bool SupportsHeightFieldShadows

Source code excerpt:

bool SupportsHeightFieldShadows(ERHIFeatureLevel::Type FeatureLevel, EShaderPlatform ShaderPlatform)
{
	return GHeightFieldShadowing
		&& GetHFShadowQuality() > 0
		&& FeatureLevel >= ERHIFeatureLevel::SM5
		&& DoesPlatformSupportDistanceFieldShadowing(ShaderPlatform);
}

bool FSceneRenderer::ShouldPrepareForDistanceFieldShadows() const