r.DOF.Gather.RingCount

r.DOF.Gather.RingCount

#Overview

name: r.DOF.Gather.RingCount

The value of this variable can be defined or overridden in .ini config files. 4 .ini config files referencing this setting variable.

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

• type: Var
• help: Number of rings for gathering kernels [[3; 5]]. Default to 5.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DOF.Gather.RingCount is to control the number of sampling rings in the gathering kernel for the Depth of Field (DOF) effect in Unreal Engine’s rendering system. This setting variable is specifically used in the Diaphragm DOF implementation.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the post-processing subsystem for Depth of Field effects. The code references are found in the DiaphragmDOF.cpp file, which is part of the post-processing pipeline.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 5, but can be changed at runtime or through configuration files. The allowed range is between 3 and 5, as indicated in the comment.

The associated variable CVarRingCount directly interacts with r.DOF.Gather.RingCount. They share the same value and purpose. CVarRingCount is the actual console variable object that stores and manages the value of r.DOF.Gather.RingCount.

Developers must be aware that:

1. This variable affects the quality and performance of the Depth of Field effect.
2. The value is clamped between the minimum gathering ring count (3) and the maximum allowed for the current shader platform.
3. Changes to this variable are considered scalability settings and are render thread safe.

Best practices when using this variable include:

1. Use lower values for better performance, higher values for better quality.
2. Consider the target hardware when setting this value, as it can impact performance.
3. Test different values to find the best balance between visual quality and performance for your specific use case.

Regarding the associated variable CVarRingCount:

• Its purpose is the same as r.DOF.Gather.RingCount, to control the number of sampling rings in the DOF gathering kernel.
• It’s used in the same Renderer module and DiaphragmDOF implementation.
• The value is set at initialization and can be modified at runtime through the console or configuration files.
• It directly interacts with r.DOF.Gather.RingCount, effectively being the same setting.
• Developers should be aware that this is the actual variable used in the code to retrieve the current value (using GetValueOnRenderThread()).
• Best practices for CVarRingCount are the same as for r.DOF.Gather.RingCount, as they represent the same setting.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:433, section: [PostProcessQuality@1]

• INI Section: PostProcessQuality@1
• Raw value: 3 ; low number of samples when gathering
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:466, section: [PostProcessQuality@2]

• INI Section: PostProcessQuality@2
• Raw value: 4 ; medium number of samples when gathering
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:501, section: [PostProcessQuality@3]

• INI Section: PostProcessQuality@3
• Raw value: 4 ; medium number of samples when gathering
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:539, section: [PostProcessQuality@Cine]

• INI Section: PostProcessQuality@Cine
• Raw value: 5 ; high number of samples when gathering
• Is Array: False

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/DiaphragmDOF.cpp:61

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

TAutoConsoleVariable<int32> CVarRingCount(
	TEXT("r.DOF.Gather.RingCount"),
	5,
	TEXT("Number of rings for gathering kernels [[3; 5]]. Default to 5.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe);


TAutoConsoleVariable<int32> CVarHybridScatterForegroundMode(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/DiaphragmDOF.cpp:60

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarRingCount(
	TEXT("r.DOF.Gather.RingCount"),
	5,
	TEXT("Number of rings for gathering kernels [[3; 5]]. Default to 5.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/DiaphragmDOF.cpp:1389

Scope (from outer to inner):

file
function     bool DiaphragmDOF::AddPasses

Source code excerpt:

	// Number of sampling ring in the gathering kernel.
	const int32 HalfResRingCount = FMath::Clamp(CVarRingCount.GetValueOnRenderThread(), kMinGatheringRingCount, MaxGatheringRingCount(ShaderPlatform));

	// Post filtering method to do.
	const EDiaphragmDOFPostfilterMethod PostfilterMethod = GetPostfilteringMethod();

	// The mode for hybrid scattering.
	const EHybridScatterMode FgdHybridScatteringMode = EHybridScatterMode(CVarHybridScatterForegroundMode.GetValueOnRenderThread());