r.PathTracing.AdaptiveSampling.ErrorThreshold

r.PathTracing.AdaptiveSampling.ErrorThreshold

#Overview

name: r.PathTracing.AdaptiveSampling.ErrorThreshold

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.AdaptiveSampling.ErrorThreshold is to control the adaptive sampling process in the path tracing rendering system of Unreal Engine 5. It sets a target perceptual error threshold for determining when to stop sampling pixels during the path tracing process.

This setting variable is primarily used by the rendering system, specifically the path tracing module within Unreal Engine 5. Based on the callsites, it’s clear that this variable is utilized in the PathTracing.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0.001f, but can be changed at runtime through console commands or project settings.

The variable interacts directly with its associated C++ variable CVarPathTracingAdaptiveSamplingErrorThreshold. This C++ variable is used to retrieve the current value of the setting in the rendering code.

Developers should be aware that this variable significantly impacts the performance and quality trade-off in path tracing. A lower threshold will result in higher quality images but longer rendering times, while a higher threshold will produce faster results but potentially noisier images.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your scene. More complex scenes might require a lower threshold for acceptable quality.
  2. Using it in conjunction with other path tracing settings for optimal results.
  3. Testing different values to find the right balance between image quality and performance for your specific use case.

Regarding the associated variable CVarPathTracingAdaptiveSamplingErrorThreshold:

This is the C++ implementation of the console variable. It’s used to store and retrieve the current value of the error threshold setting. The purpose is the same as r.PathTracing.AdaptiveSampling.ErrorThreshold, but it’s the programmatic interface for accessing the value.

It’s used within the rendering system to apply the error threshold during the path tracing process. As seen in the second callsite, it’s retrieved using GetValueOnRenderThread() and assigned to Config.AdaptiveSamplingThreshold, which is likely a configuration struct used by the path tracing algorithm.

Developers working directly with the C++ code should use this variable when they need to access or modify the error threshold value programmatically. It’s important to note that changes to this variable will directly affect the path tracing process, so it should be handled with care in performance-critical sections of code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<float> CVarPathTracingAdaptiveSamplingErrorThreshold(
	TEXT("r.PathTracing.AdaptiveSampling.ErrorThreshold"),
	0.001f,
	TEXT("This is the target perceptual error threshold. Once a pixel's error falls below this value, it will not be sampled again (default: 0.001)\n"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarPathTracingAdaptiveSamplingVisualize(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<float> CVarPathTracingAdaptiveSamplingErrorThreshold(
	TEXT("r.PathTracing.AdaptiveSampling.ErrorThreshold"),
	0.001f,
	TEXT("This is the target perceptual error threshold. Once a pixel's error falls below this value, it will not be sampled again (default: 0.001)\n"),
	ECVF_RenderThreadSafe
);

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

Scope: file

Source code excerpt:

	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;
	Config.LightShowFlags |= View.Family->EngineShowFlags.RectLights            ? 1 << 2 : 0;