r.Shadow.Virtual.OnePassProjection

r.Shadow.Virtual.OnePassProjection

#Overview

name: r.Shadow.Virtual.OnePassProjection

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

• type: Var
• help: Projects all local light virtual shadow maps in a single pass for better performance.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.OnePassProjection is to control the projection method for virtual shadow maps in Unreal Engine’s rendering system. It is specifically designed to optimize the performance of local light virtual shadow maps by projecting them all in a single pass.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the shadow rendering and light grid injection subsystems. The main files that reference this variable are ShadowSceneRenderer.cpp and LightGridInjection.cpp.

The value of this variable is set through a console variable (CVar) named CVarVirtualShadowOnePassProjection. It is initialized with a default value of 1, meaning the one-pass projection is enabled by default.

The associated variable CVarVirtualShadowOnePassProjection interacts directly with r.Shadow.Virtual.OnePassProjection, as they share the same value. This variable is used in conditional statements to determine whether to use the one-pass projection method for virtual shadow maps.

Developers should be aware that this variable affects the performance and potentially the visual quality of shadow rendering, especially for local lights. It’s important to consider the trade-offs between performance and visual fidelity when adjusting this setting.

Best practices when using this variable include:

1. Testing the performance impact with and without one-pass projection enabled.
2. Ensuring that the visual quality of shadows remains acceptable when enabled.
3. Considering the specific requirements of your project, as the optimal setting may vary depending on the number and complexity of local lights in your scenes.

Regarding the associated variable CVarVirtualShadowOnePassProjection:

• Its purpose is to provide a programmatic way to access and modify the r.Shadow.Virtual.OnePassProjection setting within the C++ code.
• It is used in the Renderer module, specifically in shadow rendering and light grid computation.
• The value is set through the console variable system, allowing for runtime modification.
• It interacts directly with the r.Shadow.Virtual.OnePassProjection setting.
• Developers should be aware that changes to this variable will affect the shadow rendering pipeline and potentially impact performance.
• Best practices include using GetValueOnRenderThread() when accessing this variable to ensure thread-safe operations in the rendering code.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:56

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarVirtualShadowOnePassProjection(
	TEXT("r.Shadow.Virtual.OnePassProjection"),
	1,
	TEXT("Projects all local light virtual shadow maps in a single pass for better performance."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarResolutionLodBiasLocal(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:98

Scope: file

Source code excerpt:

);

extern TAutoConsoleVariable<int32> CVarVirtualShadowOnePassProjection;

bool ShouldVisualizeLightGrid()
{
	return GForwardLightGridDebug > 0;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:948

Scope (from outer to inner):

file
function     FComputeLightGridOutput FDeferredShadingSceneRenderer::GatherLightsAndComputeLightGrid

Source code excerpt:

	bool bShadowedLightsInClustered = ShouldUseClusteredDeferredShading()
		&& CVarVirtualShadowOnePassProjection.GetValueOnRenderThread()
		&& VirtualShadowMapArray.IsEnabled();

	GatherAndSortLights(SortedLightSet, bShadowedLightsInClustered);
	
	if (!bNeedLightGrid)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:55

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarVirtualShadowOnePassProjection(
	TEXT("r.Shadow.Virtual.OnePassProjection"),
	1,
	TEXT("Projects all local light virtual shadow maps in a single pass for better performance."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:481

Scope (from outer to inner):

file
function     void FShadowSceneRenderer::RenderVirtualShadowMapProjectionMaskBits

Source code excerpt:

	bShouldUseVirtualShadowMapOnePassProjection =
		VirtualShadowMapArray.IsAllocated() &&
		CVarVirtualShadowOnePassProjection.GetValueOnRenderThread();

	if (!VirtualShadowMapArray.HasAnyShadowData())
	{
		return;
	}