r.GTAO.UseNormals

r.GTAO.UseNormals

#Overview

name: r.GTAO.UseNormals

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

• type: Var
• help: Whether to use GBuffer Normals or Depth Derived normals \n 0: Off \n 1: On (default)\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GTAO.UseNormals is to control whether the Ground Truth Ambient Occlusion (GTAO) system uses GBuffer Normals or Depth Derived normals in the rendering process. This setting variable is part of the rendering system, specifically the ambient occlusion component.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the Ambient Occlusion post-processing component. This can be seen from the file location where the variable is defined and used: “Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbientOcclusion.cpp”.

The value of this variable is set through a console variable (CVarGTAOUseNormals) with a default value of 0 (Off). It can be changed at runtime using console commands or through code.

The associated variable CVarGTAOUseNormals interacts directly with r.GTAO.UseNormals. They share the same value and purpose.

Developers must be aware that:

1. This variable affects the quality and performance of ambient occlusion rendering.
2. Using GBuffer Normals (when set to 1) may provide more accurate results but could be more performance-intensive.
3. The setting is render thread safe and scalable, meaning it can be adjusted based on performance requirements.

Best practices when using this variable include:

1. Testing both settings (0 and 1) to find the best balance between visual quality and performance for your specific project.
2. Consider using the depth-derived normals (setting 0) for performance-critical scenarios or on lower-end hardware.
3. Use the GBuffer Normals (setting 1) when higher quality ambient occlusion is required and performance allows.

Regarding the associated variable CVarGTAOUseNormals:

• It is an integer console variable that directly controls the r.GTAO.UseNormals setting.
• It is used in the GetGTAOPassType and AddGTAOHorizonSearchIntegratePass functions to determine the GTAO pass type and whether to use normals in the horizon search and integrate pass.
• Developers can access its value using CVarGTAOUseNormals.GetValueOnRenderThread() in C++ code.
• When modifying this variable, consider the impact on both visual quality and performance, and test thoroughly in various scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbientOcclusion.cpp:96

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarGTAOUseNormals(
	TEXT("r.GTAO.UseNormals"),
	0,
	TEXT("Whether to use GBuffer Normals or Depth Derived normals \n ")
	TEXT("0: Off \n ")
	TEXT("1: On (default)\n "),
	ECVF_RenderThreadSafe | ECVF_Scalability);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbientOcclusion.cpp:95

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarGTAOUseNormals(
	TEXT("r.GTAO.UseNormals"),
	0,
	TEXT("Whether to use GBuffer Normals or Depth Derived normals \n ")
	TEXT("0: Off \n ")
	TEXT("1: On (default)\n "),
	ECVF_RenderThreadSafe | ECVF_Scalability);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbientOcclusion.cpp:285

Scope (from outer to inner):

file
function     EGTAOType FSSAOHelper::GetGTAOPassType

Source code excerpt:

{
	int32 Method		= CVarAmbientOcclusionMethod.GetValueOnRenderThread();
	int32 UseNormals	= CVarGTAOUseNormals.GetValueOnRenderThread();

	if (Method == 1)
	{
		if (IsAmbientOcclusionAsyncCompute(View, Levels))
		{
			if (UseNormals)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessAmbientOcclusion.cpp:1139

Scope (from outer to inner):

file
function     FGTAOHorizonSearchOutputs AddGTAOHorizonSearchIntegratePass

Source code excerpt:

	}

	const bool bUseNormals = CVarGTAOUseNormals.GetValueOnRenderThread() >= 1;

	FGTAOHorizonSearchAndIntegrateCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FGTAOHorizonSearchAndIntegrateCS::FParameters>();
	PassParameters->View = View.ViewUniformBuffer;
	PassParameters->SceneTextures = CommonParameters.SceneTexturesUniformBuffer;
	PassParameters->HZBParameters = GetHZBParameters(View, HZBInput, SceneViewport.Extent, EAOTechnique::GTAO);
	PassParameters->Substrate = Substrate::BindSubstrateGlobalUniformParameters(View);