r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias

r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias

#Overview

name: r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias

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

• type: Var
• help: As page allocation approaches the pool capacity, VSM resolution ramps down by biasing the LOD up, similar to \'ResolutionLodBiasDirectional\'.\nThis is the maximum LOD bias to clamp to for global dynamic shadow resolution reduction. 0 = disabled

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias is to control the maximum Level of Detail (LOD) bias for global dynamic shadow resolution reduction in Virtual Shadow Maps (VSM).

This setting variable is primarily used by the rendering system, specifically for the Virtual Shadow Maps feature in Unreal Engine 5. It is part of the dynamic resolution system for shadows.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its location in the VirtualShadowMapCacheManager.cpp file within the Renderer’s private directory.

The value of this variable is set using a TAutoConsoleVariable, which means it can be adjusted at runtime through console commands or configuration files. The default value is set to 2.0f.

This variable interacts with CVarVSMDynamicResolutionMaxPagePoolLoadFactor, as seen in the provided code snippet. Together, they control how the VSM resolution is adjusted based on page allocation approaching the pool capacity.

Developers must be aware that this variable affects the trade-off between shadow quality and performance. A higher value allows for more aggressive resolution reduction, potentially improving performance at the cost of shadow quality.

Best practices when using this variable include:

1. Adjusting it in conjunction with other shadow-related settings for optimal balance.
2. Testing different values to find the right balance between performance and visual quality for your specific game.
3. Considering the target hardware capabilities when setting this value.

The associated variable CVarVSMDynamicResolutionMaxLodBias serves the same purpose and is used interchangeably with r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias. It’s an implementation detail that allows for easy access to the console variable’s value within the C++ code.

This associated variable is used in the FVirtualShadowMapArrayCacheManager to retrieve the current value of the setting on the render thread. It’s important to note that it uses GetValueOnRenderThread(), ensuring thread-safe access to the variable’s value.

When working with CVarVSMDynamicResolutionMaxLodBias, developers should follow the same best practices as with r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias, as they represent the same setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:92

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarVSMDynamicResolutionMaxLodBias(
	TEXT("r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias"),
	2.0f,
	TEXT("As page allocation approaches the pool capacity, VSM resolution ramps down by biasing the LOD up, similar to 'ResolutionLodBiasDirectional'.\n")
	TEXT("This is the maximum LOD bias to clamp to for global dynamic shadow resolution reduction. 0 = disabled"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:91

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarVSMDynamicResolutionMaxLodBias(
	TEXT("r.Shadow.Virtual.DynamicRes.MaxResolutionLodBias"),
	2.0f,
	TEXT("As page allocation approaches the pool capacity, VSM resolution ramps down by biasing the LOD up, similar to 'ResolutionLodBiasDirectional'.\n")
	TEXT("This is the maximum LOD bias to clamp to for global dynamic shadow resolution reduction. 0 = disabled"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapCacheManager.cpp:519

Scope (from outer to inner):

file
function     FVirtualShadowMapArrayCacheManager::FVirtualShadowMapArrayCacheManager
lambda-function

Source code excerpt:

			const float MaxPageAllocation = CVarVSMDynamicResolutionMaxPagePoolLoadFactor.GetValueOnRenderThread();
			const float MaxLodBias = CVarVSMDynamicResolutionMaxLodBias.GetValueOnRenderThread();
			
			if (MaxPageAllocation > 0.0f)
			{
				const uint32 SceneFrameNumber = Scene->GetFrameNumberRenderThread();

				// Dynamically bias shadow resolution when we get too near the maximum pool capacity