r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold

r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold

#Overview

name: r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold

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

• type: Var
• help: How large area is considered a \'large\' footprint, summed over all overlapped levels, if set to -1 uses the physical page pool size / 8.\nUsed as a threshold when storing page area coverage stats for diagnostics.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold is to define a threshold for what is considered a ’large’ footprint in terms of page area coverage for virtual shadow maps, specifically for non-Nanite objects. This setting is used in the context of the virtual shadow mapping system within Unreal Engine 5’s rendering pipeline.

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

The value of this variable is set through a console variable (CVarLargeInstancePageAreaThreshold). By default, it’s set to -1, which means it will use the physical page pool size divided by 8 as the threshold. Users can modify this value through console commands or project settings.

The associated variable CVarLargeInstancePageAreaThreshold interacts directly with r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold. They essentially represent the same setting, with CVarLargeInstancePageAreaThreshold being the C++ implementation of the console variable.

Developers should be aware that this variable is primarily used for diagnostic purposes. It’s used as a threshold when storing page area coverage stats, which can be helpful for performance analysis and optimization of virtual shadow maps.

Best practices when using this variable include:

1. Leave it at the default value (-1) unless you have specific reasons to change it.
2. If you do modify it, monitor the impact on performance and shadow quality carefully.
3. Use it in conjunction with other virtual shadow map settings for comprehensive optimization.
4. Remember that this setting is specific to non-Nanite objects, so consider its interaction with Nanite-specific shadow settings as well.

Regarding the associated variable CVarLargeInstancePageAreaThreshold:

• It’s the C++ implementation of the console variable.
• It’s used to retrieve the actual value of the setting in the render thread.
• The value is used in the FCullPerPageDrawCommandsCs pass parameters, specifically to set the LargeInstancePageAreaThreshold.
• If the value is -1 or less, it defaults to (VirtualShadowMapArray.GetMaxPhysicalPages() / 8).
• This variable is crucial for the proper functioning of the virtual shadow map system, particularly in diagnostics and performance optimization scenarios.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarLargeInstancePageAreaThreshold(
	TEXT("r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold"),
	-1,
	TEXT("How large area is considered a 'large' footprint, summed over all overlapped levels, if set to -1 uses the physical page pool size / 8.\n")
	TEXT("Used as a threshold when storing page area coverage stats for diagnostics."),
	ECVF_RenderThreadSafe
);
#endif // !UE_BUILD_SHIPPING

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarLargeInstancePageAreaThreshold(
	TEXT("r.Shadow.Virtual.NonNanite.LargeInstancePageAreaThreshold"),
	-1,
	TEXT("How large area is considered a 'large' footprint, summed over all overlapped levels, if set to -1 uses the physical page pool size / 8.\n")
	TEXT("Used as a threshold when storing page area coverage stats for diagnostics."),
	ECVF_RenderThreadSafe
);

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

Scope: file

Source code excerpt:

#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);
		PermutationVector.Set< FCullPerPageDrawCommandsCs::FUseHzbDim >(HZBShaderParameters.HZBTexture != nullptr);