r.Shadow.Virtual.NormalBias

r.Shadow.Virtual.NormalBias

#Overview

name: r.Shadow.Virtual.NormalBias

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.Shadow.Virtual.NormalBias is to control the receiver offset along the surface normal for shadow lookup in virtual shadow maps. This setting is part of the rendering system, specifically the virtual shadow mapping subsystem in Unreal Engine 5.

The Unreal Engine rendering module relies on this setting variable, as evidenced by its use in the VirtualShadowMapProjection.cpp file within the Renderer source code.

The value of this variable is set through a console variable (CVar) system, with a default value of 0.5f. It can be modified at runtime or through configuration files.

The associated variable CVarNormalBias directly interacts with r.Shadow.Virtual.NormalBias, as they share the same value and purpose.

Developers must be aware that this variable affects the trade-off between artifact avoidance and shadow accuracy. Higher values can help avoid artifacts on surfaces nearly parallel to the light but may also cause visibility offset shadows and increase the chance of hitting unmapped pages in the virtual shadow map.

Best practices when using this variable include:

  1. Adjusting it carefully to find the optimal balance between artifact reduction and shadow accuracy for your specific scene.
  2. Testing different values in various lighting scenarios to ensure consistent quality across your game.
  3. Considering performance implications, as higher values may increase the chance of hitting unmapped pages, potentially affecting rendering performance.

Regarding the associated variable CVarNormalBias:

The purpose of CVarNormalBias is to provide a programmatic interface to access and modify the r.Shadow.Virtual.NormalBias setting within the C++ code.

It is used in the rendering system, specifically in the virtual shadow map projection functionality.

The value of CVarNormalBias is set through the console variable system, mirroring the value of r.Shadow.Virtual.NormalBias.

CVarNormalBias interacts directly with r.Shadow.Virtual.NormalBias, as they represent the same setting.

Developers should be aware that CVarNormalBias is accessed on the render thread, as seen in the GetNormalBiasForShader() function, where its value is retrieved using GetValueOnRenderThread().

Best practices for using CVarNormalBias include:

  1. Accessing it only on the render thread to avoid threading issues.
  2. Using the provided GetNormalBiasForShader() function when needing the value in shader calculations, as it applies the necessary scaling (dividing by 1000.0f).
  3. Considering caching the value if it’s accessed frequently, to avoid potential performance overhead from repeated CVar lookups.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapProjection.cpp:38

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarNormalBias(
	TEXT( "r.Shadow.Virtual.NormalBias" ),
	0.5f,
	TEXT( "Receiver offset along surface normal for shadow lookup. Scaled by distance to camera." )
	TEXT( "Higher values avoid artifacts on surfaces nearly parallel to the light, but also visibility offset shadows and increase the chance of hitting unmapped pages." ),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapProjection.cpp:37

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarNormalBias(
	TEXT( "r.Shadow.Virtual.NormalBias" ),
	0.5f,
	TEXT( "Receiver offset along surface normal for shadow lookup. Scaled by distance to camera." )
	TEXT( "Higher values avoid artifacts on surfaces nearly parallel to the light, but also visibility offset shadows and increase the chance of hitting unmapped pages." ),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapProjection.cpp:321

Scope (from outer to inner):

file
function     static float GetNormalBiasForShader

Source code excerpt:

static float GetNormalBiasForShader()
{
	return CVarNormalBias.GetValueOnRenderThread() / 1000.0f;
}

static void RenderVirtualShadowMapProjectionCommon(
	FRDGBuilder& GraphBuilder,
	const FMinimalSceneTextures& SceneTextures,
	const FViewInfo& View, int32 ViewIndex,