r.Shadow.Virtual.NonNanite.NumPageAreaDiagSlots

r.Shadow.Virtual.NonNanite.NumPageAreaDiagSlots

#Overview

name: r.Shadow.Virtual.NonNanite.NumPageAreaDiagSlots

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.NonNanite.NumPageAreaDiagSlots is to control the number of diagnostic slots used to report non-Nanite instances with the largest page area coverage in virtual shadow maps. This setting is part of the virtual shadow map system in Unreal Engine’s rendering pipeline.

This variable is primarily used in the Renderer module, specifically within the virtual shadow map subsystem. It’s referenced in the VirtualShadowMapArray.cpp file, which is part of the core implementation of virtual shadow maps.

The value of this variable is set through the console variable system, allowing it to be adjusted at runtime. It’s defined with a default value of 0, which disables the diagnostic feature.

This variable interacts with other parts of the virtual shadow map system:

  1. It’s used in conjunction with CVarLargeInstancePageAreaThreshold to determine which non-Nanite instances to report in diagnostics.
  2. It affects the allocation of the StatsBuffer, which is used for various shadow map statistics.

Developers should be aware of the following when using this variable:

  1. Setting it to a value less than 0 will use the maximum number of slots allowed (defined by MaxPageAreaDiagnosticSlots).
  2. Setting it to 0 disables the diagnostic feature entirely.
  3. This diagnostic feature is only available in non-shipping builds (#if !UE_BUILD_SHIPPING).

Best practices for using this variable include:

  1. Use it primarily for debugging and performance analysis of virtual shadow maps.
  2. Be mindful of the performance impact when enabling many diagnostic slots, especially in complex scenes.
  3. Consider using it in conjunction with other virtual shadow map diagnostics for a comprehensive view of the system’s behavior.

The associated variable CVarNumPageAreaDiagSlots serves as the actual console variable that controls this setting. It shares the same value and purpose as r.Shadow.Virtual.NonNanite.NumPageAreaDiagSlots. This console variable can be set through the game console or configuration files to adjust the behavior at runtime or startup.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarNumPageAreaDiagSlots(
	TEXT("r.Shadow.Virtual.NonNanite.NumPageAreaDiagSlots"),
	0,
	TEXT("Number of slots in diagnostics to report non-nanite instances with the largest page area coverage, < 0 uses the max number allowed, 0 disables."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarLargeInstancePageAreaThreshold(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarNumPageAreaDiagSlots(
	TEXT("r.Shadow.Virtual.NonNanite.NumPageAreaDiagSlots"),
	0,
	TEXT("Number of slots in diagnostics to report non-nanite instances with the largest page area coverage, < 0 uses the max number allowed, 0 disables."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

	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));
#endif
#else
	constexpr bool bRunPageAreaDiagnostics = false;
#endif

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

Scope: file

Source code excerpt:

			PassParameters->OutStatsBuffer = VirtualShadowMapArray.StatsBufferUAV;
#if !UE_BUILD_SHIPPING
			PassParameters->NumPageAreaDiagnosticSlots = CVarNumPageAreaDiagSlots.GetValueOnRenderThread() < 0 ? FVirtualShadowMapArray::MaxPageAreaDiagnosticSlots : FMath::Min(FVirtualShadowMapArray::MaxPageAreaDiagnosticSlots, uint32(CVarNumPageAreaDiagSlots.GetValueOnRenderThread()));
			PassParameters->LargeInstancePageAreaThreshold = CVarLargeInstancePageAreaThreshold.GetValueOnRenderThread() >= 0 ? CVarLargeInstancePageAreaThreshold.GetValueOnRenderThread() : (VirtualShadowMapArray.GetMaxPhysicalPages() / 8);
#endif
		}

		FCullPerPageDrawCommandsCs::FPermutationDomain PermutationVector;
		PermutationVector.Set< FCullPerPageDrawCommandsCs::FBatchedDim >(bUseBatchMode);