r.GTAO.Downsample

r.GTAO.Downsample

#Overview

name: r.GTAO.Downsample

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.GTAO.Downsample is to control whether Ground Truth Ambient Occlusion (GTAO) is performed at half resolution. This setting variable is part of the rendering system in Unreal Engine 5, specifically related to the ambient occlusion technique.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its location in the CompositionLighting.cpp file within the Runtime/Renderer/Private/CompositionLighting directory.

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

This variable interacts with the CVarGTAODownsample variable, which is directly associated with it. They share the same value and purpose.

Developers must be aware that enabling this option (setting it to 1) will perform GTAO at half resolution, which can improve performance at the cost of some quality loss. When disabled (set to 0), GTAO will be performed at full resolution.

Best practices when using this variable include:

  1. Consider enabling it (set to 1) for performance-sensitive scenarios or on lower-end hardware.
  2. Keep it disabled (set to 0) for highest quality renders or when targeting high-end systems.
  3. Test the visual impact and performance gain in your specific scene before deciding on a setting.

Regarding the associated variable CVarGTAODownsample:

The purpose of CVarGTAODownsample is to provide a programmable interface for the r.GTAO.Downsample setting. It’s an instance of TAutoConsoleVariable, which allows for runtime modification of the setting.

This variable is used within the Renderer module to determine the downscale factor for GTAO calculations. As seen in the GetGTAOCommonParameters function, the value of CVarGTAODownsample directly influences the DownscaleFactor used in GTAO rendering.

The value of CVarGTAODownsample is set when the console variable is initialized, but can be changed at runtime using console commands.

Developers should be aware that changes to CVarGTAODownsample will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag used in its declaration.

Best practices for using CVarGTAODownsample include:

  1. Use it for dynamic quality adjustments based on performance metrics.
  2. Consider exposing it as a user-configurable setting in graphics options menus.
  3. Be cautious when changing its value frequently, as it may impact frame-to-frame consistency in visual quality.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarGTAODownsample(
	TEXT("r.GTAO.Downsample"),
	0,
	TEXT("Perform GTAO at Halfres \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 CVarGTAODownsample. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarGTAODownsample(
	TEXT("r.GTAO.Downsample"),
	0,
	TEXT("Perform GTAO at Halfres \n ")
	TEXT("0: Off \n ")
	TEXT("1: On (default)\n "),
	ECVF_RenderThreadSafe | ECVF_Scalability);

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

Scope (from outer to inner):

file
function     FGTAOCommonParameters GetGTAOCommonParameters

Source code excerpt:


	CommonParameters.ShaderQuality = FSSAOHelper::GetAmbientOcclusionShaderLevel(View);
	CommonParameters.DownscaleFactor = CVarGTAODownsample.GetValueOnRenderThread() > 0 ? 2 : 1;
	CommonParameters.GTAOType = GTAOType;

	CommonParameters.DownsampledViewRect = GetDownscaledRect(View.ViewRect, CommonParameters.DownscaleFactor);

	return CommonParameters;
}