r.Shadow.Virtual.PageDilationBorderSizeDirectional

r.Shadow.Virtual.PageDilationBorderSizeDirectional

#Overview

name: r.Shadow.Virtual.PageDilationBorderSizeDirectional

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 directional 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.PageDilationBorderSizeDirectional is to control the dilation of virtual shadow map pages for directional lights in Unreal Engine’s rendering system. It specifically affects the behavior of page mapping near the borders of shadow map pages.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the Virtual Shadow Maps subsystem. Based on the callsites, it’s implemented in the VirtualShadowMapArray.cpp file, which is part of the virtual shadow mapping functionality.

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 through configuration files.

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

Developers must be aware that this variable affects the trade-off between shadow quality and performance. A higher value can reduce page misses at screen edges or during disocclusions, which can improve shadow quality, but it will also increase the total number of shadow map pages, potentially impacting performance.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your scene and performance targets.
2. Testing different values to find the optimal balance between shadow quality and performance.
3. Considering the impact on memory usage, as increasing this value will lead to more shadow map pages being allocated.

Regarding the associated variable CVarPageDilationBorderSizeDirectional:

• Its purpose is identical to r.Shadow.Virtual.PageDilationBorderSizeDirectional.
• It’s used in the same Renderer module and Virtual Shadow Maps subsystem.
• The value is set and accessed using the GetValueOnRenderThread() method, indicating it’s designed for thread-safe access in the render thread.
• It’s used directly in the BuildPageAllocations function of the FVirtualShadowMapArray class, where it’s passed as a parameter to shader code.

When working with CVarPageDilationBorderSizeDirectional, developers should:

1. Treat it as equivalent to r.Shadow.Virtual.PageDilationBorderSizeDirectional in terms of its effects and considerations.
2. Be aware that changes to this variable will take effect on the render thread, which may not be immediate depending on when it’s modified.
3. Consider its interaction with other shadow-related variables, such as CVarPageDilationBorderSizeLocal, which is used alongside it in the shader parameter setup.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarPageDilationBorderSizeDirectional(
	TEXT("r.Shadow.Virtual.PageDilationBorderSizeDirectional"),
	0.05f,
	TEXT("If a screen pixel falls within this fraction of a page border for directional 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 CVarPageDilationBorderSizeDirectional. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarPageDilationBorderSizeDirectional(
	TEXT("r.Shadow.Virtual.PageDilationBorderSizeDirectional"),
	0.05f,
	TEXT("If a screen pixel falls within this fraction of a page border for directional 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:1527

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();
					
					const FIntPoint StridedPixelSize = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), PixelStride);