r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades

r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades

#Overview

name: r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades

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.UnbuiltNumWholeSceneDynamicShadowCascades is to control the number of dynamic shadow cascades used when previewing unbuilt lighting from a directional light using Cascaded Shadow Maps (CSM).

This setting variable is primarily used by the rendering system, specifically for shadow rendering in Unreal Engine 5. It is utilized within the DirectionalLightComponent, which is part of the Engine module.

The value of this variable is set through a console variable (CVarUnbuiltNumWholeSceneDynamicShadowCascades) with a default value of 4. It can be modified at runtime through the console or programmatically.

The associated variable CVarUnbuiltNumWholeSceneDynamicShadowCascades directly interacts with r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades, as they share the same value and purpose.

Developers must be aware that this variable only affects the preview of unbuilt lighting from directional lights. It does not impact built lighting or other types of lights. Additionally, its effect is limited to scenes where precomputed lighting is not valid.

Best practices when using this variable include:

  1. Adjusting it to balance between shadow quality and performance in unbuilt scenes.
  2. Considering the target hardware capabilities when setting this value.
  3. Using it in conjunction with other shadow-related settings for optimal results.

Regarding the associated variable CVarUnbuiltNumWholeSceneDynamicShadowCascades:

The purpose of CVarUnbuiltNumWholeSceneDynamicShadowCascades is to provide a programmatic way to access and modify the r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades setting.

This variable is used within the Engine module, specifically in the DirectionalLightComponent and its associated FDirectionalLightSceneProxy class.

The value of CVarUnbuiltNumWholeSceneDynamicShadowCascades is set when the console variable is created, with a default value of 4. It can be accessed and modified at runtime using the GetValueOnAnyThread() method.

CVarUnbuiltNumWholeSceneDynamicShadowCascades interacts directly with r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades, as they represent the same setting.

Developers should be aware that this variable is thread-safe (ECVF_RenderThreadSafe) and can be accessed from any thread.

Best practices for using CVarUnbuiltNumWholeSceneDynamicShadowCascades include:

  1. Using GetValueOnAnyThread() to retrieve the current value safely.
  2. Considering performance implications when modifying this value at runtime.
  3. Ensuring that any code depending on this value is prepared to handle changes dynamically.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarUnbuiltNumWholeSceneDynamicShadowCascades(
	TEXT("r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades"),
	4,
	TEXT("DynamicShadowCascades to use when using CSM to preview unbuilt lighting from a directional light"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarCSMShadowDistanceFadeoutMultiplier(
	TEXT("r.Shadow.CSMShadowDistanceFadeoutMultiplier"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<int32> CVarUnbuiltNumWholeSceneDynamicShadowCascades(
	TEXT("r.Shadow.UnbuiltNumWholeSceneDynamicShadowCascades"),
	4,
	TEXT("DynamicShadowCascades to use when using CSM to preview unbuilt lighting from a directional light"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarCSMShadowDistanceFadeoutMultiplier(

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

Scope (from outer to inner):

file
class        class FDirectionalLightSceneProxy : public FLightSceneProxy
function     uint32 GetNumShadowMappedCascades

Source code excerpt:

		if (!bPrecomputedLightingIsValid)
		{
			EffectiveNumDynamicShadowCascades = FMath::Max(0, CVarUnbuiltNumWholeSceneDynamicShadowCascades.GetValueOnAnyThread());

			static const auto CVarUnbuiltPreviewShadowsInGame = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.UnbuiltPreviewInGame"));
			bool bUnbuiltPreviewShadowsInGame = CVarUnbuiltPreviewShadowsInGame->GetInt() != 0;

			if (!bUnbuiltPreviewShadowsInGame && !GetSceneInterface()->IsEditorScene())
			{