r.Mobile.AmbientOcclusionDepthBoundsTest

r.Mobile.AmbientOcclusionDepthBoundsTest

#Overview

name: r.Mobile.AmbientOcclusionDepthBoundsTest

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Mobile.AmbientOcclusionDepthBoundsTest is to control whether depth bounds testing is used to cull distant pixels during the ambient occlusion pass in mobile rendering.

This setting variable is primarily used in the rendering system, specifically for mobile ambient occlusion processing. It is part of Unreal Engine’s mobile rendering pipeline.

The variable is referenced in the PostProcessAmbientOcclusionMobile.cpp file, which is part of the Renderer module. This suggests that the mobile ambient occlusion subsystem relies on this setting variable.

The value of this variable is set through a console variable (CVarMobileAmbientOcclusionDepthBoundsTest) with a default value of 1 (enabled). It can be changed at runtime through console commands or programmatically.

This variable interacts with other conditions such as half-resolution rendering (bHalfResolution), hardware support for depth bounds testing (GSupportsDepthBoundsTest), and the validity and properties of the scene depth texture.

Developers should be aware that:

  1. This setting is only valid when the pixel shader path is used for ambient occlusion.
  2. It requires hardware support for depth bounds testing.
  3. It’s not applicable when using half-resolution ambient occlusion.
  4. The scene depth texture must be valid and have only one sample.

Best practices when using this variable include:

  1. Ensure it’s only enabled on devices that support depth bounds testing.
  2. Consider the performance impact and visual quality trade-offs when enabling or disabling this feature.
  3. Test thoroughly on target mobile devices to ensure it provides the desired performance benefit without compromising visual quality.

Regarding the associated variable CVarMobileAmbientOcclusionDepthBoundsTest:

This is the actual console variable that controls the r.Mobile.AmbientOcclusionDepthBoundsTest setting. It’s defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime.

The purpose of this variable is the same as r.Mobile.AmbientOcclusionDepthBoundsTest - to enable or disable depth bounds testing for mobile ambient occlusion.

It’s used in the AddMobileAmbientOcclusionPass and AddMobileAmbientOcclusionUpsamplePass functions to determine whether depth bounds testing should be enabled for these passes.

Developers should be aware that:

  1. The value is accessed using GetValueOnRenderThread(), ensuring thread-safe access.
  2. It’s combined with other conditions to determine if depth bounds testing should be used.

Best practices for using this variable include:

  1. Use the console variable for debugging and testing, but consider exposing it as a user-configurable setting for release builds if appropriate.
  2. When changing the value programmatically, ensure it’s done in a thread-safe manner, preferably on the render thread.

#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:66

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMobileAmbientOcclusionDepthBoundsTest(
	TEXT("r.Mobile.AmbientOcclusionDepthBoundsTest"),
	1,
	TEXT("Whether to use depth bounds test to cull distant pixels during AO pass. This option is only valid when pixel shader path is used"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarMobileSSAOHalfResolution(
	TEXT("r.Mobile.SSAOHalfResolution"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarMobileAmbientOcclusionDepthBoundsTest(
	TEXT("r.Mobile.AmbientOcclusionDepthBoundsTest"),
	1,
	TEXT("Whether to use depth bounds test to cull distant pixels during AO pass. This option is only valid when pixel shader path is used"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarMobileSSAOHalfResolution(

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

Scope (from outer to inner):

file
function     static void AddMobileAmbientOcclusionPass

Source code excerpt:

	
	const bool bDepthBoundsTestEnabled =
		CVarMobileAmbientOcclusionDepthBoundsTest.GetValueOnRenderThread()
		&& !bHalfResolution
		&& GSupportsDepthBoundsTest
		&& CommonParameters.SceneDepth.IsValid()
		&& CommonParameters.SceneDepth.Texture->Desc.NumSamples == 1;

	float DepthFar = 0.0f;

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

Scope (from outer to inner):

file
function     static void AddMobileAmbientOcclusionUpsamplePass

Source code excerpt:

{
	const bool bDepthBoundsTestEnabled =
		CVarMobileAmbientOcclusionDepthBoundsTest.GetValueOnRenderThread()
		&& GSupportsDepthBoundsTest
		&& CommonParameters.SceneDepth.IsValid()
		&& CommonParameters.SceneDepth.Texture->Desc.NumSamples == 1;

	const FScreenPassTextureViewport OutputViewport = CommonParameters.SceneTexturesViewport;