r.Shadow.TexelsPerPixelSpotlight

r.Shadow.TexelsPerPixelSpotlight

#Overview

name: r.Shadow.TexelsPerPixelSpotlight

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

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.TexelsPerPixelSpotlight is to control the ratio of subject pixels to shadow texels for spotlights in the rendering system. This variable is crucial for determining the resolution and quality of shadow maps for spotlight sources.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the shadow setup and rendering subsystem. It’s referenced in the ShadowSetup.cpp file, which is responsible for configuring shadow rendering parameters.

The value of this variable is set as a console variable (CVar) with an initial value of 2.0f * 1.27324f (approximately 2.54648). It can be modified at runtime through the console or configuration files.

The variable interacts closely with other shadow-related variables, particularly those for different light types. For example, there’s a similar variable for rectlights (r.Shadow.TexelsPerPixelRectlight) defined right after it in the source code.

Developers must be aware that this variable directly affects the quality and performance of spotlight shadows. A higher value will result in higher quality shadows but at the cost of increased memory usage and potential performance impact.

Best practices when using this variable include:

1. Balancing quality and performance by adjusting the value based on the specific needs of the game or scene.
2. Testing different values to find the optimal balance between shadow quality and performance for your specific use case.
3. Considering the target hardware when setting this value, as lower-end devices may benefit from a lower value to maintain performance.

Regarding the associated variable CVarShadowTexelsPerPixelSpotlight:

The purpose of CVarShadowTexelsPerPixelSpotlight is to provide programmatic access to the r.Shadow.TexelsPerPixelSpotlight setting within the C++ code of the engine.

This variable is used directly in the shadow setup process, specifically in the CreateWholeSceneProjectedShadow function of the FSceneRenderer class. It’s used to calculate the UnclampedResolution for spotlight shadows.

The value of this variable is set through the console variable system and can be accessed in the render thread using the GetValueOnRenderThread() method.

CVarShadowTexelsPerPixelSpotlight interacts with similar variables for other light types (like CVarShadowTexelsPerPixelRectlight) in the shadow resolution calculation process.

Developers should be aware that changes to this variable will immediately affect spotlight shadow calculations in the render thread.

Best practices for using CVarShadowTexelsPerPixelSpotlight include:

1. Accessing the value using GetValueOnRenderThread() when used in render thread operations.
2. Considering the impact on shadow quality and performance when modifying this value dynamically.
3. Coordinating changes to this variable with other shadow-related variables to maintain consistent shadow quality across different light types.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelSpotlight(
	TEXT("r.Shadow.TexelsPerPixelSpotlight"),
	2.0f * 1.27324f,
	TEXT("The ratio of subject pixels to shadow texels for spotlights"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelRectlight(
	TEXT("r.Shadow.TexelsPerPixelRectlight"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelSpotlight(
	TEXT("r.Shadow.TexelsPerPixelSpotlight"),
	2.0f * 1.27324f,
	TEXT("The ratio of subject pixels to shadow texels for spotlights"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelRectlight(

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

Scope (from outer to inner):

file
function     void FSceneRenderer::CreateWholeSceneProjectedShadow

Source code excerpt:

				break;
			case LightType_Spot:
				UnclampedResolution = ScreenRadius * CVarShadowTexelsPerPixelSpotlight.GetValueOnRenderThread();
				break;
			case LightType_Rect:
				UnclampedResolution = ScreenRadius * CVarShadowTexelsPerPixelRectlight.GetValueOnRenderThread();
				break;
			default:
				// directional lights are not handled here