r.SkinCache.MaxRayTracingPrimitivesPerCmdList

r.SkinCache.MaxRayTracingPrimitivesPerCmdList

#Overview

name: r.SkinCache.MaxRayTracingPrimitivesPerCmdList

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

• type: Var
• help: Maximum amount of primitives which are batched together into a single command list to fix potential TDRs.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.SkinCache.MaxRayTracingPrimitivesPerCmdList is to control the maximum number of ray tracing primitives that can be batched together into a single command list for skinned geometry updates in the ray tracing system. This setting is primarily used to prevent potential Time Detection and Recovery (TDR) issues that may occur when processing large amounts of ray tracing data.

This setting variable is utilized by the ray tracing subsystem within Unreal Engine’s rendering module. Specifically, it is used in the FRayTracingSkinnedGeometryUpdateQueue class, which is responsible for managing updates to skinned geometry for ray tracing.

The value of this variable is set through the Unreal Engine console variable system. It is defined as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files.

The associated variable GMaxRayTracingPrimitivesPerCmdList directly interacts with r.SkinCache.MaxRayTracingPrimitivesPerCmdList. They share the same value, with GMaxRayTracingPrimitivesPerCmdList being the actual integer variable used in the code logic.

Developers must be aware that:

1. This variable affects performance and stability of ray tracing for skinned geometry.
2. Setting the value too low might impact performance by causing more frequent command list submissions.
3. Setting the value too high might lead to TDR issues on some hardware configurations.

Best practices when using this variable include:

1. Leave it at the default value (-1) unless experiencing specific TDR issues related to skinned geometry ray tracing.
2. If TDR issues occur, start by setting a relatively high value (e.g., 1000) and gradually decrease it until the issues are resolved.
3. Monitor performance impacts when adjusting this value, as it may affect frame rates.
4. Document any changes made to this variable in project settings or documentation for future reference.

Regarding the associated variable GMaxRayTracingPrimitivesPerCmdList:

• It is the actual integer variable used in the code logic to control the batching of ray tracing primitives.
• It is used in the Commit function of FRayTracingSkinnedGeometryUpdateQueue to determine when to flush a batch of primitives and submit a command list.
• When its value is greater than 0, it limits the number of primitives processed in a single batch, potentially preventing TDR issues at the cost of more frequent command list submissions.
• Developers should be aware that modifying r.SkinCache.MaxRayTracingPrimitivesPerCmdList directly affects this variable’s value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/RayTracingSkinnedGeometry.cpp:28

Scope: file

Source code excerpt:

static int32 GMaxRayTracingPrimitivesPerCmdList = -1;
FAutoConsoleVariableRef CVarSkinnedGeometryMaxRayTracingPrimitivesPerCmdList(
	TEXT("r.SkinCache.MaxRayTracingPrimitivesPerCmdList"),
	GMaxRayTracingPrimitivesPerCmdList,
	TEXT("Maximum amount of primitives which are batched together into a single command list to fix potential TDRs."),
	ECVF_RenderThreadSafe
);

void FRayTracingSkinnedGeometryUpdateQueue::Add(FRayTracingGeometry* InRayTracingGeometry, const FRayTracingAccelerationStructureSize& StructureSize)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/RayTracingSkinnedGeometry.cpp:26

Scope: file

Source code excerpt:

);

static int32 GMaxRayTracingPrimitivesPerCmdList = -1;
FAutoConsoleVariableRef CVarSkinnedGeometryMaxRayTracingPrimitivesPerCmdList(
	TEXT("r.SkinCache.MaxRayTracingPrimitivesPerCmdList"),
	GMaxRayTracingPrimitivesPerCmdList,
	TEXT("Maximum amount of primitives which are batched together into a single command list to fix potential TDRs."),
	ECVF_RenderThreadSafe
);

void FRayTracingSkinnedGeometryUpdateQueue::Add(FRayTracingGeometry* InRayTracingGeometry, const FRayTracingAccelerationStructureSize& StructureSize)
{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/RayTracingSkinnedGeometry.cpp:189

Scope (from outer to inner):

file
function     void FRayTracingSkinnedGeometryUpdateQueue::Commit

Source code excerpt:

			// Flush batch when limit is reached
			if (GMaxRayTracingPrimitivesPerCmdList > 0 && PrimitivesToUpdates >= GMaxRayTracingPrimitivesPerCmdList)
			{
				KickBatch();
				RHICmdList.SubmitCommandsHint();
			}
		}