r.AmbientOcclusion.DepthBoundsTest

r.AmbientOcclusion.DepthBoundsTest

#Overview

name: r.AmbientOcclusion.DepthBoundsTest

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

• type: Var
• help: Whether to use depth bounds test to cull distant pixels during AO pass. This option is only valid when pixel shader path is used (r.AmbientOcclusion.Compute=0), without upsampling.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AmbientOcclusion.DepthBoundsTest is to control whether depth bounds testing is used to cull distant pixels during the Ambient Occlusion (AO) pass in the rendering pipeline.

This setting variable is primarily used in the rendering system, specifically in the Ambient Occlusion post-processing pass. It is part of the Unreal Engine’s rendering module, as evidenced by its location in the “Renderer/Private/CompositionLighting” directory.

The value of this variable is set through a console variable (CVar) system, which allows for runtime configuration. It is initialized with a default value of 1 (enabled) in the C++ code.

The associated variable CVarAmbientOcclusionDepthBoundsTest directly interacts with r.AmbientOcclusion.DepthBoundsTest. They share the same value and purpose.

Developers must be aware of several important factors when using this variable:

1. It only applies when using the pixel shader path for Ambient Occlusion (r.AmbientOcclusion.Compute=0).
2. It is not valid when upsampling is used.
3. It requires hardware support for depth bounds testing (GSupportsDepthBoundsTest).
4. It is only effective when ScaleToFullRes is 1 and the scene depth texture has only one sample.

Best practices for using this variable include:

1. Enable it by default (as it is in the code) to potentially improve performance by culling distant pixels.
2. Ensure that the necessary conditions are met for it to be effective (pixel shader path, no upsampling, hardware support).
3. Consider disabling it if visual artifacts occur in distant objects or if performance gains are negligible.

Regarding the associated variable CVarAmbientOcclusionDepthBoundsTest:

• Its purpose is identical to r.AmbientOcclusion.DepthBoundsTest.
• It is used in the same rendering subsystem (Ambient Occlusion).
• Its value is set through the same console variable system.
• It interacts directly with r.AmbientOcclusion.DepthBoundsTest, as they are essentially the same variable.
• The same awareness points and best practices apply to this variable as well.

Developers should treat CVarAmbientOcclusionDepthBoundsTest as the internal representation of the r.AmbientOcclusion.DepthBoundsTest console variable, used within the C++ code to access and modify the setting.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarAmbientOcclusionDepthBoundsTest(
	TEXT("r.AmbientOcclusion.DepthBoundsTest"),
	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 (r.AmbientOcclusion.Compute=0), without upsampling."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAmbientOcclusionMethod(
	TEXT("r.AmbientOcclusion.Method"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAmbientOcclusionDepthBoundsTest(
	TEXT("r.AmbientOcclusion.DepthBoundsTest"),
	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 (r.AmbientOcclusion.Compute=0), without upsampling."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAmbientOcclusionMethod(

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

Scope (from outer to inner):

file
function     void AddAmbientOcclusionPass

Source code excerpt:

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

		FDepthStencilBinding DepthStencilBinding(CommonParameters.SceneDepth.Texture, ERenderTargetLoadAction::ELoad, ERenderTargetLoadAction::ELoad, FExclusiveDepthStencil::DepthRead_StencilWrite);