r.Filter.LoopMode

r.Filter.LoopMode

#Overview

name: r.Filter.LoopMode

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.Filter.LoopMode is to control the loop mode used in Gaussian filtering for post-processing effects such as Gaussian Blur, Bloom, and Depth of Field in Unreal Engine’s rendering system.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the post-processing subsystem. It affects how the engine iterates over samples during Gaussian filtering operations.

The value of this variable is set through the console variable system, allowing it to be adjusted at runtime. It is defined as a TAutoConsoleVariable with an initial value of 0.

The associated variable CVarLoopMode directly interacts with r.Filter.LoopMode, as they share the same value and purpose.

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

  1. It affects the trade-off between performance and flexibility in sample count.
  2. The default value (0) uses unrolled loops, which are limited to 32 samples but may be more efficient.
  3. Non-zero values allow for dynamic loops, supporting up to 128 samples but with a potential performance cost due to additional loop stop tests.

Best practices when using this variable include:

  1. Use the default value (0) for most cases, as it provides a good balance of performance and quality.
  2. Increase the value only when higher sample counts are necessary for specific visual effects.
  3. Profile the performance impact when changing this setting, especially on target hardware.
  4. Consider the target platform’s capabilities, as some platforms (e.g., Metal MRT platforms) may have different maximum sample counts.

Regarding the associated variable CVarLoopMode:

The purpose of CVarLoopMode is identical to r.Filter.LoopMode, as they are essentially the same variable.

It is used in the same Renderer module and post-processing subsystem as r.Filter.LoopMode.

The value of CVarLoopMode is set through the console variable system, just like r.Filter.LoopMode.

CVarLoopMode directly interacts with r.Filter.LoopMode, as they share the same value and purpose.

Developers should be aware of the same considerations and follow the same best practices as mentioned for r.Filter.LoopMode when working with CVarLoopMode.

The main difference is that CVarLoopMode is the actual C++ variable used in the code to access and modify the setting, while r.Filter.LoopMode is the console command used to manipulate this setting externally.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessWeightedSampleSum.cpp:20

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<int32> CVarLoopMode(
	TEXT("r.Filter.LoopMode"),
	0,
	TEXT("Controls when to use either dynamic or unrolled loops to iterates over the Gaussian filtering.\n")
	TEXT("This passes is used for Gaussian Blur, Bloom and Depth of Field. The dynamic loop allows\n")
	TEXT("up to 128 samples versus the 32 samples of unrolled loops, but add an additional cost for\n")
	TEXT("the loop's stop test at every iterations.\n")
	TEXT(" 0: Unrolled loop only (default; limited to 32 samples).\n")

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessWeightedSampleSum.cpp:19

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

const int32 GFilterComputeTileSizeY = 8;

TAutoConsoleVariable<int32> CVarLoopMode(
	TEXT("r.Filter.LoopMode"),
	0,
	TEXT("Controls when to use either dynamic or unrolled loops to iterates over the Gaussian filtering.\n")
	TEXT("This passes is used for Gaussian Blur, Bloom and Depth of Field. The dynamic loop allows\n")
	TEXT("up to 128 samples versus the 32 samples of unrolled loops, but add an additional cost for\n")
	TEXT("the loop's stop test at every iterations.\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessWeightedSampleSum.cpp:117

Scope (from outer to inner):

file
function     uint32 GetSampleCountMax

Source code excerpt:

uint32 GetSampleCountMax(ERHIFeatureLevel::Type InFeatureLevel, EShaderPlatform InPlatform)
{
	if (CVarLoopMode.GetValueOnRenderThread() != 0)
	{
		return MAX_FILTER_SAMPLES;
	}
	else if (IsMetalMRTPlatform(InPlatform))
	{
		return MAX_FILTER_COMPILE_TIME_SAMPLES_IOS;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessWeightedSampleSum.cpp:204

Scope (from outer to inner):

file
function     uint32 GetStaticSampleCount

Source code excerpt:

uint32 GetStaticSampleCount(uint32 RequiredSampleCount)
{
	const int32 LoopMode = CVarLoopMode.GetValueOnRenderThread();

	const bool bForceStaticLoop = LoopMode == 0;

	const bool bForceDynamicLoop = LoopMode == 2;

	if (!bForceDynamicLoop && (bForceStaticLoop || RequiredSampleCount <= MAX_FILTER_COMPILE_TIME_SAMPLES))