r.PathTracing.DispatchSize

r.PathTracing.DispatchSize

#Overview

name: r.PathTracing.DispatchSize

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.PathTracing.DispatchSize is to control the tile size used when rendering the image in the path tracing system of Unreal Engine 5. This setting is primarily used in the rendering system, specifically for path tracing.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its usage in the “PathTracing.cpp” file within the Runtime/Renderer/Private directory.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 2048, but can be changed at runtime using console commands or through project settings.

This variable interacts with the associated C++ variable CVarPathTracingDispatchSize. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the performance and stability of path tracing renders. As mentioned in the comment, reducing this value may prevent GPU timeouts for heavy renders. This suggests that if developers are experiencing GPU timeouts during path tracing, they should consider lowering this value.

Best practices when using this variable include:

  1. Start with the default value (2048) and adjust as needed.
  2. If experiencing GPU timeouts or performance issues with complex scenes, try reducing the value.
  3. Keep in mind that smaller values may increase the overall render time but can improve stability.
  4. For multi-GPU setups, be aware that this value interacts with the number of GPUs and passes per frame.

Regarding the associated variable CVarPathTracingDispatchSize:

The purpose of CVarPathTracingDispatchSize is to provide a C++ interface to the r.PathTracing.DispatchSize console variable within the engine’s code.

This variable is used directly in the path tracing rendering code to determine the dispatch size for rendering tiles. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to the current value.

The value of this variable is set when the console variable is initialized and can be changed through the same mechanisms as r.PathTracing.DispatchSize.

Developers should be aware that this variable is used in performance-critical rendering code, so frequent changes or extremely low values might impact rendering performance.

Best practices for using CVarPathTracingDispatchSize include:

  1. Use GetValueOnRenderThread() when accessing the value in render thread code.
  2. Consider caching the value if it’s used multiple times in performance-critical sections.
  3. Be cautious about changing this value frequently during runtime, as it could affect rendering consistency.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarPathTracingDispatchSize(
	TEXT("r.PathTracing.DispatchSize"),
	2048,
	TEXT("Controls the tile size used when rendering the image. Reducing this value may prevent GPU timeouts for heavy renders. (default = 2048)"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarPathTracingMaxBounces(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingDispatchSize(
	TEXT("r.PathTracing.DispatchSize"),
	2048,
	TEXT("Controls the tile size used when rendering the image. Reducing this value may prevent GPU timeouts for heavy renders. (default = 2048)"),
	ECVF_RenderThreadSafe
);

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

Scope: file

Source code excerpt:

	const int32 DispatchResX = View.ViewRect.Size().X;
	const int32 DispatchResY = View.ViewRect.Size().Y;
	const int32 DispatchSize = FMath::Max(CVarPathTracingDispatchSize.GetValueOnRenderThread(), 64);

	// When running with multiple GPUs, do that number of passes per frame, to keep the GPU work done per frame consistent
	// (given that each GPU processes a fraction of the pixels), but get the job done in fewer frames.
#if WITH_MGPU
	const int32 FramePassCount = !View.bIsOfflineRender && CVarPathTracingAdjustMultiGPUPasses.GetValueOnRenderThread() ? NumGPUs : 1;
#else