r.Shadow.UnbuiltWholeSceneDynamicShadowRadius

r.Shadow.UnbuiltWholeSceneDynamicShadowRadius

#Overview

name: r.Shadow.UnbuiltWholeSceneDynamicShadowRadius

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.Shadow.UnbuiltWholeSceneDynamicShadowRadius is to set the radius for whole scene dynamic shadows when using Cascaded Shadow Maps (CSM) to preview unbuilt lighting from a directional light. This setting is part of Unreal Engine’s rendering system, specifically the shadow rendering subsystem.

This setting variable is primarily used in the Engine module, particularly within the DirectionalLightComponent. It’s referenced in the DirectionalLightSceneProxy class, which is responsible for representing directional lights in the rendering scene.

The value of this variable is set as a console variable with a default value of 200000.0f. It can be modified at runtime through the console or configuration files.

The associated variable CVarUnbuiltWholeSceneDynamicShadowRadius interacts directly with r.Shadow.UnbuiltWholeSceneDynamicShadowRadius. They share the same value and purpose.

Developers should be aware that this variable is specifically used for unbuilt lighting scenarios. It affects the shadow radius when precomputed lighting is not valid or available, which is typically during level editing or when dynamic lighting changes occur.

Best practices for using this variable include:

  1. Adjusting it carefully to balance between shadow quality and performance, especially in large open environments.
  2. Consider the scale of your game world when modifying this value, as it directly affects the coverage area of dynamic shadows.
  3. Use it in conjunction with r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades for fine-tuning shadow quality in unbuilt lighting scenarios.

Regarding the associated variable CVarUnbuiltWholeSceneDynamicShadowRadius:

The purpose of CVarUnbuiltWholeSceneDynamicShadowRadius is identical to r.Shadow.UnbuiltWholeSceneDynamicShadowRadius. It’s an internal representation of the console variable used within the C++ code.

This variable is used directly in the Engine module, specifically in the DirectionalLightSceneProxy class. It’s accessed through the GetEffectiveWholeSceneDynamicShadowRadius function, which determines whether to use the precomputed lighting value or this unbuilt value.

The value is set when the TAutoConsoleVariable is initialized, but can be changed at runtime through console commands.

CVarUnbuiltWholeSceneDynamicShadowRadius interacts directly with the WholeSceneDynamicShadowRadius member of the DirectionalLightSceneProxy class.

Developers should be aware that this variable is used in the rendering code path and changes to it will affect runtime performance and visual quality.

Best practices include:

  1. Modifying this value through the console variable r.Shadow.UnbuiltWholeSceneDynamicShadowRadius rather than directly in code.
  2. Profiling the impact of changes to this value on both visual quality and performance.
  3. Considering the interplay between this variable and other shadow-related settings for optimal results.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarUnbuiltWholeSceneDynamicShadowRadius(
	TEXT("r.Shadow.UnbuiltWholeSceneDynamicShadowRadius"),
	200000.0f,
	TEXT("WholeSceneDynamicShadowRadius to use when using CSM to preview unbuilt lighting from a directional light")
	);

static TAutoConsoleVariable<int32> CVarUnbuiltNumWholeSceneDynamicShadowCascades(
	TEXT("r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<float> CVarUnbuiltWholeSceneDynamicShadowRadius(
	TEXT("r.Shadow.UnbuiltWholeSceneDynamicShadowRadius"),
	200000.0f,
	TEXT("WholeSceneDynamicShadowRadius to use when using CSM to preview unbuilt lighting from a directional light")
	);

static TAutoConsoleVariable<int32> CVarUnbuiltNumWholeSceneDynamicShadowCascades(

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

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     float GetEffectiveWholeSceneDynamicShadowRadius

Source code excerpt:

	float GetEffectiveWholeSceneDynamicShadowRadius(bool bPrecomputedLightingIsValid) const
	{
		return bPrecomputedLightingIsValid ? WholeSceneDynamicShadowRadius : CVarUnbuiltWholeSceneDynamicShadowRadius.GetValueOnAnyThread();
	}

	uint32 GetNumShadowMappedCascades(uint32 MaxShadowCascades, bool bPrecomputedLightingIsValid) const
	{
		int32 EffectiveNumDynamicShadowCascades = DynamicShadowCascades;
		if (!bPrecomputedLightingIsValid)