r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel

r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel

#Overview

name: r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel

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

• type: Var
• help: Maximum lights per pixel that get full filtering when using one pass projection and clustered shading.Generally set to 8 (32bpp), 16 (64bpp) or 32 (128bpp). Lower values require less transient VRAM during the lighting pass.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel is to control the maximum number of lights per pixel that receive full filtering when using one-pass projection and clustered shading in the virtual shadow mapping system. This setting is part of Unreal Engine 5’s rendering system, specifically related to virtual shadow maps.

This setting variable is primarily used in the Renderer module, particularly in the virtual shadow mapping subsystem. It’s referenced in the VirtualShadowMapArray.cpp file, which is part of the virtual shadow mapping implementation.

The value of this variable is set through a console variable (CVarVirtualShadowOnePassProjectionMaxLights) with a default value of 16. It can be changed at runtime through console commands or project settings.

The associated variable CVarVirtualShadowOnePassProjectionMaxLights directly interacts with this setting. They share the same value and purpose.

Developers should be aware that:

1. This setting affects the balance between shadow quality and performance.
2. It has implications for VRAM usage during the lighting pass.
3. The value is typically set to 8, 16, or 32, corresponding to 32bpp, 64bpp, or 128bpp respectively.
4. Lower values will require less transient VRAM during the lighting pass but may reduce shadow quality.

Best practices when using this variable include:

1. Adjusting it based on the target hardware capabilities and performance requirements.
2. Considering the number of lights in the scene and clustered shading settings when setting this value.
3. Testing different values to find the optimal balance between shadow quality and performance for your specific project.

Regarding the associated variable CVarVirtualShadowOnePassProjectionMaxLights:

• It’s an auto console variable that directly controls the r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel setting.
• It’s used in the FVirtualShadowMapArray::Initialize function to set the UniformParameters.PackedShadowMaskMaxLightCount, clamping the value to a maximum of 32.
• This variable allows for runtime adjustment of the setting, which can be useful for performance tuning and debugging.

When working with this variable, developers should consider the overall lighting setup in their scene and adjust it in conjunction with other shadow and lighting settings for optimal results.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:195

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarVirtualShadowOnePassProjectionMaxLights(
	TEXT("r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel"),
	16,
	TEXT("Maximum lights per pixel that get full filtering when using one pass projection and clustered shading.")
	TEXT("Generally set to 8 (32bpp), 16 (64bpp) or 32 (128bpp). Lower values require less transient VRAM during the lighting pass."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:194

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarVirtualShadowOnePassProjectionMaxLights(
	TEXT("r.Shadow.Virtual.OnePassProjection.MaxLightsPerPixel"),
	16,
	TEXT("Maximum lights per pixel that get full filtering when using one pass projection and clustered shading.")
	TEXT("Generally set to 8 (32bpp), 16 (64bpp) or 32 (128bpp). Lower values require less transient VRAM during the lighting pass."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:495

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:

		// TODO: Parameterize this in a useful way; potentially modify it automatically
		// when there are fewer lights in the scene and/or clustered shading settings differ.
		UniformParameters.PackedShadowMaskMaxLightCount = FMath::Min(CVarVirtualShadowOnePassProjectionMaxLights.GetValueOnRenderThread(), 32);

		// Set up nanite visualization if enabled. We use an extra array slice in the physical page pool for debug output
		// so need to set this up in advance.
		if (EngineShowFlags.VisualizeVirtualShadowMap)
		{
			bEnableVisualization = true;