r.Shadow.TexelsPerPixelRectlight

r.Shadow.TexelsPerPixelRectlight

#Overview

name: r.Shadow.TexelsPerPixelRectlight

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

• type: Var
• help: The ratio of subject pixels to shadow texels for rect lights

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.TexelsPerPixelRectlight is to control the ratio of subject pixels to shadow texels for rect lights in the Unreal Engine 5 rendering system. This setting variable is specifically used to determine the resolution of shadows cast by rectangular lights.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evidenced by its location in the ShadowSetup.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set as a console variable using TAutoConsoleVariable, with a default value of 1.27324f. This means it can be adjusted at runtime through console commands or configuration files.

The associated variable CVarShadowTexelsPerPixelRectlight directly interacts with r.Shadow.TexelsPerPixelRectlight, as they share the same value and purpose. This variable is used in the code to retrieve the current value of the setting.

Developers must be aware that this variable specifically affects rectangular lights and their shadow quality. Adjusting this value will impact the performance and visual quality of shadows cast by rect lights.

Best practices when using this variable include:

1. Balancing between shadow quality and performance by adjusting the value.
2. Testing different values to find the optimal setting for your specific scene and hardware targets.
3. Considering the impact on different platforms, as higher values may affect performance on less powerful devices.

Regarding the associated variable CVarShadowTexelsPerPixelRectlight:

The purpose of CVarShadowTexelsPerPixelRectlight is to provide a programmatic way to access and modify the r.Shadow.TexelsPerPixelRectlight setting within the C++ code of Unreal Engine 5.

This variable is used in the Renderer module, specifically in the shadow setup and creation process for whole scene projected shadows.

The value of this variable is set through the TAutoConsoleVariable initialization, which links it to the r.Shadow.TexelsPerPixelRectlight console variable.

CVarShadowTexelsPerPixelRectlight interacts directly with the r.Shadow.TexelsPerPixelRectlight setting, serving as the in-code representation of this console variable.

Developers should be aware that this variable is used to calculate the UnclampedResolution for rect light shadows in the CreateWholeSceneProjectedShadow function. Changes to this variable will directly affect shadow resolution calculations.

Best practices for using CVarShadowTexelsPerPixelRectlight include:

1. Using GetValueOnRenderThread() when accessing the value to ensure thread-safety.
2. Considering the performance implications of shadow resolution changes when modifying this value.
3. Documenting any custom logic that modifies this variable to maintain code clarity.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:223

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelRectlight(
	TEXT("r.Shadow.TexelsPerPixelRectlight"),
	1.27324f,
	TEXT("The ratio of subject pixels to shadow texels for rect lights"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPreShadowFadeResolution(
	TEXT("r.Shadow.PreShadowFadeResolution"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:222

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelRectlight(
	TEXT("r.Shadow.TexelsPerPixelRectlight"),
	1.27324f,
	TEXT("The ratio of subject pixels to shadow texels for rect lights"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPreShadowFadeResolution(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:4094

Scope (from outer to inner):

file
function     void FSceneRenderer::CreateWholeSceneProjectedShadow

Source code excerpt:

				break;
			case LightType_Rect:
				UnclampedResolution = ScreenRadius * CVarShadowTexelsPerPixelRectlight.GetValueOnRenderThread();
				break;
			default:
				// directional lights are not handled here
				checkf(false, TEXT("Unexpected LightType %d appears in CreateWholeSceneProjectedShadow %s"),
					(int32)LightSceneInfo->Proxy->GetLightType(),
					*LightSceneInfo->Proxy->GetOwnerNameOrLabel());