r.Shadow.Virtual.MarkCoarsePagesLocal

r.Shadow.Virtual.MarkCoarsePagesLocal

#Overview

name: r.Shadow.Virtual.MarkCoarsePagesLocal

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

• type: Var
• help: Marks coarse pages in local light virtual shadow maps so that low resolution data is available everywhere.Ability to disable is primarily for profiling and debugging.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.MarkCoarsePagesLocal is to control the marking of coarse pages in local light virtual shadow maps. It is used in the rendering system, specifically for virtual shadow map management.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the virtual shadow map subsystem. Based on the callsites, it’s utilized in the FVirtualShadowMapArray class, which is responsible for managing virtual shadow maps.

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

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

Developers should be aware that this variable affects the availability of low-resolution shadow data across the entire scene for local lights. When enabled (set to 1), it ensures that coarse shadow information is available everywhere, which can be beneficial for performance and visual quality in some scenarios.

Best practices when using this variable include:

1. Keeping it enabled (set to 1) for most scenarios, as it’s the default behavior.
2. Only disabling it (set to 0) for profiling and debugging purposes, as mentioned in the variable’s description.
3. Being cautious when modifying this setting, as it can impact shadow rendering performance and quality.

Regarding the associated variable CVarMarkCoarsePagesLocal:

• It’s purpose is identical to r.Shadow.Virtual.MarkCoarsePagesLocal.
• It’s used in the same Renderer module and virtual shadow map subsystem.
• The value is set when the console variable is initialized.
• It directly controls the behavior of coarse page marking for local light virtual shadow maps.
• Developers should treat it with the same considerations as r.Shadow.Virtual.MarkCoarsePagesLocal.
• Best practices include using it for runtime adjustments and debugging, while generally keeping it enabled for optimal shadow rendering.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarMarkCoarsePagesLocal(
	TEXT("r.Shadow.Virtual.MarkCoarsePagesLocal"),
	1,
	TEXT("Marks coarse pages in local light virtual shadow maps so that low resolution data is available everywhere.")
	TEXT("Ability to disable is primarily for profiling and debugging."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarMarkCoarsePagesLocal(
	TEXT("r.Shadow.Virtual.MarkCoarsePagesLocal"),
	1,
	TEXT("Marks coarse pages in local light virtual shadow maps so that low resolution data is available everywhere.")
	TEXT("Ability to disable is primarily for profiling and debugging."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

			// Because of this we also cannot overlap this pass with the following ones.
			bool bMarkCoarsePagesDirectional = CVarMarkCoarsePagesDirectional.GetValueOnRenderThread() != 0;
			bool bMarkCoarsePagesLocal = CVarMarkCoarsePagesLocal.GetValueOnRenderThread() != 0;
			// Note: always run this pass such that the distant lights may be marked if need be
			{
				FMarkCoarsePagesCS::FParameters* PassParameters = GraphBuilder.AllocParameters< FMarkCoarsePagesCS::FParameters >();
				PassParameters->VirtualShadowMap = GetUncachedUniformBuffer(GraphBuilder);
				PassParameters->OutPageRequestFlags = GraphBuilder.CreateUAV(PageRequestFlagsRDG);
				PassParameters->bMarkCoarsePagesLocal = bMarkCoarsePagesLocal ? 1 : 0;