r.DOF.Scatter.MaxSpriteRatio

r.DOF.Scatter.MaxSpriteRatio

#Overview

name: r.DOF.Scatter.MaxSpriteRatio

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

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

• type: Var
• help: Maximum ratio of scattered pixel quad as sprite, usefull to control DOF\'s scattering upperbound. 1 will allow to scatter 100% pixel quads, whereas 0.2 will only allow 20% (default = 0.1).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DOF.Scatter.MaxSpriteRatio is to control the maximum ratio of scattered pixel quads as sprites in the Depth of Field (DOF) effect’s scattering process. This setting is part of the rendering system, specifically for the post-processing stage.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the Diaphragm Depth of Field implementation. It’s referenced in the DiaphragmDOF.cpp file, which is responsible for handling the DOF effect.

The value of this variable is set using a TAutoConsoleVariable, which means it can be adjusted at runtime through console commands. The default value is set to 0.1f (10%).

The associated variable CVarScatterMaxSpriteRatio directly interacts with r.DOF.Scatter.MaxSpriteRatio. They share the same value and purpose.

Developers must be aware that:

1. This variable affects the performance and quality of the DOF effect.
2. The value is clamped between 0.0 and 1.0 in the actual implementation.
3. Higher values allow for more scattered pixel quads, which can increase the quality of the DOF effect but may impact performance.

Best practices when using this variable include:

1. Adjusting it based on the target platform’s performance capabilities.
2. Testing different values to find the right balance between visual quality and performance.
3. Consider using lower values for mobile or lower-end platforms to maintain performance.

Regarding the associated variable CVarScatterMaxSpriteRatio:

• It serves the same purpose as r.DOF.Scatter.MaxSpriteRatio.
• It’s used to retrieve the actual value in the rendering code (GetValueOnRenderThread()).
• Developers should treat it as the programmatic interface to the r.DOF.Scatter.MaxSpriteRatio setting.
• When modifying the DOF implementation, use CVarScatterMaxSpriteRatio.GetValueOnRenderThread() to access the current value of the setting.

#Setting Variables

#References In INI files

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

• INI Section: PostProcessQuality@2
• Raw value: 0.04 ; only a maximum of 4% of scattered bokeh
• Is Array: False

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

• INI Section: PostProcessQuality@3
• Raw value: 0.1 ; only a maximum of 10% of scattered bokeh
• Is Array: False

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

• INI Section: PostProcessQuality@Cine
• Raw value: 0.25 ; only a maximum of 10% of scattered bokeh
• 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:98

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

TAutoConsoleVariable<float> CVarScatterMaxSpriteRatio(
	TEXT("r.DOF.Scatter.MaxSpriteRatio"),
	0.1f,
	TEXT("Maximum ratio of scattered pixel quad as sprite, usefull to control DOF's scattering upperbound. ")
	TEXT(" 1 will allow to scatter 100% pixel quads, whereas 0.2 will only allow 20% (default = 0.1)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarEnableRecombineBokehSettings(

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<float> CVarScatterMaxSpriteRatio(
	TEXT("r.DOF.Scatter.MaxSpriteRatio"),
	0.1f,
	TEXT("Maximum ratio of scattered pixel quad as sprite, usefull to control DOF's scattering upperbound. ")
	TEXT(" 1 will allow to scatter 100% pixel quads, whereas 0.2 will only allow 20% (default = 0.1)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     bool DiaphragmDOF::AddPasses

Source code excerpt:

	// Setting for scattering budget upper bound.
	const float MaxScatteringRatio = FMath::Clamp(CVarScatterMaxSpriteRatio.GetValueOnRenderThread(), 0.0f, 1.0f);

	// Slight out of focus is not supporting with DOF's TAA upsampling, because of the brute force
	// kernel used in GatherCS for slight out of focus stability buffer.
	const bool bSupportsSlightOutOfFocus = true; // View.PrimaryScreenPercentageMethod != EPrimaryScreenPercentageMethod::TemporalUpscale;

	// Quality setting for the recombine pass.