r.Mobile.AmbientOcclusionTechnique

r.Mobile.AmbientOcclusionTechnique

#Overview

name: r.Mobile.AmbientOcclusionTechnique

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Mobile.AmbientOcclusionTechnique is to control the ambient occlusion technique used in mobile rendering within Unreal Engine 5. This setting variable is specifically for the mobile rendering system, focusing on the ambient occlusion aspect of the rendering pipeline.

The Unreal Engine subsystem that relies on this setting variable is the mobile rendering system, particularly the ambient occlusion pass. This can be seen in the references within the MobileShadingRenderer.cpp and PostProcessAmbientOcclusionMobile.cpp files.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with two possible values: 0 for GTAO (Ground Truth Ambient Occlusion) and 1 for SSAO (Screen Space Ambient Occlusion).

This variable interacts with other parts of the rendering system, particularly:

  1. It affects whether the HZB (Hi-Z Buffer) should be rendered in the ShouldRenderHZB function.
  2. It determines the downsampling factor and technique used in the CreateMobileScreenSpaceAOTexture function.
  3. It controls which ambient occlusion rendering technique is used in the RenderAmbientOcclusion function.

Developers must be aware that changing this variable will affect the visual quality and performance of ambient occlusion on mobile devices. GTAO (the default) and SSAO have different quality and performance characteristics.

Best practices when using this variable include:

  1. Testing both techniques (GTAO and SSAO) to determine which provides the best balance of visual quality and performance for your specific mobile game.
  2. Consider the target mobile hardware when choosing the technique, as more powerful devices might handle GTAO better.
  3. Be aware that changing this setting might require adjustments to other rendering settings for optimal results.

Regarding the associated variable CVarMobileAmbientOcclusionTechnique:

The purpose of CVarMobileAmbientOcclusionTechnique is to provide a console-accessible way to modify the r.Mobile.AmbientOcclusionTechnique setting. It’s the actual console variable that stores and provides the value for the ambient occlusion technique.

This variable is used directly in the rendering code to determine which ambient occlusion technique to use. It’s accessed using GetValueOnRenderThread() in various parts of the mobile rendering pipeline.

The value of this variable is set when the console command “r.Mobile.AmbientOcclusionTechnique” is used, allowing runtime modification of the ambient occlusion technique.

Developers should be aware that changes to this variable will take effect on the render thread, which means the change might not be instantaneous but will occur on the next frame or render pass.

Best practices for using this variable include:

  1. Use it for debugging and testing different ambient occlusion techniques during development.
  2. Consider exposing it as a user-configurable setting in graphics options for power users, allowing them to optimize for their specific device.
  3. Monitor performance when changing this value, as it can have a significant impact on rendering speed, especially on lower-end mobile devices.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessAmbientOcclusionMobile.cpp:30

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMobileAmbientOcclusionTechnique(
	TEXT("r.Mobile.AmbientOcclusionTechnique"),
	0,
	TEXT("0: GTAO (default).\n")
	TEXT("1: SSAO.\n"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MobileShadingRenderer.cpp:2272

Scope (from outer to inner):

file
function     bool FMobileSceneRenderer::ShouldRenderHZB

Source code excerpt:

bool FMobileSceneRenderer::ShouldRenderHZB()
{
	static const auto MobileAmbientOcclusionTechniqueCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Mobile.AmbientOcclusionTechnique"));

	// Mobile SSAO requests HZB
	bool bIsFeatureRequested = bRequiresAmbientOcclusionPass && MobileAmbientOcclusionTechniqueCVar->GetValueOnRenderThread() == 1;

	// Instance occlusion culling requires HZB
	if (FInstanceCullingContext::IsOcclusionCullingEnabled())

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessAmbientOcclusionMobile.cpp:29

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarMobileAmbientOcclusionTechnique(
	TEXT("r.Mobile.AmbientOcclusionTechnique"),
	0,
	TEXT("0: GTAO (default).\n")
	TEXT("1: SSAO.\n"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessAmbientOcclusionMobile.cpp:438

Scope (from outer to inner):

file
function     FRDGTextureRef CreateMobileScreenSpaceAOTexture

Source code excerpt:

FRDGTextureRef CreateMobileScreenSpaceAOTexture(FRDGBuilder& GraphBuilder, const FSceneTexturesConfig& Config)
{
	bool bGTAO = (CVarMobileAmbientOcclusionTechnique.GetValueOnRenderThread() == 0);
	const uint32 DownsampleFactor = bGTAO ? 2 : 1;

	const FIntPoint Extent = FIntPoint::DivideAndRoundUp(Config.Extent, DownsampleFactor);

	EPixelFormat Format = PF_G8;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessAmbientOcclusionMobile.cpp:1152

Scope (from outer to inner):

file
function     void FMobileSceneRenderer::RenderAmbientOcclusion

Source code excerpt:

void FMobileSceneRenderer::RenderAmbientOcclusion(FRDGBuilder& GraphBuilder, FRDGTextureRef SceneDepthTexture, FRDGTextureRef AmbientOcclusionTexture)
{
	const int32 Technique = CVarMobileAmbientOcclusionTechnique.GetValueOnRenderThread();
	switch (Technique)
	{
	case 0:
		RenderGTAO(GraphBuilder, SceneDepthTexture, AmbientOcclusionTexture, Views);
		break;
	case 1: