r.PathTracing.FlushDispatch

r.PathTracing.FlushDispatch

#Overview

name: r.PathTracing.FlushDispatch

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

• type: Var
• help: Enables flushing of the command list after dispatch to reduce the likelyhood of TDRs on Windows (default: 2)\n0: off\n1: flush after each dispatch\n2: flush after each tile\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.FlushDispatch is to control the flushing of command lists during path tracing rendering to reduce the likelihood of Timeout Detection and Recovery (TDR) events on Windows systems. This setting is part of Unreal Engine’s rendering system, specifically the path tracing subsystem.

This setting variable is primarily used in the Renderer module of Unreal Engine, as evidenced by its location in the PathTracing.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set through a console variable (CVarPathTracingFlushDispatch) with a default value of 2. It can be changed at runtime using console commands or through configuration files.

The associated variable CVarPathTracingFlushDispatch interacts directly with r.PathTracing.FlushDispatch, as they share the same value. This console variable is used to access the setting’s value within the C++ code.

Developers must be aware that this variable has three possible values: 0: Flushing is disabled 1: Flush after each dispatch 2: Flush after each tile (default)

When using this variable, developers should consider the following best practices:

1. Leave the default value (2) unless experiencing specific performance issues or TDRs.
2. If TDRs occur frequently during path tracing, try setting the value to 1 for more frequent flushing.
3. Only disable flushing (value 0) if you’re certain it won’t cause stability issues on target hardware.
4. Monitor performance impacts when changing this value, as more frequent flushing may affect rendering speed.

Regarding the associated variable CVarPathTracingFlushDispatch:

• It is an instance of TAutoConsoleVariable, which allows for runtime modification of the setting.
• It is used in the code to retrieve the current value of the setting using GetValueOnRenderThread().
• Developers should use this variable when they need to access the flush dispatch setting in C++ code, particularly within render thread operations.
• Best practices for using CVarPathTracingFlushDispatch include checking its value only on the render thread and caching the result if used frequently to avoid repeated calls to GetValueOnRenderThread().

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:60

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarPathTracingFlushDispatch(
	TEXT("r.PathTracing.FlushDispatch"),
	2,
	TEXT("Enables flushing of the command list after dispatch to reduce the likelyhood of TDRs on Windows (default: 2)\n")
	TEXT("0: off\n")
	TEXT("1: flush after each dispatch\n")
	TEXT("2: flush after each tile\n"),
	ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:59

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingFlushDispatch(
	TEXT("r.PathTracing.FlushDispatch"),
	2,
	TEXT("Enables flushing of the command list after dispatch to reduce the likelyhood of TDRs on Windows (default: 2)\n")
	TEXT("0: off\n")
	TEXT("1: flush after each dispatch\n")
	TEXT("2: flush after each tile\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:2789

Scope: file

Source code excerpt:

			const bool bUseCompaction = (bUseExperimental == false) || CVarPathTracingCompaction.GetValueOnRenderThread() != 0;
			const bool bUseIndirectDispatch = GRHISupportsRayTracingDispatchIndirect && CVarPathTracingIndirectDispatch.GetValueOnRenderThread() != 0;
			const int FlushRenderingCommands = CVarPathTracingFlushDispatch.GetValueOnRenderThread();

			FRDGBuffer* ActivePaths[2] = {};
			FRDGBuffer* NumActivePaths[2] = {};
			FRDGBuffer* PathStateData = nullptr;
			if (bUseCompaction || Config.UseAdaptiveSampling)
			{