r.ParallelGatherNumPrimitivesPerPacket

r.ParallelGatherNumPrimitivesPerPacket

#Overview

name: r.ParallelGatherNumPrimitivesPerPacket

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.ParallelGatherNumPrimitivesPerPacket is to control the number of primitives processed per packet during shadow culling operations in Unreal Engine’s rendering system. This setting is specifically used when the octree-based culling method is disabled.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the shadow setup and culling subsystem. Based on the callsites, it’s clear that this variable is utilized in the ShadowSetup.cpp file, which is part of the rendering pipeline.

The value of this variable is set through a console variable (CVarParallelGatherNumPrimitivesPerPacket) with a default value of 256. It can be modified at runtime through console commands or programmatically.

The associated variable CVarParallelGatherNumPrimitivesPerPacket interacts directly with r.ParallelGatherNumPrimitivesPerPacket, as they share the same value. This console variable is used to retrieve the current value of the setting in the code.

Developers must be aware that this setting is only relevant when the octree-based culling method is disabled (controlled by r.Shadow.UseOctreeForCulling). The value of this variable affects the performance and memory usage of the shadow culling process.

Best practices when using this variable include:

  1. Adjusting the value based on the specific needs of the project and target hardware.
  2. Monitoring performance impacts when modifying this value.
  3. Considering the relationship with other shadow-related settings, particularly r.Shadow.UseOctreeForCulling.

Regarding the associated variable CVarParallelGatherNumPrimitivesPerPacket:

The purpose of CVarParallelGatherNumPrimitivesPerPacket is to provide a convenient way to access and modify the r.ParallelGatherNumPrimitivesPerPacket setting within the C++ code.

This console variable is used in the Renderer module, specifically in the shadow setup and culling system. It allows for runtime modification of the setting and provides thread-safe access to its value.

The value of CVarParallelGatherNumPrimitivesPerPacket is set when the console variable is initialized, with a default value of 256. It can be modified through console commands or programmatically.

CVarParallelGatherNumPrimitivesPerPacket directly interacts with r.ParallelGatherNumPrimitivesPerPacket, as they represent the same setting.

Developers should be aware that this console variable is marked as render thread safe (ECVF_RenderThreadSafe), meaning it can be safely accessed from the render thread.

Best practices for using CVarParallelGatherNumPrimitivesPerPacket include:

  1. Using GetValueOnAnyThread() when accessing the value from different threads.
  2. Considering performance implications when modifying the value at runtime.
  3. Documenting any project-specific modifications to this setting for easier maintenance and optimization.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarParallelGatherNumPrimitivesPerPacket(
	TEXT("r.ParallelGatherNumPrimitivesPerPacket"),
	256,  
	TEXT("Number of primitives per packet.  Only used when r.Shadow.UseOctreeForCulling is disabled."),
	ECVF_RenderThreadSafe
	);

int32 GUseOctreeForShadowCulling = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

}

static TAutoConsoleVariable<int32> CVarParallelGatherNumPrimitivesPerPacket(
	TEXT("r.ParallelGatherNumPrimitivesPerPacket"),
	256,  
	TEXT("Number of primitives per packet.  Only used when r.Shadow.UseOctreeForCulling is disabled."),
	ECVF_RenderThreadSafe
	);

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

Scope (from outer to inner):

file
function     void AnyThreadTask

Source code excerpt:

		else
		{
			const int32 PacketSize = CVarParallelGatherNumPrimitivesPerPacket.GetValueOnAnyThread();
			const int32 NumPackets = FMath::DivideAndRoundUp(TaskData.Scene->Primitives.Num(), PacketSize);

			TaskData.Packets.Reserve(NumPackets);

			for (int32 PacketIndex = 0; PacketIndex < NumPackets; PacketIndex++)
			{