r.PathTracing.Experimental

r.PathTracing.Experimental

#Overview

name: r.PathTracing.Experimental

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.Experimental is to enable experimental features in the path tracing renderer of Unreal Engine 5. This setting variable is specifically designed for the rendering system, particularly the path tracing component.

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 a console variable (CVarPathTracingExperimental) with an initial value of 0, meaning the experimental features are disabled by default. It can be changed at runtime through console commands or programmatically.

This variable interacts with several other variables and settings:

  1. It affects the compilation of shader permutations in the FPathTracingRG class.
  2. It influences the use of compaction and adaptive sampling in path tracing.
  3. It’s used in conjunction with other path tracing-related console variables like CVarPathTracingCompaction and CVarPathTracingAdaptiveSampling.

Developers must be aware of the following when using this variable:

  1. It’s marked as ECVF_RenderThreadSafe and ECVF_ReadOnly, meaning it’s safe to read from any thread but should not be modified after engine initialization.
  2. Enabling this variable may increase compilation time and memory usage due to additional shader permutations.
  3. The experimental features it enables may not be fully tested or optimized for production use.

Best practices when using this variable include:

  1. Only enable it in development or testing environments, not in production builds.
  2. Monitor performance and stability when enabled, as experimental features may impact these aspects.
  3. Be prepared to recompile shaders when changing this setting.

Regarding the associated variable CVarPathTracingExperimental: The purpose of CVarPathTracingExperimental is to provide a programmatic interface to control the r.PathTracing.Experimental setting. It’s an instance of TAutoConsoleVariable, which allows for runtime modification of the setting through console commands or C++ code.

This variable is used throughout the path tracing implementation to conditionally enable or disable experimental features. It’s important for developers to use this variable consistently when checking for experimental feature availability, rather than directly accessing the console variable string.

When working with CVarPathTracingExperimental, developers should:

  1. Use the appropriate thread-safe accessor methods (GetValueOnAnyThread() or GetValueOnRenderThread()) depending on the context.
  2. Be aware that changes to this variable may require shader recompilation or other expensive operations.
  3. Consider wrapping usage of experimental features in preprocessor macros or runtime checks to easily disable them in shipping builds.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarPathTracingExperimental(
	TEXT("r.PathTracing.Experimental"),
	0,
	TEXT("Enables some experimental features of the path tracing renderer that require compiling additional permutations of the path tracer."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#include "EnvironmentComponentsFlags.h"

TAutoConsoleVariable<int32> CVarPathTracingExperimental(
	TEXT("r.PathTracing.Experimental"),
	0,
	TEXT("Enables some experimental features of the path tracing renderer that require compiling additional permutations of the path tracer."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

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

Scope (from outer to inner):

file
function     class FCompactionType : SHADER_PERMUTATION_BOOL
class        class FCompactionType : SHADER_PERMUTATION_BOOL("PATH_TRACER_USE_COMPACTION"); class FAdaptiveSampling : SHADER_PERMUTATION_BOOL("PATH_TRACER_USE_ADAPTIVE_SAMPLING"); class FSubstrateComplexSpecialMaterial : SHADER_PERMUTATION_BOOL("PATH_TRACER_USE_SUBSTRATE_SPECIAL_COMPLEX_MATERIAL"); using FPermutationDomain = TShaderPermutationDomain<FCompactionType, FAdaptiveSampling, FSubstrateComplexSpecialMaterial>; static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& Parameters)

Source code excerpt:

	static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& Parameters)
	{
		const bool bUseExperimental = CVarPathTracingExperimental.GetValueOnAnyThread() != 0;
		FPermutationDomain PermutationVector(Parameters.PermutationId);
		if (bUseExperimental == false)
		{
			
			if (PermutationVector.Get<FCompactionType>() == 0)
			{

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

Scope (from outer to inner):

file
function     static FPathTracingRG::FPermutationDomain GetPathTracingRGPermutation

Source code excerpt:

static FPathTracingRG::FPermutationDomain GetPathTracingRGPermutation(const FScene& Scene)
{
	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);

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

Scope: file

Source code excerpt:

	MaxSPP = FMath::Max(MaxSPP, 1u);

	const bool bUseExperimental = CVarPathTracingExperimental.GetValueOnRenderThread() != 0;

	Config.LockedSamplingPattern = CVarPathTracingFrameIndependentTemporalSeed.GetValueOnRenderThread() == 0;
	Config.UseCameraMediumTracking = CVarPathTracingCameraMediumTracking.GetValueOnRenderThread() != 0;
	Config.UseAdaptiveSampling = bUseExperimental && CVarPathTracingAdaptiveSampling.GetValueOnAnyThread() != 0;
	Config.AdaptiveSamplingThreshold = CVarPathTracingAdaptiveSamplingErrorThreshold.GetValueOnRenderThread();