r.BackbufferQuantizationDitheringOverride

r.BackbufferQuantizationDitheringOverride

#Overview

name: r.BackbufferQuantizationDitheringOverride

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.BackbufferQuantizationDitheringOverride is to override the bit depth of each channel in the backbuffer targeted by quantization dithering in the rendering process. This setting variable is part of the rendering system in Unreal Engine 5, specifically related to post-processing and tonemapping.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the post-processing and tonemapping components. This can be seen from the file location “PostProcessTonemap.cpp” where the variable is defined and used.

The value of this variable is set through a console command, as it’s defined as a TAutoConsoleVariable. By default, it’s set to 0, which means the override is disabled.

This variable interacts with the FSceneViewFamily::RenderTarget’s pixel format of the backbuffer when the override is not active. When the override is active (value > 0), it directly influences the quantization dithering process.

Developers must be aware that this variable is intended for overriding the automatic detection of the backbuffer’s bit depth. It should be used cautiously, as incorrect values could lead to unexpected visual results or performance issues.

Best practices when using this variable include:

  1. Leave it at the default value (0) unless there’s a specific need to override the automatic detection.
  2. If overriding, ensure the value matches the actual bit depth of the backbuffer to avoid visual artifacts.
  3. Use this in conjunction with profiling tools to understand its impact on rendering performance.
  4. Be aware of the display output format, as some formats (like HDR linear) don’t support backbuffer quantization dithering.

Regarding the associated variable CVarBackbufferQuantizationDitheringOverride:

This is the actual console variable object that controls the r.BackbufferQuantizationDitheringOverride setting. It’s used in the same way as r.BackbufferQuantizationDitheringOverride, but it’s the internal representation that the engine uses to access and modify the value.

The purpose of CVarBackbufferQuantizationDitheringOverride is to provide a programmatic way to access and modify the r.BackbufferQuantizationDitheringOverride setting within the C++ code.

It’s used in the AddTonemapPass function to determine whether to apply backbuffer quantization dithering and to what extent. Developers should be aware that modifying this variable directly in code will have the same effect as changing the r.BackbufferQuantizationDitheringOverride console command.

Best practices for using CVarBackbufferQuantizationDitheringOverride include:

  1. Use GetValueOnRenderThread() to safely access its value in render thread code.
  2. Be cautious when modifying its value, as it can affect the entire rendering pipeline.
  3. Consider using it for debugging or specific rendering scenarios where fine control over quantization dithering is necessary.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp:67

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


static TAutoConsoleVariable<int32> CVarBackbufferQuantizationDitheringOverride(
	TEXT("r.BackbufferQuantizationDitheringOverride"), 0,
	TEXT("Override the bitdepth in bits of each channel of the backbuffer targeted by the quantization dithering. ")
	TEXT("Disabled by default. Instead is automatically found out by FSceneViewFamily::RenderTarget's pixel format of the backbuffer."),
	ECVF_RenderThreadSafe);

const int32 GTonemapComputeTileSizeX = 8;
const int32 GTonemapComputeTileSizeY = 8;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp:66

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarBackbufferQuantizationDitheringOverride(
	TEXT("r.BackbufferQuantizationDitheringOverride"), 0,
	TEXT("Override the bitdepth in bits of each channel of the backbuffer targeted by the quantization dithering. ")
	TEXT("Disabled by default. Instead is automatically found out by FSceneViewFamily::RenderTarget's pixel format of the backbuffer."),
	ECVF_RenderThreadSafe);

const int32 GTonemapComputeTileSizeX = 8;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp:826

Scope (from outer to inner):

file
function     FScreenPassTexture AddTonemapPass

Source code excerpt:

	{
		const bool bSupportsBackbufferQuantizationDithering = EDisplayOutputFormat(CommonParameters.OutputDevice.OutputDevice) != EDisplayOutputFormat::HDR_LinearNoToneCurve && EDisplayOutputFormat(CommonParameters.OutputDevice.OutputDevice) != EDisplayOutputFormat::HDR_LinearWithToneCurve;
		const int32 BitdepthOverride = CVarBackbufferQuantizationDitheringOverride.GetValueOnRenderThread();

		if (!bSupportsBackbufferQuantizationDithering)
		{
			CommonParameters.BackbufferQuantizationDithering = 0.0f;
		}
		else if (BitdepthOverride > 0)