r.Shadow.CSMDepthBoundsTest

r.Shadow.CSMDepthBoundsTest

#Overview

name: r.Shadow.CSMDepthBoundsTest

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

• type: Var
• help: Whether to use depth bounds tests rather than stencil tests for the CSM bounds

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.CSMDepthBoundsTest is to control whether depth bounds tests are used instead of stencil tests for Cascaded Shadow Map (CSM) bounds in Unreal Engine’s rendering system.

This setting variable is primarily used in the rendering system, specifically for shadow rendering. It is part of the Renderer module in Unreal Engine.

The value of this variable is set through the console variable system in Unreal Engine. It is initialized with a default value of 1 (enabled) and can be changed at runtime.

The associated variable CVarCSMDepthBoundsTest directly interacts with r.Shadow.CSMDepthBoundsTest. They share the same value and purpose.

Developers must be aware that:

1. This variable only affects whole scene directional shadows.
2. It requires hardware support for depth bounds testing (GSupportsDepthBoundsTest must be true).
3. It may interact with other shadow rendering techniques, such as sub-pixel shadows.

Best practices when using this variable include:

1. Only enable it if the target hardware supports depth bounds testing.
2. Consider the performance implications of using depth bounds tests vs. stencil tests on the target platform.
3. Test thoroughly when changing this setting, as it may affect shadow quality and performance.

Regarding the associated variable CVarCSMDepthBoundsTest:

The purpose of CVarCSMDepthBoundsTest is identical to r.Shadow.CSMDepthBoundsTest. It’s an internal representation of the console variable in C++ code.

This variable is used in the Renderer module, specifically in the shadow rendering subsystem.

The value is set when the console variable is initialized or changed through the console command system.

It directly interacts with the r.Shadow.CSMDepthBoundsTest console variable, sharing the same value.

Developers should be aware that this variable is used in conditional statements to determine whether to use depth bounds tests for CSM shadows.

Best practices include:

1. Use this variable for runtime checks of the depth bounds test setting.
2. Be cautious when modifying this variable directly, as it should typically be controlled through the console variable system.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarCSMDepthBoundsTest(
	TEXT("r.Shadow.CSMDepthBoundsTest"),
	1,
	TEXT("Whether to use depth bounds tests rather than stencil tests for the CSM bounds"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTransitionScale(
	TEXT("r.Shadow.TransitionScale"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowRendering.cpp:56

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarCSMDepthBoundsTest(
	TEXT("r.Shadow.CSMDepthBoundsTest"),
	1,
	TEXT("Whether to use depth bounds tests rather than stencil tests for the CSM bounds"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTransitionScale(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowRendering.cpp:1158

Scope: file

Source code excerpt:

	SetupFrustumForProjection(View, FrustumVertices, bCameraInsideShadowFrustum, OutPlanes);

	const bool bDepthBoundsTestEnabled = IsWholeSceneDirectionalShadow() && GSupportsDepthBoundsTest && CVarCSMDepthBoundsTest.GetValueOnRenderThread() != 0;// && !bSubPixelSupport;

	if (bSubPixelShadow)
	{
		// Do not apply pre-shadow on opaque geometry during sub-pixel pass as we only care about opaque geometry 'casting' shadow (not receiving shadow)
		// However, applied pre-shadow onto hair primitive (which are the only one able to cast deep shadow)
		if (bPreShadow)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowRendering.cpp:1295

Scope: file

Source code excerpt:

	const bool bSubPixelSupport = HairStrandsUniformBuffer != nullptr;// HairStrands::HasViewHairStrandsData(*View);
	const bool bStencilTestEnabled = !bSubPixelSupport && GShadowStencilCulling;
	const bool bDepthBoundsTestEnabled = IsWholeSceneDirectionalShadow() && GSupportsDepthBoundsTest && CVarCSMDepthBoundsTest.GetValueOnRenderThread() != 0;// && !bSubPixelSupport;
	const uint32 StencilRef = bSubPixelSupport && !IsWholeSceneDirectionalShadow() && !bCameraInsideShadowFrustum ? 1u : 0u;

	if (!bDepthBoundsTestEnabled && bStencilTestEnabled)
	{
		SetupProjectionStencilMask(RHICmdList, View, ViewIndex, SceneRender, FrustumVertices, bMobileModulatedProjections, bCameraInsideShadowFrustum, InstanceCullingDrawParams);
	}