r.Shadow.Virtual.MarkCoarsePagesDirectional

r.Shadow.Virtual.MarkCoarsePagesDirectional

#Overview

name: r.Shadow.Virtual.MarkCoarsePagesDirectional

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.MarkCoarsePagesDirectional is to control the marking of coarse pages in directional light virtual shadow maps. This setting is primarily used in the rendering system, specifically for virtual shadow map management.

This setting variable is utilized by the Unreal Engine’s rendering subsystem, particularly in the virtual shadow mapping module. It’s implemented in the VirtualShadowMapArray.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVarMarkCoarsePagesDirectional) with a default value of 1 (enabled). It can be changed at runtime using console commands or through engine configuration files.

The associated variable CVarMarkCoarsePagesDirectional interacts directly with r.Shadow.Virtual.MarkCoarsePagesDirectional. 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 directional lights. When enabled (default), it ensures that coarse shadow information is available everywhere, which can be beneficial for performance and visual consistency.

Best practices when using this variable include:

  1. Keeping it enabled (value 1) for most scenarios, as it’s the default and intended behavior.
  2. Only disabling it (value 0) for specific profiling or debugging purposes, as mentioned in the variable’s description.
  3. Being cautious when modifying this setting, as it can impact both performance and visual quality of shadows in the scene.
  4. Testing thoroughly after any changes to ensure desired shadow quality and performance.

Regarding the associated variable CVarMarkCoarsePagesDirectional:

The purpose of CVarMarkCoarsePagesDirectional is the same as r.Shadow.Virtual.MarkCoarsePagesDirectional. It’s an internal representation of the console variable used to control the marking of coarse pages in directional light virtual shadow maps.

This variable is used directly in the rendering code to determine whether to mark coarse pages for directional lights. It’s typically accessed using the GetValueOnRenderThread() method to ensure thread-safe access to its current value.

The value of CVarMarkCoarsePagesDirectional is set when the console variable r.Shadow.Virtual.MarkCoarsePagesDirectional is modified.

Developers should be aware that this variable is used in performance-critical rendering code, specifically in the BuildPageAllocations function of the FVirtualShadowMapArray class. Changes to its value can have immediate effects on the shadow rendering process.

Best practices for CVarMarkCoarsePagesDirectional are similar to those for r.Shadow.Virtual.MarkCoarsePagesDirectional, with an additional note to be cautious about directly modifying this variable in code, as it’s primarily intended to be controlled via the console variable system.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarMarkCoarsePagesDirectional(
	TEXT("r.Shadow.Virtual.MarkCoarsePagesDirectional"),
	1,
	TEXT("Marks coarse pages in directional 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 CVarMarkCoarsePagesDirectional. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarMarkCoarsePagesDirectional(
	TEXT("r.Shadow.Virtual.MarkCoarsePagesDirectional"),
	1,
	TEXT("Marks coarse pages in directional 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:1414

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

			// is much slower.
			// 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);