r.AmbientOcclusion.Compute

r.AmbientOcclusion.Compute

#Overview

name: r.AmbientOcclusion.Compute

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.AmbientOcclusion.Compute is to control whether Screen Space Ambient Occlusion (SSAO) should use Compute Shaders or Pixel Shaders for its calculations. This setting is part of the rendering system in Unreal Engine 5.

The Unreal Engine subsystem that primarily relies on this setting variable is the Renderer module, specifically the ambient occlusion component of the composition lighting system.

The value of this variable is set through the console variable system, allowing it to be changed at runtime. It’s defined with a default value of 0, which means Pixel Shaders are used by default.

This variable interacts closely with its associated variable CVarAmbientOcclusionCompute, which is the actual TAutoConsoleVariable instance used to store and manage the setting.

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

  1. Compute Shader support is not available on all platforms, particularly mobile, DX10, and OpenGL3.
  2. The Compute Shader version is described as work-in-progress (WIP) and not optimized.
  3. The Compute Shader version does not use normals, allowing it to run right after EarlyZPass, which can improve performance when used with Async Compute.
  4. Async Compute functionality is currently limited to PS4 (as of the time this code was written).
  5. Using Compute Shaders for SSAO affects which static draw lists meshes go into, potentially requiring a full scene rebuild if changed at runtime.

Best practices when using this variable include:

  1. Consider platform compatibility before enabling Compute Shaders for SSAO.
  2. Be cautious when enabling this on performance-critical scenes, as the Compute Shader version is not fully optimized.
  3. If changing this setting at runtime, be prepared to handle potential scene rebuilds.
  4. When using Async Compute (value 2 or higher), ensure your target platforms support this feature.

Regarding the associated variable CVarAmbientOcclusionCompute:

This is the actual console variable instance that stores the r.AmbientOcclusion.Compute setting. It’s used throughout the codebase to query the current setting value. The variable is used in functions like IsAmbientOcclusionCompute and IsAmbientOcclusionAsyncCompute to determine the SSAO computation method. When working with SSAO in custom render passes or when optimizing rendering performance, developers should use this variable to check the current SSAO computation method and adjust their code accordingly.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarAmbientOcclusionCompute(
	TEXT("r.AmbientOcclusion.Compute"),
	0,
	TEXT("If SSAO should use ComputeShader (not available on all platforms) or PixelShader.\n")
	TEXT("The [Async] Compute Shader version is WIP, not optimized, requires hardware support (not mobile/DX10/OpenGL3),\n")
	TEXT("does not use normals which allows it to run right after EarlyZPass (better performance when used with AyncCompute)\n")
	TEXT("AyncCompute is currently only functional on PS4.\n")
	TEXT(" 0: PixelShader (default)\n")

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:633

Scope (from outer to inner):

file
function     bool ShouldForceFullDepthPass

Source code excerpt:

		const bool bStencilLODDither = StencilLODDitherCVar->GetValueOnAnyThread() != 0;

		static const auto AOComputeCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.AmbientOcclusion.Compute"));
		const bool bAOCompute = AOComputeCVar->GetValueOnAnyThread() > 0;

		const bool bEarlyZMaterialMasking = MaskedInEarlyPass(Platform);

		// Note: ShouldForceFullDepthPass affects which static draw lists meshes go into, so nothing it depends on can change at runtime, unless you do a FGlobalComponentRecreateRenderStateContext to propagate the cvar change
		return bNaniteEnabled || bAOCompute || bDBufferAllowed || bVirtualTextureEnabled || bStencilLODDither || bEarlyZMaterialMasking || IsForwardShadingEnabled(Platform) || IsUsingSelectiveBasePassOutputs(Platform);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DECLARE_GPU_STAT_NAMED(GTAO_Upsample,					TEXT("GTAO Upsample"));

static TAutoConsoleVariable<int32> CVarAmbientOcclusionCompute(
	TEXT("r.AmbientOcclusion.Compute"),
	0,
	TEXT("If SSAO should use ComputeShader (not available on all platforms) or PixelShader.\n")
	TEXT("The [Async] Compute Shader version is WIP, not optimized, requires hardware support (not mobile/DX10/OpenGL3),\n")
	TEXT("does not use normals which allows it to run right after EarlyZPass (better performance when used with AyncCompute)\n")
	TEXT("AyncCompute is currently only functional on PS4.\n")

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

Scope (from outer to inner):

file
function     bool FSSAOHelper::IsAmbientOcclusionCompute

Source code excerpt:

bool FSSAOHelper::IsAmbientOcclusionCompute(const FSceneView& View)
{
	return View.GetFeatureLevel() >= ERHIFeatureLevel::SM5 && CVarAmbientOcclusionCompute.GetValueOnRenderThread() >= 1;
}

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

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

Scope (from outer to inner):

file
function     bool FSSAOHelper::IsAmbientOcclusionAsyncCompute

Source code excerpt:

	if(IsAmbientOcclusionCompute(View) && (AOPassCount == 1))
	{
		int32 ComputeCVar = CVarAmbientOcclusionCompute.GetValueOnRenderThread();

		if(ComputeCVar >= 2)
		{
			// we might want AsyncCompute

			if(ComputeCVar == 3)