r.PathTracing.Compaction

r.PathTracing.Compaction

#Overview

name: r.PathTracing.Compaction

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

• type: Var
• help: Enables path compaction to improve GPU occupancy for the path tracer (default: 1 (enabled))

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.Compaction is to enable path compaction in the path tracing system of Unreal Engine 5’s rendering pipeline. This setting is designed to improve GPU occupancy for the path tracer.

• The r.PathTracing.Compaction setting is primarily used by the rendering system, specifically the path tracing subsystem of Unreal Engine 5.

• This setting is utilized within the Renderer module, as evidenced by its implementation in the PathTracing.cpp file.

• The value of this variable is set using a console variable (CVarPathTracingCompaction) with a default value of 1 (enabled). It can be modified at runtime through console commands or programmatically.

• This variable interacts with other path tracing settings, such as CVarPathTracingExperimental and CVarPathTracingAdaptiveSampling, to determine the overall behavior of the path tracing system.

• Developers should be aware that this setting affects GPU performance and rendering quality. Enabling path compaction can improve GPU occupancy, potentially leading to better performance, but may have implications on the rendering process.

• Best practices when using this variable include:

  1. Testing performance with and without compaction to determine the optimal setting for your specific scene and hardware.
  2. Considering the interaction with other path tracing settings, especially when using experimental features.
  3. Monitoring GPU performance metrics when adjusting this setting.

Regarding the associated variable CVarPathTracingCompaction:

The purpose of CVarPathTracingCompaction is to provide programmatic access to the r.PathTracing.Compaction setting within the engine’s C++ code.

• This variable is used directly in the rendering system to control path compaction behavior.

• The value of CVarPathTracingCompaction is set when the console variable is initialized and can be accessed using the GetValueOnRenderThread() method.

• It interacts closely with other path tracing settings and is used in conditional statements to determine the rendering behavior.

• Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it’s safe to access from the render thread.

• Best practices for using CVarPathTracingCompaction include:

  1. Accessing its value using GetValueOnRenderThread() when in render thread context.
  2. Considering thread safety when accessing or modifying this variable from different parts of the engine.
  3. Using this variable in conjunction with other path tracing settings to create cohesive rendering logic.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarPathTracingCompaction(
	TEXT("r.PathTracing.Compaction"),
	1,
	TEXT("Enables path compaction to improve GPU occupancy for the path tracer (default: 1 (enabled))"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarPathTracingIndirectDispatch(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarPathTracingCompaction(
	TEXT("r.PathTracing.Compaction"),
	1,
	TEXT("Enables path compaction to improve GPU occupancy for the path tracer (default: 1 (enabled))"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     static FPathTracingRG::FPermutationDomain GetPathTracingRGPermutation

Source code excerpt:

{
	const bool bUseExperimental = CVarPathTracingExperimental.GetValueOnRenderThread() != 0;
	const bool bUseCompaction = (bUseExperimental == false) || CVarPathTracingCompaction.GetValueOnRenderThread() != 0;
	const bool bUseAdaptiveSampling = bUseExperimental && CVarPathTracingAdaptiveSampling.GetValueOnRenderThread() != 0;
	const bool bHasComplexSpecialRenderPath = Substrate::IsSubstrateEnabled() && Scene.SubstrateSceneData.bUsesComplexSpecialRenderPath;

	FPathTracingRG::FPermutationDomain Out;
	Out.Set<FPathTracingRG::FCompactionType>(bUseCompaction);
	Out.Set<FPathTracingRG::FAdaptiveSampling>(bUseAdaptiveSampling);

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

Scope: file

Source code excerpt:

			// should we use path compaction?
			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;