r.Shadow.Virtual.PageDilationBorderSizeLocal

r.Shadow.Virtual.PageDilationBorderSizeLocal

#Overview

name: r.Shadow.Virtual.PageDilationBorderSizeLocal

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

• type: Var
• help: If a screen pixel falls within this fraction of a page border for local lights, the adacent page will also be mapped.Higher values can reduce page misses at screen edges or disocclusions, but increase total page counts.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.PageDilationBorderSizeLocal is to control the dilation of virtual shadow map pages for local lights in Unreal Engine 5’s rendering system. It determines how much the engine should extend the mapping of shadow pages near the borders to reduce artifacts and improve shadow quality.

This setting variable is primarily used in the Renderer module, specifically within the Virtual Shadow Maps subsystem. It’s part of Unreal Engine 5’s advanced shadow rendering techniques.

The value of this variable is set as a console variable with a default value of 0.05f. It can be modified at runtime through the console or programmatically.

The associated variable CVarPageDilationBorderSizeLocal directly interacts with r.Shadow.Virtual.PageDilationBorderSizeLocal. They share the same value and purpose.

Developers must be aware that:

1. This variable affects performance and visual quality. Higher values can reduce page misses at screen edges or during disocclusions, but will increase the total page count, potentially impacting performance.
2. The value represents a fraction of the page border, not an absolute size.

Best practices when using this variable include:

1. Fine-tuning the value based on the specific needs of your project, balancing between shadow quality and performance.
2. Testing different values in various scenarios to find the optimal setting for your game.
3. Consider adjusting this value dynamically based on the scene complexity or performance requirements.

Regarding the associated variable CVarPageDilationBorderSizeLocal:

• It’s an internal representation of the console variable.
• It’s used to retrieve the current value of the setting in the render thread (as seen in the BuildPageAllocations function).
• Developers should use this variable when they need to access the current value of the setting in C++ code, especially within render thread operations.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarPageDilationBorderSizeLocal(
	TEXT("r.Shadow.Virtual.PageDilationBorderSizeLocal"),
	0.05f,
	TEXT("If a screen pixel falls within this fraction of a page border for local lights, the adacent page will also be mapped.")
	TEXT("Higher values can reduce page misses at screen edges or disocclusions, but increase total page counts."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarPageDilationBorderSizeLocal(
	TEXT("r.Shadow.Virtual.PageDilationBorderSizeLocal"),
	0.05f,
	TEXT("If a screen pixel falls within this fraction of a page border for local lights, the adacent page will also be mapped.")
	TEXT("Higher values can reduce page misses at screen edges or disocclusions, but increase total page counts."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations
lambda-function

Source code excerpt:

					}
					PassParameters->NumDirectionalLightSmInds = uint32(DirectionalLightIds.Num());
					PassParameters->PageDilationBorderSizeLocal = CVarPageDilationBorderSizeLocal.GetValueOnRenderThread();
					PassParameters->PageDilationBorderSizeDirectional = CVarPageDilationBorderSizeDirectional.GetValueOnRenderThread();
					PassParameters->bCullBackfacingPixels = ShouldCullBackfacingPixels() ? 1 : 0;
					PassParameters->Substrate = Substrate::BindSubstrateGlobalUniformParameters(View);
					PassParameters->PixelStride = PixelStride;
					PassParameters->MipModeLocal = CVarMarkPixelPagesMipModeLocal.GetValueOnRenderThread();