r.PathTracing.SamplesPerPixel

r.PathTracing.SamplesPerPixel

#Overview

name: r.PathTracing.SamplesPerPixel

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

• type: Var
• help: Sets the maximum number of samples per pixel (default = -1 (driven by postprocesing volume))

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.SamplesPerPixel is to control the maximum number of samples per pixel in the path tracing rendering system of Unreal Engine 5. This setting is crucial for balancing image quality and performance in path-traced rendering.

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 -1, which means it’s driven by the post-processing volume settings by default. However, developers can override this value through the console or configuration files.

The associated variable CVarPathTracingSamplesPerPixel interacts directly with r.PathTracing.SamplesPerPixel. It’s the actual C++ variable that holds the value set by the console variable.

Developers must be aware of several things when using this variable:

1. A value of -1 means the samples per pixel is controlled by the post-processing volume settings.
2. The actual number of samples used will be the maximum of 1 and the specified value, ensuring at least one sample per pixel.
3. This setting doesn’t apply when using offline rendering (View.bIsOfflineRender).

Best practices when using this variable include:

1. Use lower values for performance-critical scenarios or real-time applications.
2. Increase the value for higher quality renders, especially for still images or cinematics.
3. Consider using the default (-1) to allow for more flexible control through post-processing volumes in different areas of your game or application.
4. Be mindful of the performance impact when increasing this value, as higher sample counts can significantly increase render times.

Regarding the associated variable CVarPathTracingSamplesPerPixel:

• It’s an instance of TAutoConsoleVariable, which is Unreal’s way of creating console variables.
• It’s used to get the current value of the samples per pixel setting on the render thread (GetValueOnRenderThread()).
• The value from this variable is used to determine the MaxSPP (maximum samples per pixel) in the path tracing logic.
• When working with this variable directly in C++ code, developers should use the GetValueOnRenderThread() method to ensure thread-safe access to the current value.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarPathTracingSamplesPerPixel(
	TEXT("r.PathTracing.SamplesPerPixel"),
	-1,
	TEXT("Sets the maximum number of samples per pixel (default = -1 (driven by postprocesing volume))"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<float> CVarPathTracingFilterWidth(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingSamplesPerPixel(
	TEXT("r.PathTracing.SamplesPerPixel"),
	-1,
	TEXT("Sets the maximum number of samples per pixel (default = -1 (driven by postprocesing volume))"),
	ECVF_RenderThreadSafe
);

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

Scope: file

Source code excerpt:

	// Get current value of MaxSPP and reset render if it has changed
	// NOTE: we ignore the CVar when using offline rendering
	int32 SamplesPerPixelCVar = View.bIsOfflineRender ? -1 : CVarPathTracingSamplesPerPixel.GetValueOnRenderThread();
	uint32 MaxSPP = SamplesPerPixelCVar > -1 ? SamplesPerPixelCVar : View.FinalPostProcessSettings.PathTracingSamplesPerPixel;
	MaxSPP = FMath::Max(MaxSPP, 1u);

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

	Config.LockedSamplingPattern = CVarPathTracingFrameIndependentTemporalSeed.GetValueOnRenderThread() == 0;