r.DFFarTransitionScale

r.DFFarTransitionScale

#Overview

name: r.DFFarTransitionScale

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DFFarTransitionScale is to modify the length of the far transition (fade out) of distance field shadows in Unreal Engine’s rendering system. This setting variable is specifically used for controlling the behavior of ray-traced directional light shadows.

This setting variable is primarily used in the Engine module, specifically within the DirectionalLightComponent. It affects the rendering of distance field shadows for directional lights.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined with a default value of 1.0f, but can be modified at runtime through console commands or programmatically.

The r.DFFarTransitionScale variable interacts directly with CVarRtdfFarTransitionScale, which is the associated console variable. They share the same value and purpose.

Developers must be aware that this variable only affects ray-traced distance field shadows for directional lights. It doesn’t impact other types of shadows or non-ray-traced shadow techniques. The value range is effectively 0.0 to 1.0, where 0.0 disables the fade-out effect, and 1.0 (the default) calculates the fade-out in the same way as other shadow cascades.

Best practices when using this variable include:

  1. Use it to fine-tune the appearance of distance field shadows, especially in scenes with long-range visibility.
  2. Be cautious when setting values close to or at 0.0, as it may create abrupt shadow endings.
  3. Consider the performance impact when adjusting this value, as it affects the extent of shadow calculations.

Regarding the associated variable CVarRtdfFarTransitionScale:

The purpose of CVarRtdfFarTransitionScale is identical to r.DFFarTransitionScale. It’s the actual console variable implementation that controls the distance field shadow far transition scale.

This variable is used in the Engine module, specifically within the DirectionalLightComponent, to affect the calculation of shadow split bounds for directional lights.

The value of CVarRtdfFarTransitionScale is set when the r.DFFarTransitionScale console command is used. It’s initialized with the same default value (1.0f) and description as r.DFFarTransitionScale.

CVarRtdfFarTransitionScale directly interacts with the shadow calculation logic in the FDirectionalLightSceneProxy class. It’s used to modify the FadeExtension calculation for ray-traced cascades.

Developers should be aware that this variable is accessed on the render thread, as indicated by the ECVF_RenderThreadSafe flag. Any changes to this variable will affect rendering in real-time.

Best practices for CVarRtdfFarTransitionScale are the same as for r.DFFarTransitionScale, given they represent the same setting. Developers should use the r.DFFarTransitionScale console command to modify this value during development and testing, rather than accessing CVarRtdfFarTransitionScale directly in code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarRtdfFarTransitionScale(
	TEXT("r.DFFarTransitionScale"),
	1.0f,
	TEXT("Use to modify the length of the far transition (fade out) of the distance field shadows.\n")
	TEXT("1.0: (default) Calculate in the same way as other cascades.")
	TEXT("0.0: Disable fade out."),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<float> CVarRtdfFarTransitionScale(
	TEXT("r.DFFarTransitionScale"),
	1.0f,
	TEXT("Use to modify the length of the far transition (fade out) of the distance field shadows.\n")
	TEXT("1.0: (default) Calculate in the same way as other cascades.")
	TEXT("0.0: Disable fade out."),
	ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     virtual FSphere GetShadowSplitBounds

Source code excerpt:

			if (bIsRayTracedCascade)
			{
				FadeExtension *= FMath::Clamp(CVarRtdfFarTransitionScale.GetValueOnAnyThread(), 0.0f, 1.0f);
			}
			// For the last cascade, we want to fade out to avoid a hard line, since there is no further cascade to overlap with, 
			// extending the far makes little sense as extending the shadow range would be counter intuitive and affect performance. 
			// Thus, move the fade plane closer:
			FadePlane -= FadeExtension;
		}