r.Shadow.DistanceScale

r.Shadow.DistanceScale

#Overview

name: r.Shadow.DistanceScale

The value of this variable can be defined or overridden in .ini config files. 14 .ini config files referencing this setting variable.

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.Shadow.DistanceScale is to provide a scalability option for adjusting the distance at which shadows are rendered for directional lights. This variable allows developers to balance shadow quality and performance by controlling the shadow rendering distance.

This setting variable is primarily used in the rendering system of Unreal Engine 5, specifically for shadow calculations related to directional lights. It is referenced in the engine’s core rendering module and the Movie Render Pipeline plugin.

The value of this variable is set through the console variable system. It is defined as a TAutoConsoleVariable with a default value of 1.0f, which represents the normal shadow distance. Values less than 1 result in shorter shadow distances, while values greater than 1 increase the shadow rendering distance.

Other variables that interact with r.Shadow.DistanceScale include r.ShadowQuality and r.Shadow.RadiusThreshold, which are often adjusted together to achieve optimal shadow rendering quality and performance.

Developers must be aware that this variable affects the performance-quality trade-off for shadow rendering. Increasing the value will result in shadows being rendered at greater distances, potentially improving visual quality but at the cost of performance. Conversely, decreasing the value will improve performance but may reduce shadow quality at a distance.

Best practices when using this variable include:

  1. Adjusting it in conjunction with other shadow-related variables for a balanced approach to shadow quality and performance.
  2. Testing different values to find the optimal balance for your specific game or application.
  3. Considering the target hardware when setting this value, as higher-end systems may be able to handle larger shadow distances.
  4. Using it as part of a broader scalability strategy, allowing users to adjust shadow quality based on their system capabilities.
  5. Being cautious when increasing the value significantly, as it can have a substantial impact on performance, especially on lower-end hardware.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:903, section: [Android_Vulkan_SM5 DeviceProfile]

Location: <Workspace>/Engine/Config/BaseScalability.ini:134, section: [ShadowQuality@0]

Location: <Workspace>/Engine/Config/BaseScalability.ini:158, section: [ShadowQuality@1]

Location: <Workspace>/Engine/Config/BaseScalability.ini:182, section: [ShadowQuality@2]

Location: <Workspace>/Engine/Config/BaseScalability.ini:209, section: [ShadowQuality@3]

Location: <Workspace>/Engine/Config/BaseScalability.ini:236, section: [ShadowQuality@Cine]

Location: <Workspace>/Engine/Config/Android/AndroidScalability.ini:51, section: [ShadowQuality@0]

Location: <Workspace>/Engine/Config/Android/AndroidScalability.ini:60, section: [ShadowQuality@1]

Location: <Workspace>/Engine/Config/Android/AndroidScalability.ini:69, section: [ShadowQuality@2]

Location: <Workspace>/Engine/Config/Android/AndroidScalability.ini:78, section: [ShadowQuality@3]

Location: <Workspace>/Engine/Config/IOS/IOSScalability.ini:51, section: [ShadowQuality@0]

Location: <Workspace>/Engine/Config/IOS/IOSScalability.ini:60, section: [ShadowQuality@1]

Location: <Workspace>/Engine/Config/IOS/IOSScalability.ini:69, section: [ShadowQuality@2]

Location: <Workspace>/Engine/Config/IOS/IOSScalability.ini:78, section: [ShadowQuality@3]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/HAL/ConsoleManager.cpp:4015

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarShadowDistanceScale(
	TEXT("r.Shadow.DistanceScale"),
	1.0f,
	TEXT("Scalability option to trade shadow distance versus performance for directional lights (clamped within a reasonable range).\n"
		 "<1: shorter distance\n"
		 " 1: normal (default)\n"
		 ">1: larger distance"),
	ECVF_Scalability | ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineCore/Private/MoviePipelineGameOverrideSetting.cpp:82

Scope (from outer to inner):

file
function     void UMoviePipelineGameOverrideSetting::ApplyCVarSettings

Source code excerpt:

	if (bUseHighQualityShadows)
	{
		MOVIEPIPELINE_STORE_AND_OVERRIDE_CVAR_INT(PreviousShadowDistanceScale, TEXT("r.Shadow.DistanceScale"), ShadowDistanceScale, bOverrideValues);
		MOVIEPIPELINE_STORE_AND_OVERRIDE_CVAR_INT(PreviousShadowQuality, TEXT("r.ShadowQuality"), 5, bOverrideValues);
		MOVIEPIPELINE_STORE_AND_OVERRIDE_CVAR_FLOAT(PreviousShadowRadiusThreshold, TEXT("r.Shadow.RadiusThreshold"), ShadowRadiusThreshold, bOverrideValues);
	}

	if (bOverrideViewDistanceScale)
	{

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineCore/Private/MoviePipelineGameOverrideSetting.cpp:205

Scope (from outer to inner):

file
function     void UMoviePipelineGameOverrideSetting::BuildNewProcessCommandLineArgsImpl

Source code excerpt:

	if (bUseHighQualityShadows)
	{
		InOutDeviceProfileCvars.Add(FString::Printf(TEXT("r.Shadow.DistanceScale=%d"), ShadowDistanceScale));
		InOutDeviceProfileCvars.Add(FString::Printf(TEXT("r.Shadow.RadiusThreshold=%f"), ShadowRadiusThreshold));
		InOutDeviceProfileCvars.Add(TEXT("r.ShadowQuality=5"));
	}

	if (bOverrideViewDistanceScale)
	{

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

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     float GetCSMMaxDistance

Source code excerpt:

	float GetCSMMaxDistance(bool bPrecomputedLightingIsValid, int32 MaxShadowCascades) const
	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.Shadow.DistanceScale"));
		
		if (MaxShadowCascades <= 0)
		{
			return 0.0f;
		}