r.ParallelGatherShadowPrimitives

r.ParallelGatherShadowPrimitives

#Overview

name: r.ParallelGatherShadowPrimitives

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ParallelGatherShadowPrimitives is to control the parallelization of shadow primitive gathering in Unreal Engine’s rendering system. This setting variable is used to toggle parallel gathering of shadow primitives, which can potentially improve performance in shadow rendering.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the shadow setup and rendering subsystem. Based on the callsites, we can see that it’s referenced in ShadowSetup.cpp and PrimitiveSceneInfo.h, which are part of the rendering pipeline.

The value of this variable is set through a console variable (CVarParallelGatherShadowPrimitives) with a default value of 1 (enabled). It can be changed at runtime through console commands or project settings.

The associated variable CVarParallelGatherShadowPrimitives interacts directly with r.ParallelGatherShadowPrimitives. They share the same value and purpose.

Developers should be aware that this variable affects the performance and behavior of shadow rendering. Enabling it (value > 0) allows for parallel gathering of shadow primitives, which can improve performance on multi-core systems. However, it may also introduce additional complexity in debugging shadow-related issues.

Best practices when using this variable include:

  1. Testing performance with both enabled and disabled states to determine the optimal setting for your specific project.
  2. Considering the target hardware when deciding whether to enable or disable this feature.
  3. Being aware that changing this setting may affect shadow quality or behavior, so thorough testing is recommended.

Regarding the associated variable CVarParallelGatherShadowPrimitives:

The purpose of CVarParallelGatherShadowPrimitives is to provide a runtime-configurable way to control the r.ParallelGatherShadowPrimitives setting. It’s implemented as a TAutoConsoleVariable, which allows for easy integration with Unreal Engine’s console variable system.

This console variable is defined in the Renderer module and is used to set the value of r.ParallelGatherShadowPrimitives. It’s primarily used in the shadow setup and rendering subsystem.

The value of CVarParallelGatherShadowPrimitives is set to 1 by default, but can be changed at runtime through console commands or project settings.

CVarParallelGatherShadowPrimitives directly interacts with r.ParallelGatherShadowPrimitives, effectively controlling its value.

Developers should be aware that changes to this console variable will immediately affect the shadow gathering behavior in the rendering pipeline. It’s marked as ECVF_RenderThreadSafe, meaning it can be safely changed from any thread.

Best practices for using CVarParallelGatherShadowPrimitives include:

  1. Using it for performance testing and optimization.
  2. Considering exposing it in debug menus for easy toggling during development.
  3. Documenting any project-specific optimal values for different hardware configurations.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarParallelGatherShadowPrimitives(
	TEXT("r.ParallelGatherShadowPrimitives"),
	1,  
	TEXT("Toggles parallel Gather shadow primitives. 0 = off; 1 = on"),
	ECVF_RenderThreadSafe
	);

int32 GParallelInitDynamicShadows = 1;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Public/PrimitiveSceneInfo.h:778

Scope: file

Source code excerpt:

struct FPrimitiveOctreeSemantics
{
	/** Note: this is coupled to shadow gather task granularity, see r.ParallelGatherShadowPrimitives. */
	enum { MaxElementsPerLeaf = 256 };
	enum { MinInclusiveElementsPerNode = 7 };
	enum { MaxNodeDepth = 12 };

	typedef FDefaultAllocator ElementAllocator;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarParallelGatherShadowPrimitives(
	TEXT("r.ParallelGatherShadowPrimitives"),
	1,  
	TEXT("Toggles parallel Gather shadow primitives. 0 = off; 1 = on"),
	ECVF_RenderThreadSafe
	);

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

Scope (from outer to inner):

file
function     FDynamicShadowsTaskData

Source code excerpt:

		, bStaticSceneOnly(AreAnyViewsStaticSceneOnly(Views))
		, bRunningEarly(bInRunningEarly)
		, bMultithreaded((FApp::ShouldUseThreadingForPerformance() || FForkProcessHelper::IsForkedMultithreadInstance()) && CVarParallelGatherShadowPrimitives.GetValueOnRenderThread() > 0)
		, bMultithreadedCreateAndFilterShadows(bRunningEarly && bMultithreaded && GRHISupportsAsyncGetRenderQueryResult && GParallelInitDynamicShadows > 0)
		, bMultithreadedGDME(bMultithreadedCreateAndFilterShadows && GetNumShadowDynamicMeshElementTasks() > 0)
	{
		if (bMultithreadedCreateAndFilterShadows)
		{
			RHICmdListForAllocateTargets = new FRHICommandList(FRHIGPUMask::All());