r.CapsuleMaxIndirectOcclusionDistance

r.CapsuleMaxIndirectOcclusionDistance

#Overview

name: r.CapsuleMaxIndirectOcclusionDistance

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.CapsuleMaxIndirectOcclusionDistance is to control the maximum cast distance for indirect shadows from capsules in Unreal Engine 5’s rendering system. This setting is crucial for balancing visual quality and performance in the game’s lighting and shadow systems.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the part responsible for capsule shadow rendering. This can be seen from the file path “Engine/Source/Runtime/Renderer/Private/CapsuleShadowRendering.cpp” where the variable is defined and used.

The value of this variable is set through a console variable system. It’s initialized with a default value of 200 units and can be dynamically adjusted at runtime using the console command “r.CapsuleMaxIndirectOcclusionDistance”.

This variable interacts directly with GCapsuleMaxIndirectOcclusionDistance, which is the internal global variable that stores the actual value. They share the same value, with r.CapsuleMaxIndirectOcclusionDistance being the console-accessible name.

Developers must be aware that this variable has a significant impact on performance, as stated in the comment. Increasing this value will result in indirect shadows being cast over longer distances, which can be more computationally expensive.

Best practices when using this variable include:

  1. Carefully balancing visual quality and performance.
  2. Adjusting the value based on the scale and requirements of your specific game environment.
  3. Testing different values to find the optimal setting for your game’s performance targets.
  4. Considering platform-specific adjustments, as mobile or less powerful platforms might benefit from a lower value.

Regarding the associated variable GCapsuleMaxIndirectOcclusionDistance:

The purpose of GCapsuleMaxIndirectOcclusionDistance is to store the actual value of the maximum cast distance for indirect shadows from capsules within the engine’s code.

This variable is used directly in the rendering calculations, such as in the CreateIndirectCapsuleShadows and RenderIndirectCapsuleShadows functions.

The value of this variable is set by the console variable system when r.CapsuleMaxIndirectOcclusionDistance is modified.

It interacts with the EffectiveMaxIndirectOcclusionDistance variable, which can be adjusted based on object size for distance field casters to improve shadow solidity.

Developers should be aware that modifying this variable directly in code is not recommended, as it’s intended to be controlled via the console variable system.

Best practices include using the console variable r.CapsuleMaxIndirectOcclusionDistance to modify this value rather than changing it directly in code, ensuring consistent behavior across the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CapsuleShadowRendering.cpp:74

Scope: file

Source code excerpt:

float GCapsuleMaxIndirectOcclusionDistance = 200;
FAutoConsoleVariableRef CVarCapsuleMaxIndirectOcclusionDistance(
	TEXT("r.CapsuleMaxIndirectOcclusionDistance"),
	GCapsuleMaxIndirectOcclusionDistance,
	TEXT("Maximum cast distance for indirect shadows from capsules.  This has a big impact on performance."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GCapsuleShadowFadeAngleFromVertical = PI / 3;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CapsuleShadowRendering.cpp:72

Scope: file

Source code excerpt:

	);

float GCapsuleMaxIndirectOcclusionDistance = 200;
FAutoConsoleVariableRef CVarCapsuleMaxIndirectOcclusionDistance(
	TEXT("r.CapsuleMaxIndirectOcclusionDistance"),
	GCapsuleMaxIndirectOcclusionDistance,
	TEXT("Maximum cast distance for indirect shadows from capsules.  This has a big impact on performance."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GCapsuleShadowFadeAngleFromVertical = PI / 3;
FAutoConsoleVariableRef CVarCapsuleShadowFadeAngleFromVertical(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CapsuleShadowRendering.cpp:715

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::CreateIndirectCapsuleShadows

Source code excerpt:

				FViewInfo& View = Views[ViewIndex];

				float EffectiveMaxIndirectOcclusionDistance = GCapsuleMaxIndirectOcclusionDistance;

				if (PrimitiveProxy->HasDistanceFieldRepresentation())
				{
					// Increase max occlusion distance based on object size for distance field casters
					// This improves the solidness of the shadows, since the fadeout distance causes internal structure of objects to become visible
					EffectiveMaxIndirectOcclusionDistance += .5f * LightingGroupBounds.SphereRadius;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CapsuleShadowRendering.cpp:1045

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderIndirectCapsuleShadows

Source code excerpt:

					ScissorRect,
					GetCapsuleShadowDownsampleFactor(),
					GCapsuleMaxIndirectOcclusionDistance,
					Scene,
					View,
					SceneTextures.UniformBuffer,
					NumCapsuleShapes,
					Resources.IndirectShadowCapsuleShapesSRV,
					NumMeshDistanceFieldCasters,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CapsuleShadowRendering.cpp:1231

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderCapsuleShadowsForMovableSkylight

Source code excerpt:

						ScissorRect,
						GAODownsampleFactor,
						GCapsuleMaxIndirectOcclusionDistance,
						Scene,
						View,
						SceneTexturesUniformBuffer,
						NumCapsuleShapes,
						Resources.IndirectShadowCapsuleShapesSRV,
						NumMeshDistanceFieldCasters,