r.AmbientOcclusionLevels

r.AmbientOcclusionLevels

#Overview

name: r.AmbientOcclusionLevels

The value of this variable can be defined or overridden in .ini config files. 5 .ini config files referencing this setting variable.

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

• type: Var
• help: Defines how many mip levels are using during the ambient occlusion calculation. This is useful when tweaking the algorithm.\n<0: decide based on the quality setting in the postprocess settings/volume and r.AmbientOcclusionMaxQuality (default)\n 0: none (disable AmbientOcclusion)\n 1: one\n 2: two (costs extra performance, soft addition)\n 3: three (larger radius cost less but can flicker)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AmbientOcclusionLevels is to control the number of mip levels used during ambient occlusion calculation in Unreal Engine’s rendering system. This setting affects the quality and performance of the ambient occlusion effect.

This setting variable is primarily used in the Renderer module, specifically in the composition lighting subsystem for post-processing ambient occlusion.

The value of this variable is set through the console variable system in Unreal Engine. It can be adjusted at runtime using console commands or through configuration files.

The associated variable CVarAmbientOcclusionLevels interacts directly with r.AmbientOcclusionLevels, as they share the same value. This variable is used in the C++ code to retrieve the current setting value.

Developers must be aware of the following when using this variable:

1. The default value is -1, which means the number of levels is determined based on the quality setting in post-process settings/volume and r.AmbientOcclusionMaxQuality.
2. Setting it to 0 disables ambient occlusion entirely.
3. Values 1 and 2 correspond to using one or two mip levels, respectively.
4. Using two levels (value 2) costs extra performance but provides a softer addition to the ambient occlusion effect.

Best practices when using this variable include:

1. Leave it at -1 (default) for automatic quality adjustment based on other settings.
2. Use 0 to disable ambient occlusion for performance-critical scenarios.
3. Use 1 for a balance between quality and performance.
4. Use 2 only when higher quality ambient occlusion is required and the performance cost is acceptable.

Regarding the associated variable CVarAmbientOcclusionLevels:

• It is a TAutoConsoleVariable that directly corresponds to r.AmbientOcclusionLevels.
• It is used in the GetNumAmbientOcclusionLevels() function of the FSSAOHelper class to retrieve the current setting value on the render thread.
• Developers should use this variable when they need to access the ambient occlusion levels setting in C++ code, particularly within the rendering subsystem.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:393, section: [PostProcessQuality@0]

• INI Section: PostProcessQuality@0
• Raw value: 0
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:413, section: [PostProcessQuality@1]

• INI Section: PostProcessQuality@1
• Raw value: -1
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:446, section: [PostProcessQuality@2]

• INI Section: PostProcessQuality@2
• Raw value: -1
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:481, section: [PostProcessQuality@3]

• INI Section: PostProcessQuality@3
• Raw value: -1
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:518, section: [PostProcessQuality@Cine]

• INI Section: PostProcessQuality@Cine
• Raw value: -1
• Is Array: False

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarAmbientOcclusionLevels(
	TEXT("r.AmbientOcclusionLevels"),
	-1,
	TEXT("Defines how many mip levels are using during the ambient occlusion calculation. This is useful when tweaking the algorithm.\n")
	TEXT("<0: decide based on the quality setting in the postprocess settings/volume and r.AmbientOcclusionMaxQuality (default)\n")
	TEXT(" 0: none (disable AmbientOcclusion)\n")
	TEXT(" 1: one\n")
	TEXT(" 2: two (costs extra performance, soft addition)\n")

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAmbientOcclusionLevels(
	TEXT("r.AmbientOcclusionLevels"),
	-1,
	TEXT("Defines how many mip levels are using during the ambient occlusion calculation. This is useful when tweaking the algorithm.\n")
	TEXT("<0: decide based on the quality setting in the postprocess settings/volume and r.AmbientOcclusionMaxQuality (default)\n")
	TEXT(" 0: none (disable AmbientOcclusion)\n")
	TEXT(" 1: one\n")

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

Scope (from outer to inner):

file
function     int32 FSSAOHelper::GetNumAmbientOcclusionLevels

Source code excerpt:

int32 FSSAOHelper::GetNumAmbientOcclusionLevels()
{
	return CVarAmbientOcclusionLevels.GetValueOnRenderThread();
}

float FSSAOHelper::GetAmbientOcclusionStepMipLevelFactor()
{
	return CVarAmbientOcclusionStepMipLevelFactor.GetValueOnRenderThread();
}