r.PathTracing.AdaptiveSampling

r.PathTracing.AdaptiveSampling

#Overview

name: r.PathTracing.AdaptiveSampling

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.AdaptiveSampling is to enable or disable adaptive sampling in the path tracing rendering process. This setting is part of Unreal Engine’s rendering system, specifically for path tracing.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the path tracing component. This can be seen from the file location where the variable is defined and used: Engine/Source/Runtime/Renderer/Private/PathTracing.cpp.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0 (off) but can be changed at runtime.

This variable interacts with other path tracing related variables, such as CVarPathTracingExperimental. The adaptive sampling is only enabled when both experimental features are on and this variable is set to non-zero.

Developers must be aware that:

  1. This feature is considered experimental, as it’s only enabled when experimental features are turned on.
  2. When enabled, it affects the path tracing algorithm by potentially skipping calculations for pixels below a certain error threshold.
  3. The error threshold for adaptive sampling is controlled by another variable (CVarPathTracingAdaptiveSamplingErrorThreshold).

Best practices when using this variable include:

  1. Only enable it in conjunction with experimental features for testing purposes.
  2. Monitor performance and image quality when enabled, as it may affect both.
  3. Adjust the error threshold if needed to balance between performance gain and image quality.

Regarding the associated variable CVarPathTracingAdaptiveSampling:

This is the actual console variable that controls the r.PathTracing.AdaptiveSampling setting. It’s defined as an integer variable with two possible values: 0 (off) and 1 (on). It’s used in the path tracing code to determine whether adaptive sampling should be applied.

The variable is used in the GetPathTracingRGPermutation function to set up the permutation domain for the path tracing render graph. It’s also used when setting up the path tracing configuration (Config.UseAdaptiveSampling).

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag used in its declaration.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarPathTracingAdaptiveSampling(
	TEXT("r.PathTracing.AdaptiveSampling"),
	0,
	TEXT("Determines if adaptive sampling is enabled. When non-zero, the path tracer will try to skip calculation of pixels below the specified error threshold.\n")
	TEXT("0: off (uniform sampling - default)\n")
	TEXT("1: on (adaptive sampling)\n"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingAdaptiveSampling(
	TEXT("r.PathTracing.AdaptiveSampling"),
	0,
	TEXT("Determines if adaptive sampling is enabled. When non-zero, the path tracer will try to skip calculation of pixels below the specified error threshold.\n")
	TEXT("0: off (uniform sampling - default)\n")
	TEXT("1: on (adaptive sampling)\n"),
	ECVF_RenderThreadSafe

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

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);
	Out.Set<FPathTracingRG::FSubstrateComplexSpecialMaterial>(bHasComplexSpecialRenderPath);

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

Scope: file

Source code excerpt:

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

	// compute an integer code of what show flags and booleans related to lights are currently enabled so we can detect changes
	Config.LightShowFlags = 0;
	Config.LightShowFlags |= View.Family->EngineShowFlags.SkyLighting           ? 1 << 0 : 0;
	Config.LightShowFlags |= View.Family->EngineShowFlags.DirectionalLights     ? 1 << 1 : 0;