r.Shadow.Virtual.CoarsePagePixelThresholdDynamicNanite

r.Shadow.Virtual.CoarsePagePixelThresholdDynamicNanite

#Overview

name: r.Shadow.Virtual.CoarsePagePixelThresholdDynamicNanite

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.CoarsePagePixelThresholdDynamicNanite is to control the culling of dynamic Nanite instances in coarse pages of virtual shadow maps. This setting determines the pixel footprint threshold below which dynamic Nanite instances are not drawn into coarse pages.

Unreal Engine’s virtual shadow map system relies on this setting to optimize shadow rendering performance, particularly for the Nanite geometry virtualization system. It is part of the rendering subsystem, specifically the virtual shadow mapping module.

The value of this variable is set through the console variable system, allowing it to be adjusted at runtime. It is defined with a default value of 4.0f, which can be modified using console commands or through configuration files.

This variable interacts closely with other related settings, such as r.Shadow.Virtual.CoarsePagePixelThresholdDynamic and r.Shadow.Virtual.CoarsePagePixelThresholdStatic, which serve similar purposes for non-Nanite geometry.

Developers should be aware that this setting directly impacts the trade-off between shadow quality and performance. A higher value will cull more Nanite instances from coarse pages, potentially improving performance at the cost of shadow detail for small objects.

Best practices when using this variable include:

  1. Adjusting it in conjunction with other virtual shadow map settings for optimal balance.
  2. Testing its impact on both performance and visual quality across various scenes and viewing distances.
  3. Considering different values for different quality settings in the game.

The associated variable CVarCoarsePagePixelThresholdDynamicNanite is the actual console variable object that stores and manages this setting. It is used to retrieve the current value of the setting at runtime, allowing the rendering system to apply the appropriate culling threshold for dynamic Nanite instances in virtual shadow maps.

When using CVarCoarsePagePixelThresholdDynamicNanite, developers should note that it’s accessed using GetValueOnRenderThread() to ensure thread-safe access to its value during rendering operations. This variable is typically used in the context of setting up uniform parameters for shadow rendering passes, as seen in the provided code snippet.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdDynamicNanite(
	TEXT("r.Shadow.Virtual.CoarsePagePixelThresholdDynamicNanite"),
	4.0f,
	TEXT("If a dynamic 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.\n")
	TEXT("This value is typically lower than the non-Nanite one because Nanite has lower overhead for drawing small objects."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdDynamicNanite(
	TEXT("r.Shadow.Virtual.CoarsePagePixelThresholdDynamicNanite"),
	4.0f,
	TEXT("If a dynamic 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.\n")
	TEXT("This value is typically lower than the non-Nanite one because Nanite has lower overhead for drawing small objects."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:

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

	UniformParameters.SceneFrameNumber = Scene.GetFrameNumberRenderThread();

	// Reference dummy data in the UB initially
	const uint32 DummyPageTableElement = 0xFFFFFFFF;

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

	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;
#if CSV_PROFILER
	bCsvLogEnabled = FCsvProfiler::Get()->IsCapturing_Renderthread() && FCsvProfiler::Get()->IsCategoryEnabled(CSV_CATEGORY_INDEX(VSM));