r.Shadow.CachePreshadow

r.Shadow.CachePreshadow

#Overview

name: r.Shadow.CachePreshadow

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

• type: Var
• help: Whether preshadows can be cached as an optimization

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.CachePreshadow is to control whether preshadows can be cached as an optimization in the rendering system of Unreal Engine 5.

This setting variable is primarily used by the Renderer module of Unreal Engine, specifically in the shadow rendering subsystem. Based on the callsites, it’s implemented in the ShadowSetup.cpp file, which is part of the rendering pipeline.

The value of this variable is set through a console variable (CVarCachePreshadows) with a default value of 1 (enabled). It can be modified at runtime using console commands or through engine configuration files.

The associated variable CVarCachePreshadows directly interacts with r.Shadow.CachePreshadow. They share the same value and purpose. The ShouldUseCachePreshadows() function uses this variable to determine if preshadow caching should be used.

Developers should be aware that this variable affects rendering performance and visual quality. Enabling preshadow caching (the default setting) can improve performance by reusing shadow information across frames, but it might lead to less accurate shadows in dynamic scenes.

Best practices when using this variable include:

1. Leave it enabled (default) for most scenarios to benefit from the performance optimization.
2. Consider disabling it temporarily when debugging shadow-related issues, as mentioned in the code comments.
3. Test the impact of enabling/disabling this feature in your specific game scenarios, especially in highly dynamic environments.

Regarding the associated variable CVarCachePreshadows:

The purpose of CVarCachePreshadows is to provide a runtime-configurable way to control the r.Shadow.CachePreshadow setting. It’s implemented as a TAutoConsoleVariable, which allows easy integration with the Unreal Engine’s console variable system.

This variable is used directly in the rendering code to determine whether preshadow caching should be applied. The ShouldUseCachePreshadows() function reads its value to make this determination.

The value of CVarCachePreshadows is set when the engine initializes, but it can be changed at runtime through console commands or configuration files.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarCachePreshadows include:

1. Use it for debugging or performance testing scenarios where you need to toggle preshadow caching on and off.
2. Be cautious when changing its value in shipping builds, as it can affect both performance and visual quality.
3. Consider exposing this setting in your game’s graphics options if you want to give users control over this optimization.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:156

Scope: file

Source code excerpt:

 */
static TAutoConsoleVariable<int32> CVarCachePreshadows(
	TEXT("r.Shadow.CachePreshadow"),
	1,
	TEXT("Whether preshadows can be cached as an optimization"),
	ECVF_RenderThreadSafe
	);

/**

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:155

Scope: file

Source code excerpt:

 * Disabling the caching through this setting is useful when debugging.
 */
static TAutoConsoleVariable<int32> CVarCachePreshadows(
	TEXT("r.Shadow.CachePreshadow"),
	1,
	TEXT("Whether preshadows can be cached as an optimization"),
	ECVF_RenderThreadSafe
	);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:176

Scope (from outer to inner):

file
function     bool ShouldUseCachePreshadows

Source code excerpt:

bool ShouldUseCachePreshadows()
{
	return CVarCachePreshadows.GetValueOnRenderThread() != 0;
}

int32 GPreshadowsForceLowestLOD = 0;
FAutoConsoleVariableRef CVarPreshadowsForceLowestLOD(
	TEXT("r.Shadow.PreshadowsForceLowestDetailLevel"),
	GPreshadowsForceLowestLOD,