r.Shadow.PerObjectSpotLightDepthBias

r.Shadow.PerObjectSpotLightDepthBias

#Overview

name: r.Shadow.PerObjectSpotLightDepthBias

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

• type: Var
• help: Depth bias that is applied in the depth pass for per-object projected shadows from spot lights

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.PerObjectSpotLightDepthBias is to control the depth bias applied in the depth pass for per-object projected shadows from spot lights in Unreal Engine’s rendering system.

This setting variable is primarily used by the Renderer module of Unreal Engine, specifically in the shadow rendering subsystem. It’s defined and utilized in the ShadowRendering.cpp file, which is part of the core rendering pipeline.

The value of this variable is set using a TAutoConsoleVariable, which means it can be adjusted at runtime through console commands. Its default value is 3.0f.

This variable interacts closely with another variable called CVarPerObjectSpotLightShadowSlopeScaleDepthBias, which controls the slope scale depth bias for the same type of shadows.

Developers must be aware that this variable directly affects the quality and appearance of shadows cast by spot lights in the scene. Adjusting this value can help reduce shadow acne (self-shadowing artifacts) but may also introduce peter-panning (shadows detaching from objects) if set too high.

Best practices when using this variable include:

1. Fine-tuning it in conjunction with the slope scale depth bias for optimal results.
2. Testing different values in various lighting scenarios to find the best balance between shadow quality and performance.
3. Being cautious when modifying it, as extreme values can significantly impact visual quality.

Regarding the associated variable CVarPerObjectSpotLightShadowDepthBias:

This is the actual console variable that stores the value of r.Shadow.PerObjectSpotLightDepthBias. It’s defined using TAutoConsoleVariable, which allows it to be changed at runtime.

The purpose of CVarPerObjectSpotLightShadowDepthBias is the same as r.Shadow.PerObjectSpotLightDepthBias - to control the depth bias for per-object spot light shadows.

This variable is used directly in the UpdateShaderDepthBias function of the FProjectedShadowInfo class. Here, its value is retrieved using GetValueOnRenderThread() and used to calculate the final depth bias applied to the shadows.

Developers should be aware that changes to this variable will take effect immediately on the render thread, potentially causing visual changes in real-time.

Best practices for using CVarPerObjectSpotLightShadowDepthBias include:

1. Using it for fine-tuning shadow appearance in development builds.
2. Documenting any non-default values used in production to ensure consistency across different rendering scenarios.
3. Considering performance implications when adjusting this value, as it can affect shadow rendering complexity.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarPerObjectSpotLightShadowDepthBias(
	TEXT("r.Shadow.PerObjectSpotLightDepthBias"),
	3.0f,
	TEXT("Depth bias that is applied in the depth pass for per-object projected shadows from spot lights"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarPerObjectSpotLightShadowSlopeScaleDepthBias(
	TEXT("r.Shadow.PerObjectSpotLightSlopeDepthBias"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarPerObjectSpotLightShadowDepthBias(
	TEXT("r.Shadow.PerObjectSpotLightDepthBias"),
	3.0f,
	TEXT("Depth bias that is applied in the depth pass for per-object projected shadows from spot lights"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarPerObjectSpotLightShadowSlopeScaleDepthBias(

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

Scope (from outer to inner):

file
function     void FProjectedShadowInfo::UpdateShaderDepthBias

Source code excerpt:

			{
				// spot lights (old code, might need to be improved)
				const float LightTypeDepthBias = CVarPerObjectSpotLightShadowDepthBias.GetValueOnRenderThread();
				DepthBias = LightTypeDepthBias * 512.0f / ((MaxSubjectZ - MinSubjectZ) * FMath::Max(ResolutionX, ResolutionY));
				// * 2.0f to be compatible with the system we had before ShadowBias
				DepthBias *= 2.0f * LightSceneInfo->Proxy->GetUserShadowBias();

				SlopeScaleDepthBias = CVarPerObjectSpotLightShadowSlopeScaleDepthBias.GetValueOnRenderThread();
				SlopeScaleDepthBias *= LightSceneInfo->Proxy->GetUserShadowSlopeBias();