r.BlackBorders

r.BlackBorders

#Overview

name: r.BlackBorders

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.BlackBorders is to control the drawing of black borders around the rendered image in Unreal Engine. This setting is primarily used for the rendering system, specifically to prevent artifacts from post-processing passes that read outside of the image, such as PostProcessAA (Anti-Aliasing).

This setting variable is primarily used in the Engine module, specifically within the GameViewportClient system. It’s defined and used in the GameViewportClient.cpp file, which is part of the core rendering pipeline in Unreal Engine.

The value of this variable is set through a console variable (CVar) named CVarSetBlackBordersEnabled. It’s initialized with a default value of 0, meaning the feature is off by default. Users can change this value at runtime through the console or configuration files.

The associated variable CVarSetBlackBordersEnabled directly interacts with r.BlackBorders. They share the same value and purpose.

Developers must be aware that this variable affects the rendering output by potentially reducing the visible area of the rendered image. The value represents the number of pixels for the border width, and it’s clamped between 0 and 10 pixels.

Best practices when using this variable include:

  1. Use it judiciously, as it reduces the effective rendering area.
  2. Be aware that it may impact performance slightly due to the additional drawing operations.
  3. Consider it as a debugging tool or a last resort for fixing edge artifacts in post-processing.
  4. Test thoroughly with different values to find the optimal balance between artifact prevention and image size reduction.

Regarding the associated variable CVarSetBlackBordersEnabled:

The purpose of CVarSetBlackBordersEnabled is to provide a runtime-configurable way to control the r.BlackBorders setting. It’s an auto console variable that allows developers and users to modify the black border setting without recompiling the engine.

This variable is part of the Engine module and is used within the GameViewportClient system. It’s defined in the same file as r.BlackBorders (GameViewportClient.cpp) and is used to retrieve the current black border setting value.

The value of CVarSetBlackBordersEnabled is set when it’s declared, with a default value of 0. It can be changed at runtime through console commands or configuration files.

CVarSetBlackBordersEnabled directly controls the r.BlackBorders setting. When the game needs to know the current black border setting, it calls GetValueOnGameThread() on this variable.

Developers should be aware that changes to this variable will immediately affect the rendering output. They should also note that the value is clamped between 0 and 10 when used, even if a larger value is set.

Best practices for using CVarSetBlackBordersEnabled include:

  1. Use it for debugging or fine-tuning purposes.
  2. Remember that it’s a global setting that affects all viewports.
  3. Consider exposing it in debug menus for easier testing.
  4. Be cautious when changing it during gameplay, as it may affect the player’s view unexpectedly.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:92

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSetBlackBordersEnabled(
	TEXT("r.BlackBorders"),
	0,
	TEXT("To draw black borders around the rendered image\n")
	TEXT("(prevents artifacts from post processing passes that read outside of the image e.g. PostProcessAA)\n")
	TEXT("in pixels, 0:off"),
	ECVF_Default);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:91

Scope: file

Source code excerpt:

DECLARE_CYCLE_STAT(TEXT("UI Drawing Time"),STAT_UIDrawingTime,STATGROUP_UI);

static TAutoConsoleVariable<int32> CVarSetBlackBordersEnabled(
	TEXT("r.BlackBorders"),
	0,
	TEXT("To draw black borders around the rendered image\n")
	TEXT("(prevents artifacts from post processing passes that read outside of the image e.g. PostProcessAA)\n")
	TEXT("in pixels, 0:off"),
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:1772

Scope (from outer to inner):

file
function     void UGameViewportClient::Draw

Source code excerpt:

		// To draw black borders around the rendered image (prevents artifacts from post processing passes that read outside of the image e.g. PostProcessAA)
		{
			int32 BlackBorders = FMath::Clamp(CVarSetBlackBordersEnabled.GetValueOnGameThread(), 0, 10);

			if(ViewFamily.Views.Num() == 1 && BlackBorders)
			{
				MinX += BlackBorders;
				MinY += BlackBorders;
				MaxX -= BlackBorders;