r.Shadow.Virtual.CoarsePagePixelThresholdDynamic

r.Shadow.Virtual.CoarsePagePixelThresholdDynamic

#Overview

name: r.Shadow.Virtual.CoarsePagePixelThresholdDynamic

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.CoarsePagePixelThresholdDynamic is to control the culling of dynamic (non-Nanite) instances in virtual shadow maps for coarse pages based on their estimated pixel footprint.

This setting variable is primarily used in the rendering system, specifically in the virtual shadow mapping subsystem of Unreal Engine 5. It is part of the Renderer module, as evidenced by its location in the VirtualShadowMapArray.cpp file.

The value of this variable is set through a console variable (CVarCoarsePagePixelThresholdDynamic) with a default value of 16.0f. It can be modified at runtime using console commands or through engine configuration files.

This variable interacts with other related variables such as CoarsePagePixelThresholdStatic and CoarsePagePixelThresholdDynamicNanite, which are used to control similar thresholds for static and Nanite objects, respectively.

Developers must be aware that increasing this value will result in more instances being culled from coarse pages, which can improve performance but may affect shadow quality for smaller dynamic objects. Conversely, decreasing the value will include more small instances in the coarse pages, potentially improving shadow detail at the cost of performance.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your project and target hardware.
  2. Testing thoroughly to find the optimal balance between performance and visual quality.
  3. Considering the interaction with other shadow-related settings.
  4. Using it in conjunction with the static and Nanite-specific thresholds for a comprehensive shadow culling strategy.

Regarding the associated variable CVarCoarsePagePixelThresholdDynamic:

This is the actual console variable that controls the r.Shadow.Virtual.CoarsePagePixelThresholdDynamic setting. It is defined using the TAutoConsoleVariable template, which allows for easy runtime modification and access.

The purpose of this variable is to provide a convenient interface for developers and users to adjust the coarse page pixel threshold for dynamic objects in virtual shadow maps.

It is used in the VirtualShadowMapArray system to set the UniformParameters.CoarsePagePixelThresholdDynamic value, which is then used in shadow rendering calculations.

Developers should be aware that this variable has the ECVF_Scalability and ECVF_RenderThreadSafe flags, meaning it can be safely adjusted for performance scaling and can be accessed from the render thread.

Best practices for using this console variable include:

  1. Using it for performance tuning and quality adjustments during development and testing.
  2. Exposing it in graphics settings menus for end-users to adjust based on their hardware capabilities.
  3. Considering its impact on both performance and visual quality when modifying its value.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdDynamic(
	TEXT("r.Shadow.Virtual.CoarsePagePixelThresholdDynamic"),
	16.0f,
	TEXT("If a dynamic (non-nanite) instance has a smaller estimated pixel footprint than this value, it should not be drawn into a coarse page. Higher values cull away more instances."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdStatic(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdDynamic(
	TEXT("r.Shadow.Virtual.CoarsePagePixelThresholdDynamic"),
	16.0f,
	TEXT("If a dynamic (non-nanite) instance has a smaller estimated pixel footprint than this value, it should not be drawn into a coarse page. Higher values cull away more instances."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:


	UniformParameters.bExcludeNonNaniteFromCoarsePages = !CVarCoarsePagesIncludeNonNanite.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamic = CVarCoarsePagePixelThresholdDynamic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdStatic = CVarCoarsePagePixelThresholdStatic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamicNanite = CVarCoarsePagePixelThresholdDynamicNanite.GetValueOnRenderThread();
	UniformParameters.bClipmapGreedyLevelSelection = CVarClipmapGreedyLevelSelection.GetValueOnRenderThread();

	UniformParameters.SceneFrameNumber = Scene.GetFrameNumberRenderThread();

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:


	UniformParameters.bExcludeNonNaniteFromCoarsePages = !CVarCoarsePagesIncludeNonNanite.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamic = CVarCoarsePagePixelThresholdDynamic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdStatic = CVarCoarsePagePixelThresholdStatic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamicNanite = CVarCoarsePagePixelThresholdDynamicNanite.GetValueOnRenderThread();

	bool bCsvLogEnabled = false;
#if !UE_BUILD_SHIPPING
	const bool bRunPageAreaDiagnostics = CVarNumPageAreaDiagSlots.GetValueOnRenderThread() != 0;