r.Shadow.Virtual.Enable

r.Shadow.Virtual.Enable

#Overview

name: r.Shadow.Virtual.Enable

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.Enable is to control the enabling of Virtual Shadow Maps in Unreal Engine 5. Virtual Shadow Maps are a rendering feature that provides high-quality shadows for next-generation projects with simplified setup and high-efficiency culling when used with Nanite.

This setting variable is primarily used by the rendering system, specifically the shadow rendering subsystem. It is referenced in multiple modules including the Renderer, Engine, and RenderCore.

The value of this variable is set through a console variable (CVar) system, which allows it to be changed at runtime. It can also be set in configuration files, particularly in the DefaultEngine.ini file for new projects.

Other variables that interact with r.Shadow.Virtual.Enable include:

  1. EShadowMapMethod enum, which must match the value of r.Shadow.Virtual.Enable
  2. Nanite-related settings, as Virtual Shadow Maps are designed to work efficiently with Nanite geometry

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

  1. Enabling Virtual Shadow Maps (setting to 1) is recommended for new projects, especially those using Nanite geometry.
  2. It may have performance implications, so testing should be done to ensure it’s appropriate for the project’s target hardware.
  3. When enabled, it replaces the traditional shadow mapping technique, which may affect existing shadow setups in a project.

Best practices for using this variable include:

  1. Enable it (set to 1) for new projects targeting high-end hardware or next-gen consoles.
  2. Ensure that Nanite is also enabled for maximum efficiency.
  3. Test thoroughly after enabling or disabling to ensure desired shadow quality and performance.
  4. Consider leaving it disabled for projects targeting lower-end hardware or mobile devices.
  5. Be aware that changing this setting may require adjustments to other shadow-related settings in the project.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:112, section: [/Script/Engine.RendererSettings]

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarEnableVirtualShadowMaps(
	TEXT("r.Shadow.Virtual.Enable"),
	0,
	TEXT("Enable Virtual Shadow Maps. Renders geometry into virtualized shadow depth maps for shadowing.\n")
	TEXT("Provides high - quality shadows for next - gen projects with simplified setup.High efficiency culling when used with Nanite."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		// Needed because the depth state changes with method (so cached draw commands must be re-created) see SetStateForShadowDepth

#Loc: <Workspace>/Engine/Plugins/VirtualProduction/ICVFXTesting/Source/ICVFXTesting/Public/ICVFXTestControllerBase.h:80

Scope (from outer to inner):

file
class        class UICVFXTestControllerBase : public UGauntletTestController

Source code excerpt:

		TEXT("r.Lumen"),
		TEXT("FX.AllowGPUParticles"),
		TEXT("r.Shadow.Virtual.Enable")};

	uint32 RunCount;

	bool bRequestsFPSChart;
	bool bRequestsMemReport;
	bool bRequestsVideoCapture;

#Loc: <Workspace>/Engine/Source/Editor/GameProjectGeneration/Private/GameProjectUtils.cpp:125

Scope (from outer to inner):

file
namespace    anonymous
function     void AddNewProjectDefaultShadowConfigValues

Source code excerpt:

		ConfigValues.Emplace(TEXT("DefaultEngine.ini"),
			TEXT("/Script/Engine.RendererSettings"),
			TEXT("r.Shadow.Virtual.Enable"),
			TEXT("1"),
			true /* ShouldReplaceExistingValue */);
	}

	void AddPostProcessingConfigValues(const FProjectInformation& InProjectInfo, TArray<FTemplateConfigValue>& ConfigValues)
	{
		// Enable support for ExtendDefaultLuminanceRange by default for new projects
		ConfigValues.Emplace(TEXT("DefaultEngine.ini"),
			TEXT("/Script/Engine.RendererSettings"),
			TEXT("r.DefaultFeature.AutoExposure.ExtendDefaultLuminanceRange"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/EngineTypes.h:457

Scope: file

Source code excerpt:

}

// Note: Must match r.Shadow.Virtual.Enable, this is used in URendererSettings
UENUM()
namespace EShadowMapMethod
{
	enum Type : int
	{
		/** Render geometry into shadow depth maps for shadowing.  Requires manual setup of shadowing distances and only culls per-component, causing poor performance with high poly scenes.  Required to enable stationary baked shadows (but which is incompatible with Nanite geometry). */

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/StaticMeshComponent.cpp:496

Scope (from outer to inner):

file
function     void UStaticMeshComponent::CheckForErrors

Source code excerpt:

	if (GetStaticMesh() != nullptr && GetStaticMesh()->IsNaniteEnabled() != 0)
	{
		static const auto CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.Virtual.Enable"));
		if (CVar->GetInt() == 0)
		{
			FFormatNamedArguments Arguments;
			Arguments.Add(TEXT("MeshName"), FText::FromString(GetStaticMesh()->GetName()));
			FMessageLog("MapCheck").Warning()
				->AddToken(FUObjectToken::Create(Owner))

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

Scope (from outer to inner):

file
function     bool UseVirtualShadowMaps

Source code excerpt:

bool UseVirtualShadowMaps(EShaderPlatform ShaderPlatform, const FStaticFeatureLevel FeatureLevel)
{
	static const auto EnableVirtualSMCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.Virtual.Enable"));
	const bool bVirtualShadowMapsEnabled = EnableVirtualSMCVar ? (EnableVirtualSMCVar->GetInt() != 0) : false;
	return bVirtualShadowMapsEnabled && DoesRuntimeSupportNanite(ShaderPlatform, true /* check for atomics */, false /* check project setting */);
}

bool DoesPlatformSupportVirtualShadowMaps(EShaderPlatform Platform)
{