r.PathTracing.TemporalDenoiser.DistanceMetrics

r.PathTracing.TemporalDenoiser.DistanceMetrics

#Overview

name: r.PathTracing.TemporalDenoiser.DistanceMetrics

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.TemporalDenoiser.DistanceMetrics is to control the distance metric used in the temporal denoiser for path tracing in Unreal Engine 5’s rendering system. This setting variable is specifically used in the path tracing temporal denoising process.

Based on the callsites, this setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically in the path tracing and temporal denoising subsystem.

The value of this variable is set through a console variable (CVar) system, which allows for runtime configuration. It is initialized with a default value of 2, but can be changed during runtime or through configuration files.

This variable interacts directly with its associated variable CVarPathTracingTemporalDenoiserDistanceMetrics. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable accepts three different values (0, 1, or 2), each corresponding to a different distance metric: 0: Luminance-based metrics 1: Direct color difference 2: Visual color difference based on CIELAB2000

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

  1. Understand the implications of each distance metric on the final rendered image.
  2. Test different values to find the best balance between performance and visual quality for their specific use case.
  3. Be aware that using luminance-based metrics (0) may create errors in motion and history weight estimation for colors with the same luminance.
  4. Consider using the CIELAB2000-based metric (2) for potentially more visually accurate results, as it’s the default setting.

Regarding the associated variable CVarPathTracingTemporalDenoiserDistanceMetrics: This is the actual console variable that stores and provides access to the distance metric setting. It is used in the GetDistanceMetrics() function to retrieve the current value and ensure it’s within the valid range. Developers should use this variable when they need to programmatically access or modify the distance metric setting in C++ code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracingSpatialTemporalDenoising.cpp:217

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	TAutoConsoleVariable<int32> CVarPathTracingTemporalDenoiserDistanceMetrics(
		TEXT("r.PathTracing.TemporalDenoiser.DistanceMetrics"),
		2,
		TEXT("0: Luminance based metrics for distance estimation. Color with same luminance will create error in motion and history weights estimation.")
		TEXT("1: Direct color difference")
		TEXT("2: Visual color difference based on CIELAB2000 color difference."),
		ECVF_RenderThreadSafe
	);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracingSpatialTemporalDenoising.cpp:216

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	);

	TAutoConsoleVariable<int32> CVarPathTracingTemporalDenoiserDistanceMetrics(
		TEXT("r.PathTracing.TemporalDenoiser.DistanceMetrics"),
		2,
		TEXT("0: Luminance based metrics for distance estimation. Color with same luminance will create error in motion and history weights estimation.")
		TEXT("1: Direct color difference")
		TEXT("2: Visual color difference based on CIELAB2000 color difference."),
		ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracingSpatialTemporalDenoising.cpp:599

Scope (from outer to inner):

file
class        class FTemporalReprojectionAlignCS : public FGlobalShader
function     static EDistanceMetrics GetDistanceMetrics

Source code excerpt:

	static EDistanceMetrics GetDistanceMetrics()
	{
		uint32 DistanceMetrics = CVarPathTracingTemporalDenoiserDistanceMetrics.GetValueOnRenderThread();
		DistanceMetrics = FMath::Clamp(DistanceMetrics, 
			static_cast<uint32>(EDistanceMetrics::METRICS_LUMINANCE),
			static_cast<uint32>(EDistanceMetrics::MAX) - 1);

		return static_cast<EDistanceMetrics>(DistanceMetrics);
	}