r.Shadow.Virtual.NonNanite.IncludeInCoarsePages

r.Shadow.Virtual.NonNanite.IncludeInCoarsePages

#Overview

name: r.Shadow.Virtual.NonNanite.IncludeInCoarsePages

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

• type: Var
• help: Include non-Nanite geometry in coarse pages.Rendering non-Nanite geometry into large coarse pages can be expensive; disabling this can be a significant performance win.

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.NonNanite.IncludeInCoarsePages is to control whether non-Nanite geometry should be included in coarse pages of virtual shadow maps. This setting variable is part of Unreal Engine’s virtual shadow map system, which is a rendering optimization technique for handling shadows in large, complex scenes.

The variable is used primarily in the rendering system, specifically in the virtual shadow map subsystem. It affects how the engine processes and renders shadows for different types of geometry.

The value of this variable is set through the console variable system. It’s defined as a TAutoConsoleVariable, which means it can be changed at runtime through console commands or configuration files.

This variable interacts closely with the CVarCoarsePagesIncludeNonNanite variable, which shares the same value. They are used together to determine whether non-Nanite geometry should be included in coarse shadow map pages.

Developers should be aware that:

1. Including non-Nanite geometry in coarse pages can be computationally expensive.
2. Disabling this feature (setting it to 0) can lead to significant performance improvements, especially in scenes with a lot of non-Nanite geometry.
3. However, disabling it might affect shadow quality for non-Nanite objects, particularly at a distance.

Best practices when using this variable include:

1. Consider the composition of your scene. If you have many non-Nanite objects that need accurate shadows at a distance, you might want to keep this enabled.
2. Profile your game’s performance with this setting both on and off to determine the best balance between visual quality and performance for your specific use case.
3. Consider exposing this as a graphics option for end-users, allowing them to balance between performance and shadow quality.

Regarding the associated variable CVarCoarsePagesIncludeNonNanite: This is the actual console variable that controls the behavior. It’s defined with a default value of 1 (enabled), but can be changed at runtime. It’s used in various parts of the virtual shadow map system to determine whether to include non-Nanite geometry in coarse page calculations. The same considerations and best practices apply to this variable as to r.Shadow.Virtual.NonNanite.IncludeInCoarsePages, as they are effectively the same setting.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarCoarsePagesIncludeNonNanite(
	TEXT("r.Shadow.Virtual.NonNanite.IncludeInCoarsePages"),
	1,
	TEXT("Include non-Nanite geometry in coarse pages.")
	TEXT("Rendering non-Nanite geometry into large coarse pages can be expensive; disabling this can be a significant performance win."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.h:139

Scope: file

Source code excerpt:

	SHADER_PARAMETER(FIntPoint, PhysicalPoolSizePages)

	// Set to 1 if r.Shadow.Virtual.NonNanite.IncludeInCoarsePages is set to 0 in order to signal that we want to use the legacy path for just excluding non-nanite
	SHADER_PARAMETER(uint32, bExcludeNonNaniteFromCoarsePages)
	SHADER_PARAMETER(float, CoarsePagePixelThresholdDynamic)
	SHADER_PARAMETER(float, CoarsePagePixelThresholdStatic)
	SHADER_PARAMETER(float, CoarsePagePixelThresholdDynamicNanite)

	// For shadow page age calculations

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarCoarsePagesIncludeNonNanite(
	TEXT("r.Shadow.Virtual.NonNanite.IncludeInCoarsePages"),
	1,
	TEXT("Include non-Nanite geometry in coarse pages.")
	TEXT("Rendering non-Nanite geometry into large coarse pages can be expensive; disabling this can be a significant performance win."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:

	// NOTE: Most uniform values don't matter when VSM is disabled

	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:1313

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

	UniformParameters.ProjectionData = GraphBuilder.CreateSRV(ProjectionDataRDG);

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

	bool bCsvLogEnabled = false;
#if !UE_BUILD_SHIPPING

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

				PassParameters->ClipmapFirstLevel = FVirtualShadowMapClipmap::GetFirstLevel();
				PassParameters->ClipmapIndexMask = bMarkCoarsePagesDirectional ? FVirtualShadowMapClipmap::GetCoarsePageClipmapIndexMask() : 0;
				PassParameters->bIncludeNonNaniteGeometry = CVarCoarsePagesIncludeNonNanite.GetValueOnRenderThread();

				auto ComputeShader = View.ShaderMap->GetShader<FMarkCoarsePagesCS>();

				FComputeShaderUtils::AddPass(
					GraphBuilder,
					RDG_EVENT_NAME("MarkCoarsePages"),