r.ParallelShadows

r.ParallelShadows

#Overview

name: r.ParallelShadows

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 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ParallelShadows is to control parallel shadow rendering in Unreal Engine 5’s rendering system. This setting variable is used to toggle the parallel rendering of shadows, which can potentially improve performance on systems with multiple processing cores.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the shadow depth rendering subsystem. The code referencing this variable is located in the ShadowDepthRendering.cpp file, which is part of the core rendering pipeline.

The value of this variable is set through a console variable (CVarParallelShadows) with a default value of 1, meaning parallel shadow rendering is enabled by default. Developers can modify this value at runtime using console commands or through project settings.

The r.ParallelShadows variable interacts with another variable called r.ParallelShadowsNonWholeScene (CVarParallelShadowsNonWholeScene). These two variables work together to determine when parallel shadow rendering should be used.

Developers should be aware that:

  1. Parallel rendering must be enabled for this setting to have an effect.
  2. The setting is render thread safe, meaning it can be changed dynamically without causing threading issues.
  3. This setting may not have an effect on all platforms, as indicated by the check for mobile platforms in the IsParallelDispatchEnabled function.

Best practices for using this variable include:

  1. Testing performance with and without parallel shadows enabled to determine the optimal setting for your specific project and target hardware.
  2. Considering the interaction with whole scene directional shadows and non-whole scene shadows when configuring shadow rendering.
  3. Being mindful of the target platforms, especially mobile, where parallel dispatch may not be supported.

Regarding the associated variable CVarParallelShadows:

The purpose of CVarParallelShadows is to provide a programmatic interface for the r.ParallelShadows setting. It allows the engine to access and modify the parallel shadows setting at runtime.

This variable is used in the Renderer module, specifically in the shadow depth rendering system. It’s defined and used in the same file as r.ParallelShadows (ShadowDepthRendering.cpp).

The value of CVarParallelShadows is set when the console variable is created, with a default value of 1. It can be accessed and modified through the Unreal Engine console system.

CVarParallelShadows interacts directly with the r.ParallelShadows setting, effectively serving as its in-code representation. It’s also used in conjunction with CVarParallelShadowsNonWholeScene to determine when parallel shadow rendering should be used.

Developers should be aware that:

  1. This variable is of type TAutoConsoleVariable, which means it’s thread-safe and can be accessed from multiple threads.
  2. Changes to this variable will immediately affect the behavior of the shadow rendering system.

Best practices for using CVarParallelShadows include:

  1. Using GetValueOnRenderThread() when accessing the value, as shown in the IsParallelDispatchEnabled function, to ensure thread-safe access.
  2. Consider caching the value if it’s accessed frequently, to avoid potential performance overhead from repeated console variable lookups.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/Android/AndroidEngine.ini:75, section: [ConsoleVariables]

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarParallelShadows(
	TEXT("r.ParallelShadows"),
	1,
	TEXT("Toggles parallel shadow rendering. Parallel rendering must be enabled for this to have an effect."),
	ECVF_RenderThreadSafe
);
static TAutoConsoleVariable<int32> CVarParallelShadowsNonWholeScene(
	TEXT("r.ParallelShadowsNonWholeScene"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

}

static TAutoConsoleVariable<int32> CVarParallelShadows(
	TEXT("r.ParallelShadows"),
	1,
	TEXT("Toggles parallel shadow rendering. Parallel rendering must be enabled for this to have an effect."),
	ECVF_RenderThreadSafe
);
static TAutoConsoleVariable<int32> CVarParallelShadowsNonWholeScene(

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

Scope (from outer to inner):

file
function     bool IsParallelDispatchEnabled

Source code excerpt:

bool IsParallelDispatchEnabled(const FProjectedShadowInfo* ProjectedShadowInfo, EShaderPlatform ShaderPlatform)
{
	return GRHICommandList.UseParallelAlgorithms() && CVarParallelShadows.GetValueOnRenderThread()
		&& (ProjectedShadowInfo->IsWholeSceneDirectionalShadow() || CVarParallelShadowsNonWholeScene.GetValueOnRenderThread())
		// Parallel dispatch is not supported on mobile platform
		&& !IsMobilePlatform(ShaderPlatform);
}

void FSceneRenderer::RenderShadowDepthMapAtlases(FRDGBuilder& GraphBuilder)