r.CapsuleMaxDirectOcclusionDistance

r.CapsuleMaxDirectOcclusionDistance

#Overview

name: r.CapsuleMaxDirectOcclusionDistance

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.CapsuleMaxDirectOcclusionDistance is to control the maximum cast distance for direct shadows from capsules in Unreal Engine’s rendering system. This setting variable is crucial for balancing shadow quality and performance in the engine’s rendering pipeline.

This setting variable is primarily used by the Renderer module of Unreal Engine, specifically in the capsule shadow rendering subsystem. It’s referenced in the CapsuleShadowRendering.cpp file, which is part of the runtime renderer.

The value of this variable is set through the engine’s console variable system. It’s initialized with a default value of 400 units and can be modified at runtime using console commands or through project settings.

The associated variable GCapsuleMaxDirectOcclusionDistance directly interacts with r.CapsuleMaxDirectOcclusionDistance. They share the same value, with GCapsuleMaxDirectOcclusionDistance being the C++ variable that stores the actual value used in the rendering code.

Developers must be aware that this variable has a significant impact on performance. Increasing the value will result in longer-range capsule shadows, which can improve visual quality but at the cost of increased rendering time. Conversely, decreasing the value will improve performance but may result in noticeable pop-in of capsule shadows at closer distances.

Best practices when using this variable include:

  1. Carefully balancing visual quality and performance requirements.
  2. Testing different values to find the optimal setting for your specific project.
  3. Considering scalability options, allowing the value to be adjusted based on hardware capabilities.
  4. Using it in conjunction with other shadow-related settings for a cohesive shadow rendering strategy.

Regarding the associated variable GCapsuleMaxDirectOcclusionDistance: This is the C++ variable that directly stores the value set by r.CapsuleMaxDirectOcclusionDistance. It’s used in the actual rendering code to determine the maximum distance for capsule shadow calculations. The variable is defined in the same file (CapsuleShadowRendering.cpp) and is used in the RenderCapsuleDirectShadows function of the FDeferredShadingSceneRenderer class.

Developers should be aware that modifying GCapsuleMaxDirectOcclusionDistance directly in C++ code is not recommended. Instead, they should use the r.CapsuleMaxDirectOcclusionDistance console variable to ensure proper synchronization and to take advantage of the engine’s built-in settings management system.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GCapsuleMaxDirectOcclusionDistance = 400;
FAutoConsoleVariableRef CVarCapsuleMaxDirectOcclusionDistance(
	TEXT("r.CapsuleMaxDirectOcclusionDistance"),
	GCapsuleMaxDirectOcclusionDistance,
	TEXT("Maximum cast distance for direct shadows from capsules.  This has a big impact on performance."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GCapsuleMaxIndirectOcclusionDistance = 200;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

float GCapsuleMaxDirectOcclusionDistance = 400;
FAutoConsoleVariableRef CVarCapsuleMaxDirectOcclusionDistance(
	TEXT("r.CapsuleMaxDirectOcclusionDistance"),
	GCapsuleMaxDirectOcclusionDistance,
	TEXT("Maximum cast distance for direct shadows from capsules.  This has a big impact on performance."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GCapsuleMaxIndirectOcclusionDistance = 200;
FAutoConsoleVariableRef CVarCapsuleMaxIndirectOcclusionDistance(

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

Scope (from outer to inner):

file
function     bool FDeferredShadingSceneRenderer::RenderCapsuleDirectShadows

Source code excerpt:

					ScissorRect,
					GetCapsuleShadowDownsampleFactor(),
					GCapsuleMaxDirectOcclusionDistance,
					Scene,
					View,
					SceneTexturesUniformBuffer,
					CapsuleShapeData.Num(),
					GraphBuilder.CreateSRV(ShadowCapsuleShapesBuffer),
					0,