r.AOSpecularOcclusionMode

r.AOSpecularOcclusionMode

#Overview

name: r.AOSpecularOcclusionMode

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AOSpecularOcclusionMode is to control how specular reflections are occluded by Distance Field Ambient Occlusion (DFAO) in Unreal Engine’s rendering system. This setting variable allows developers to adjust the balance between accurate occlusion and potential artifacts in specular reflections.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the Distance Field Ambient Occlusion subsystem. It directly affects how specular reflections interact with ambient occlusion, which is an important aspect of realistic lighting in 3D scenes.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

The associated variable GDistanceFieldAOSpecularOcclusionMode interacts directly with r.AOSpecularOcclusionMode. They share the same value, with GDistanceFieldAOSpecularOcclusionMode being the actual integer variable used in the C++ code, while r.AOSpecularOcclusionMode is the console variable name used for external access and configuration.

Developers must be aware that this variable has two possible values: 0: Applies non-directional AO to specular reflections. 1 (default): Intersects the reflection cone with the unoccluded cone produced by DFAO.

The choice between these modes involves a trade-off. Mode 1 provides more accurate occlusion but may introduce DFAO sampling artifacts. Mode 0 is less accurate but potentially smoother.

Best practices when using this variable include:

  1. Testing both modes in various lighting conditions to determine which works best for your specific scene.
  2. Being aware of potential artifacts when using mode 1, especially in scenes with complex geometry.
  3. Considering performance implications, as mode 1 may be slightly more computationally expensive.
  4. Using this in conjunction with other AO and lighting settings for optimal results.

Regarding the associated variable GDistanceFieldAOSpecularOcclusionMode:

The purpose of GDistanceFieldAOSpecularOcclusionMode is to serve as the actual integer storage for the r.AOSpecularOcclusionMode setting within the C++ code of the engine.

This variable is used directly in the Renderer module, specifically in the SetupUniformBufferParameters function of the FViewInfo class. It’s used to set the DistanceFieldAOSpecularOcclusionMode parameter in the ViewUniformShaderParameters, which likely feeds into shaders responsible for rendering the scene.

The value of GDistanceFieldAOSpecularOcclusionMode is set by the console variable system when r.AOSpecularOcclusionMode is modified.

Developers should be aware that changes to r.AOSpecularOcclusionMode will directly affect GDistanceFieldAOSpecularOcclusionMode, and vice versa. Any code that needs to read or modify this setting should use the appropriate variable based on the context (console variable for external access, GDistanceFieldAOSpecularOcclusionMode for internal C++ code).

Best practices include using the console variable (r.AOSpecularOcclusionMode) for runtime or configuration changes, and referring to GDistanceFieldAOSpecularOcclusionMode when working within the C++ codebase of the engine.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GDistanceFieldAOSpecularOcclusionMode = 1;
FAutoConsoleVariableRef CVarDistanceFieldAOSpecularOcclusionMode(
	TEXT("r.AOSpecularOcclusionMode"),
	GDistanceFieldAOSpecularOcclusionMode,
	TEXT("Determines how specular should be occluded by DFAO\n")
	TEXT("0: Apply non-directional AO to specular.\n")
	TEXT("1: (default) Intersect the reflection cone with the unoccluded cone produced by DFAO.  This gives more accurate occlusion than 0, but can bring out DFAO sampling artifacts.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:55

Scope: file

Source code excerpt:

	);

int32 GDistanceFieldAOSpecularOcclusionMode = 1;
FAutoConsoleVariableRef CVarDistanceFieldAOSpecularOcclusionMode(
	TEXT("r.AOSpecularOcclusionMode"),
	GDistanceFieldAOSpecularOcclusionMode,
	TEXT("Determines how specular should be occluded by DFAO\n")
	TEXT("0: Apply non-directional AO to specular.\n")
	TEXT("1: (default) Intersect the reflection cone with the unoccluded cone produced by DFAO.  This gives more accurate occlusion than 0, but can bring out DFAO sampling artifacts.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:1913

Scope (from outer to inner):

file
function     void FViewInfo::SetupUniformBufferParameters

Source code excerpt:

	ViewUniformShaderParameters.ShowDecalsMask = Family->EngineShowFlags.Decals ? 1.0f : 0.0f;

	extern int32 GDistanceFieldAOSpecularOcclusionMode;
	ViewUniformShaderParameters.DistanceFieldAOSpecularOcclusionMode = GDistanceFieldAOSpecularOcclusionMode;

	ViewUniformShaderParameters.IndirectCapsuleSelfShadowingIntensity = Scene ? Scene->DynamicIndirectShadowsSelfShadowingIntensity : 1.0f;

	extern FVector GetReflectionEnvironmentRoughnessMixingScaleBiasAndLargestWeight();
	ViewUniformShaderParameters.ReflectionEnvironmentRoughnessMixingScaleBiasAndLargestWeight = (FVector3f)GetReflectionEnvironmentRoughnessMixingScaleBiasAndLargestWeight();