r.DOF.Scatter.BackgroundCompositing

r.DOF.Scatter.BackgroundCompositing

#Overview

name: r.DOF.Scatter.BackgroundCompositing

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).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DOF.Scatter.BackgroundCompositing is to control the compositing mode of the background hybrid scattering in the Depth of Field (DOF) effect. This setting is part of the rendering system, specifically for post-processing effects.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically in the Depth of Field (DOF) implementation. It’s defined and used in the DiaphragmDOF.cpp file, which is responsible for implementing the Diaphragm Depth of Field effect.

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

This variable interacts closely with another variable named CVarHybridScatterBackgroundMode. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the visual quality and performance of the Depth of Field effect. The different modes (0, 1, 2) offer a trade-off between visual quality and performance.

Best practices when using this variable include:

  1. Understanding the visual impact of each mode before changing it.
  2. Testing the performance impact of different modes in your specific scene.
  3. Considering the target hardware when selecting a mode, as more complex modes may not perform well on lower-end devices.

Regarding the associated variable CVarHybridScatterBackgroundMode:

The purpose of CVarHybridScatterBackgroundMode is the same as r.DOF.Scatter.BackgroundCompositing. It’s used internally in the C++ code to access the value set by the console variable.

This variable is used in the DiaphragmDOF::AddPasses function to determine the hybrid scattering mode for the background. It’s retrieved using GetValueOnRenderThread(), indicating that it’s accessed on the render thread for performance reasons.

Developers should be aware that changes to r.DOF.Scatter.BackgroundCompositing will affect CVarHybridScatterBackgroundMode, and vice versa. They should treat these as two interfaces to the same underlying setting.

When using this variable, developers should ensure that any code accessing it is thread-safe and optimized for render thread usage, following the patterns established in the existing code.

#Setting Variables

#References In INI files

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

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

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

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

#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:76

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<int32> CVarHybridScatterBackgroundMode(
	TEXT("r.DOF.Scatter.BackgroundCompositing"),
	2,
	TEXT("Compositing mode of the background hybrid scattering.\n")
	TEXT(" 0: Disabled;\n")
	TEXT(" 1: Additive;\n")
	TEXT(" 2: Gather occlusion (default)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarHybridScatterBackgroundMode(
	TEXT("r.DOF.Scatter.BackgroundCompositing"),
	2,
	TEXT("Compositing mode of the background hybrid scattering.\n")
	TEXT(" 0: Disabled;\n")
	TEXT(" 1: Additive;\n")
	TEXT(" 2: Gather occlusion (default)."),

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

Scope (from outer to inner):

file
function     bool DiaphragmDOF::AddPasses

Source code excerpt:

	// The mode for hybrid scattering.
	const EHybridScatterMode FgdHybridScatteringMode = EHybridScatterMode(CVarHybridScatterForegroundMode.GetValueOnRenderThread());
	const EHybridScatterMode BgdHybridScatteringMode = EHybridScatterMode(CVarHybridScatterBackgroundMode.GetValueOnRenderThread());
	
	const float MinScatteringCocRadius = FMath::Max(CVarScatterMinCocRadius.GetValueOnRenderThread(), kMinScatteringCocRadius);

	// Whether the platform support gather bokeh simmulation.
	const bool bSupportGatheringBokehSimulation = SupportsBokehSimmulation(ShaderPlatform);