r.Shadow.Virtual.NonNaniteVSM

r.Shadow.Virtual.NonNaniteVSM

#Overview

name: r.Shadow.Virtual.NonNaniteVSM

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

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.NonNaniteVSM is to enable support for non-Nanite Virtual Shadow Maps in Unreal Engine 5. This setting variable is primarily used in the rendering system, specifically for shadow rendering and management.

The Unreal Engine subsystems that rely on this setting variable are primarily the Renderer module and the RenderCore module. These modules handle various aspects of the rendering pipeline, including shadow rendering.

The value of this variable is set through a console variable (CVar) system. It is defined as a read-only variable that should be set in a configuration file and requires a restart to take effect.

The associated variable GEnableNonNaniteVSM interacts directly with r.Shadow.Virtual.NonNaniteVSM. They share the same value and are used interchangeably in the codebase.

Developers must be aware that this variable affects the support for non-Nanite Virtual Shadow Maps. It’s important to note that this setting is platform-dependent and is checked alongside other conditions such as Nanite support and general Virtual Shadow Map usage.

Best practices when using this variable include:

  1. Setting it in the appropriate configuration file rather than trying to change it at runtime.
  2. Considering its impact on performance and visual quality when enabling or disabling it.
  3. Ensuring that the target platform supports the feature before relying on it.

Regarding the associated variable GEnableNonNaniteVSM:

The purpose of GEnableNonNaniteVSM is to serve as an internal representation of the r.Shadow.Virtual.NonNaniteVSM console variable. It is used throughout the rendering code to check if non-Nanite Virtual Shadow Maps are enabled.

This variable is primarily used in the Renderer module, specifically in shadow-related operations and setup.

The value of GEnableNonNaniteVSM is set based on the r.Shadow.Virtual.NonNaniteVSM console variable.

GEnableNonNaniteVSM interacts closely with various shadow rendering systems, influencing decisions about shadow map creation, culling, and shader compilation.

Developers should be aware that this variable is used in conditional statements throughout the shadow rendering code. Its value (0 or non-zero) determines whether certain shadow-related features are enabled or disabled.

Best practices for using GEnableNonNaniteVSM include:

  1. Treating it as a read-only variable in code, as its value is controlled by the console variable system.
  2. Being aware of its impact on shadow rendering when debugging or optimizing shadow-related code.
  3. Considering its state when implementing new shadow rendering features or modifying existing ones.

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

Scope: file

Source code excerpt:

int32 GEnableNonNaniteVSM = 1;
FAutoConsoleVariableRef CVarEnableNonNaniteVSM(
	TEXT("r.Shadow.Virtual.NonNaniteVSM"),
	GEnableNonNaniteVSM,
	TEXT("Enable support for non-nanite Virtual Shadow Maps.")
	TEXT("Read-only and to be set in a config file (requires restart)."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1378

Scope (from outer to inner):

file
function     bool DoesPlatformSupportNonNaniteVirtualShadowMaps

Source code excerpt:

bool DoesPlatformSupportNonNaniteVirtualShadowMaps(EShaderPlatform ShaderPlatform)
{
	static const auto EnableCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.Virtual.NonNaniteVSM"));
	return EnableCVar->GetInt() != 0 && DoesPlatformSupportNanite(ShaderPlatform, false /* check project setting */);
}

bool UseNonNaniteVirtualShadowMaps(EShaderPlatform ShaderPlatform, const FStaticFeatureLevel FeatureLevel)
{
	static const auto EnableCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.Virtual.NonNaniteVSM"));
	return EnableCVar->GetInt() != 0 && UseVirtualShadowMaps(ShaderPlatform, FeatureLevel);
}

bool IsWaterVirtualShadowMapFilteringEnabled(const FStaticShaderPlatform Platform)
{
	static const auto CVarWaterSingleLayerShaderSupportVSMFiltering = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Water.SingleLayer.ShadersSupportVSMFiltering"));

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Public/RenderUtils.h:420

Scope: file

Source code excerpt:


/**
* Returns true if non-Nanite virtual shadow maps are enabled by CVar r.Shadow.Virtual.NonNaniteVSM
* and the runtime supports Nanite/virtual shadow maps.
*/
RENDERCORE_API bool DoesPlatformSupportNonNaniteVirtualShadowMaps(EShaderPlatform ShaderPlatform);

/**
* Similar to DoesPlatformSupportNonNaniteVirtualShadowMaps, but checks if nanite and virtual shadow maps are enabled (at runtime).
*/
RENDERCORE_API bool UseNonNaniteVirtualShadowMaps(EShaderPlatform ShaderPlatform, FStaticFeatureLevel FeatureLevel);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowDepthRendering.cpp:139

Scope: file

Source code excerpt:


extern int32 GNaniteShowStats;
extern int32 GEnableNonNaniteVSM;

namespace Nanite
{
	extern bool IsStatFilterActive(const FString& FilterName);
	extern bool IsStatFilterActiveForLight(const FLightSceneProxy* LightProxy);
	extern FString GetFilterNameForLight(const FLightSceneProxy* LightProxy);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:58

Scope: file

Source code excerpt:

	);

extern int GEnableNonNaniteVSM;

int32 GCacheWholeSceneShadows = 1;
FAutoConsoleVariableRef CVarCacheWholeSceneShadows(
	TEXT("r.Shadow.CacheWholeSceneShadows"),
	GCacheWholeSceneShadows,
	TEXT("When enabled, movable point and spot light whole scene shadow depths from static primitives will be cached as an optimization."),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:2070

Scope (from outer to inner):

file
function     bool FProjectedShadowInfo::TestPrimitiveFarCascadeConditions

Source code excerpt:

	}

	if (GEnableNonNaniteVSM != 0 && MeshPassTargetType == EMeshPass::VSMShadowDepth)
	{
		const bool bWholeSceneDirectionalShadow = IsWholeSceneDirectionalShadow();

		if (bWholeSceneDirectionalShadow && MaxNonFarCascadeDistance > 0.0f)
		{
			check(DependentView);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:5601

Scope (from outer to inner):

file
function     void FSceneRenderer::AddViewDependentWholeSceneShadowsForView

Source code excerpt:

				SortedShadowsForShadowDepthPass.VirtualShadowMapClipmaps.Add(VirtualShadowMapClipmap);

				if (GEnableNonNaniteVSM != 0)
				{
					// Create the projected shadow info to make sure that culling happens.
					FProjectedShadowInfo* ProjectedShadowInfo = Allocator.Create<FProjectedShadowInfo>();
					ProjectedShadowInfo->SetupClipmapProjection(&LightSceneInfo, &View, VirtualShadowMapClipmap, CVarVsmUseFarShadowRules.GetValueOnRenderThread() != 0 ? MaxNonFarCascadeDistance : -1.0f);
					VisibleLightInfo.AllProjectedShadows.Add(ProjectedShadowInfo);
					ShadowInfosThatNeedCulling.Add(ProjectedShadowInfo);

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

Scope: file

Source code excerpt:

);

int32 GEnableNonNaniteVSM = 1;
FAutoConsoleVariableRef CVarEnableNonNaniteVSM(
	TEXT("r.Shadow.Virtual.NonNaniteVSM"),
	GEnableNonNaniteVSM,
	TEXT("Enable support for non-nanite Virtual Shadow Maps.")
	TEXT("Read-only and to be set in a config file (requires restart)."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

static TAutoConsoleVariable<int32> CVarNonNaniteVsmUseHzb(

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::SetShaderDefines

Source code excerpt:

{
	static_assert(FVirtualShadowMap::Log2Level0DimPagesXY * 2U + NANITE_MAX_VIEWS_PER_CULL_RASTERIZE_PASS_BITS <= 32U, "Page indirection plus view index must fit into 32-bits for page-routing storage!");
	OutEnvironment.SetDefine(TEXT("ENABLE_NON_NANITE_VSM"), GEnableNonNaniteVSM);
	OutEnvironment.SetDefine(TEXT("VSM_PAGE_SIZE"), FVirtualShadowMap::PageSize);
	OutEnvironment.SetDefine(TEXT("VSM_PAGE_SIZE_MASK"), FVirtualShadowMap::PageSizeMask);
	OutEnvironment.SetDefine(TEXT("VSM_LOG2_PAGE_SIZE"), FVirtualShadowMap::Log2PageSize);
	OutEnvironment.SetDefine(TEXT("VSM_LEVEL0_DIM_PAGES_XY"), FVirtualShadowMap::Level0DimPagesXY);
	OutEnvironment.SetDefine(TEXT("VSM_LOG2_LEVEL0_DIM_PAGES_XY"), FVirtualShadowMap::Log2Level0DimPagesXY);
	OutEnvironment.SetDefine(TEXT("VSM_MAX_MIP_LEVELS"), FVirtualShadowMap::MaxMipLevels);