r.GBufferFormat

r.GBufferFormat

#Overview

name: r.GBufferFormat

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

It is referenced in 10 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GBufferFormat is to define the memory layout used for the GBuffer in Unreal Engine’s rendering system. It affects performance, mainly through bandwidth, and the quality of normals and material attributes.

This setting variable is primarily used by the Renderer module of Unreal Engine, as evident from its definition in SceneTextures.cpp. It’s also utilized by the PixelInspector, ShaderCompiler, and RenderCore subsystems.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It’s defined with a default value of 1, which represents low precision.

The r.GBufferFormat variable interacts closely with its associated variable CVarGBufferFormat. They share the same value and are used interchangeably in different parts of the codebase.

Developers must be aware that changing this variable affects the precision of the GBuffer:

Best practices when using this variable include:

  1. Use the default value (1) for most scenarios, as it balances performance and quality.
  2. Consider using 0 for performance profiling or on lower-end hardware.
  3. Use 3 if high-quality normal maps are crucial for your project and you can afford the performance cost.

Regarding the associated variable CVarGBufferFormat:

The purpose of CVarGBufferFormat is to provide a programmatic way to access and modify the r.GBufferFormat setting. It’s used in various parts of the engine to retrieve the current GBuffer format setting.

This variable is primarily used in the Renderer, PixelInspector, and ShaderCompiler modules.

The value of CVarGBufferFormat is set when the r.GBufferFormat console variable is initialized or changed.

Developers should be aware that CVarGBufferFormat is often used to retrieve the current GBuffer format in different parts of the engine, so changes to r.GBufferFormat will be reflected through this variable.

Best practices for using CVarGBufferFormat include:

  1. Use it to read the current GBuffer format setting in your code.
  2. Don’t modify it directly; instead, change the r.GBufferFormat console variable.
  3. Be aware that its value can change at runtime, so always fetch it when needed rather than caching it.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneTextures.cpp:55

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarGBufferFormat(
	TEXT("r.GBufferFormat"),
	1,
	TEXT("Defines the memory layout used for the GBuffer.\n")
	TEXT("(affects performance, mostly through bandwidth, quality of normals and material attributes).\n")
	TEXT(" 0: lower precision (8bit per component, for profiling)\n")
	TEXT(" 1: low precision (default)\n")
	TEXT(" 3: high precision normals encoding\n")

#Loc: <Workspace>/Engine/Source/Editor/PixelInspector/Private/PixelInspector.cpp:480

Scope (from outer to inner):

file
namespace    PixelInspector
function     void SPixelInspector::CreatePixelInspectorRequest

Source code excerpt:

		TickSinceLastCreateRequest = 0;
		// We need to know if the GBuffer is in low, default or high precision buffer
		const auto CVarGBufferFormat = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GBufferFormat"));
		//0: lower precision (8bit per component, for profiling)
		//1: low precision (default)
		//5: high precision
		const int32 GBufferFormat = CVarGBufferFormat != nullptr ? CVarGBufferFormat->GetValueOnGameThread() : 1;

		const bool AllowStaticLighting = IsStaticLightingAllowed();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderGenerationUtil.cpp:442

Scope (from outer to inner):

file
function     static FShaderGlobalDefines FetchShaderGlobalDefines

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GBufferFormat"));
		Ret.LegacyGBufferFormat = CVar->GetInt();
	}

	return Ret;
}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderGenerationUtil.cpp:2246

Scope (from outer to inner):

file
function     FGBufferParams FShaderCompileUtilities::FetchGBufferParamsPipeline

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GBufferFormat"));
		Ret.LegacyFormatIndex = CVar->GetInt();
	}
#else
	// this function should never be called in a non-editor build
	check(0);
#endif

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderGenerationUtil.cpp:2274

Scope (from outer to inner):

file
function     FGBufferParams FShaderCompileUtilities::FetchGBufferParamsRuntime

Source code excerpt:

	Ret.bUsesVelocityDepth = NeedsVelocityDepth(Platform);

	static const auto CVarFormat = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GBufferFormat"));
	Ret.LegacyFormatIndex = CVarFormat->GetValueOnAnyThread();

	// This should match with SINGLE_LAYER_WATER_SEPARATED_MAIN_LIGHT
	Ret.bHasSingleLayerWaterSeparatedMainLight = IsWaterDistanceFieldShadowEnabled(Platform) || IsWaterVirtualShadowMapFilteringEnabled(Platform);

	return Ret;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1876

Scope (from outer to inner):

file
namespace    Substrate
function     uint32 GetNormalQuality

Source code excerpt:

	uint32 GetNormalQuality()
	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GBufferFormat"));
		return CVar && CVar->GetValueOnAnyThread() > 1 ? 1 : 0;
	}

	uint32 GetRayTracingMaterialPayloadSizeInBytes(bool bFullySimplifiedMaterial)
	{
		// The payload size represents FPackedMaterialClosestHitPayload containing FSubstrateRaytracingPayload composed of

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/PixelInspector/Private/PixelInspector.cpp:480

Scope (from outer to inner):

file
namespace    PixelInspector
function     void SPixelInspector::CreatePixelInspectorRequest

Source code excerpt:

		TickSinceLastCreateRequest = 0;
		// We need to know if the GBuffer is in low, default or high precision buffer
		const auto CVarGBufferFormat = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GBufferFormat"));
		//0: lower precision (8bit per component, for profiling)
		//1: low precision (default)
		//5: high precision
		const int32 GBufferFormat = CVarGBufferFormat != nullptr ? CVarGBufferFormat->GetValueOnGameThread() : 1;

		const bool AllowStaticLighting = IsStaticLightingAllowed();
		
		//Try to create the request buffer
		int32 BufferIndex = CreateRequestBuffer(SceneInterface, GBufferFormat, bInGameViewMode);
		if (BufferIndex == -1)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/EngineTypes.h:562

Scope: file

Source code excerpt:

/** 
 * Enumerates available GBufferFormats. 
 * @warning When this enum is updated please update CVarGBufferFormat comments 
 */
UENUM()
namespace EGBufferFormat
{
	enum Type : int
	{
		/** Forces all GBuffers to 8 bits per channel. Intended as profiling for best performance. (Substrate: Octahedral encoding as 2x11bits for simple and single materials, 2x16bits for complex materials) */
		Force8BitsPerChannel = 0 UMETA(DisplayName = "Force 8 Bits Per Channel"),
		/** See GBuffer allocation function for layout details. (Substrate: Octahedral encoding as 2x11bits for simple and single material, 2x16bits for complex materials) */

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneTextures.cpp:54

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<int32> CVarGBufferFormat(
	TEXT("r.GBufferFormat"),
	1,
	TEXT("Defines the memory layout used for the GBuffer.\n")
	TEXT("(affects performance, mostly through bandwidth, quality of normals and material attributes).\n")
	TEXT(" 0: lower precision (8bit per component, for profiling)\n")
	TEXT(" 1: low precision (default)\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneTextures.cpp:80

Scope (from outer to inner):

file
function     EPixelFormat FSceneTextures::GetGBufferFFormatAndCreateFlags

Source code excerpt:

EPixelFormat FSceneTextures::GetGBufferFFormatAndCreateFlags(ETextureCreateFlags& OutCreateFlags)
{
	const int32 GBufferFormat = CVarGBufferFormat.GetValueOnAnyThread();
	const bool bHighPrecisionGBuffers = (GBufferFormat >= EGBufferFormat::Force16BitsPerChannel);
	const bool bEnforce8BitPerChannel = (GBufferFormat == EGBufferFormat::Force8BitsPerChannel);
	EPixelFormat NormalGBufferFormat = bHighPrecisionGBuffers ? PF_FloatRGBA : PF_B8G8R8A8;

	if (bEnforce8BitPerChannel)
	{