r.DFDistanceScale

r.DFDistanceScale

#Overview

name: r.DFDistanceScale

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.DFDistanceScale is to scale the distance field shadows distance for directional lights in Unreal Engine’s rendering system. This variable allows developers to adjust the range of distance field shadows without modifying the actual light properties directly.

This setting variable is primarily used in the rendering system, specifically for directional light components. It’s part of the Engine module, as evidenced by its location in the DirectionalLightComponent.cpp file.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1.0f, which means no scaling is applied by default. Developers can change this value at runtime using console commands or through code.

The r.DFDistanceScale variable interacts directly with the DistanceFieldShadowDistance property of directional lights. It’s used as a multiplier to adjust the final distance used for distance field shadows.

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

  1. The value is clamped between 0.0001 and 10000.
  2. Values less than 1 will decrease the shadow distance, while values greater than 1 will increase it.
  3. Changes to this variable will affect all directional lights in the scene.

Best practices for using this variable include:

  1. Use it for global adjustments to distance field shadow distances, rather than per-light tweaks.
  2. Be cautious when setting extreme values, as they may impact performance or visual quality.
  3. Consider exposing this setting in your game’s graphics options for users to adjust based on their hardware capabilities.

Regarding the associated variable CVarRTDFDistanceScale:

This is the actual console variable object that holds the value of r.DFDistanceScale. It’s used internally by the engine to access and modify the scale value. The purpose of CVarRTDFDistanceScale is to provide a programmatic interface for the r.DFDistanceScale setting.

CVarRTDFDistanceScale is used within the FDirectionalLightSceneProxy class to retrieve the current scale value on the render thread. This ensures that the most up-to-date value is used when calculating the final distance field shadow distance.

Developers should be aware that CVarRTDFDistanceScale is a render thread-safe variable, meaning its value should be accessed using GetValueOnRenderThread() when used in rendering code.

Best practices for CVarRTDFDistanceScale include:

  1. Use GetValueOnRenderThread() when accessing the value in render thread code.
  2. Avoid directly modifying this variable; instead, use the r.DFDistanceScale console command or appropriate engine functions to change the value.
  3. Remember that changes to this variable will affect all instances where r.DFDistanceScale is used.

#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:88

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarRTDFDistanceScale(
	TEXT("r.DFDistanceScale"),
	1.0f,
	TEXT("Factor to scale directional light property 'DistanceField Shadows Distance', clamped to [0.0001, 10000].\n")
	TEXT("I.e.: DistanceFieldShadowsDistance *= r.DFDistanceScale.\n")	
	TEXT("[0.0001,1): shorter distance\n")
	TEXT(" 1: normal (default)\n")
	TEXT("(1,10000]: larger distance.)"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarRTDFDistanceScale(
	TEXT("r.DFDistanceScale"),
	1.0f,
	TEXT("Factor to scale directional light property 'DistanceField Shadows Distance', clamped to [0.0001, 10000].\n")
	TEXT("I.e.: DistanceFieldShadowsDistance *= r.DFDistanceScale.\n")	
	TEXT("[0.0001,1): shorter distance\n")
	TEXT(" 1: normal (default)\n")

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

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     float GetDistanceFieldShadowDistance

Source code excerpt:

		}

		return DistanceFieldShadowDistance * FMath::Clamp(CVarRTDFDistanceScale.GetValueOnRenderThread(), 0.0001f, 10000.0f);
	}

	float GetShadowTransitionScale() const
	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.Shadow.CSM.TransitionScale"));
		float Scale = FMath::Clamp(CVar->GetValueOnRenderThread(), 0.0f, 2.0f);