r.Shadow.CacheWPOPrimitives

r.Shadow.CacheWPOPrimitives

#Overview

name: r.Shadow.CacheWPOPrimitives

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

• type: Var
• help: Whether primitives whose materials use World Position Offset should be considered movable for cached shadowmaps.\nEnablings this gives more correct, but slower whole scene shadows from materials that use WPO.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.CacheWPOPrimitives is to control whether primitives using World Position Offset (WPO) in their materials should be considered movable for cached shadowmaps in Unreal Engine’s rendering system.

This setting variable is primarily used by Unreal Engine’s rendering system, specifically the shadow caching subsystem. It’s referenced in the Engine module, as seen in the PrimitiveSceneProxy.cpp and UnrealEngine.cpp files.

The value of this variable is set through the console variable system. It’s initialized with a default value of 0 (disabled) when the CVarCacheWPOPrimitives console variable is created.

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

Developers must be aware that enabling this variable (setting it to non-zero) can result in more correct but slower whole scene shadows from materials that use World Position Offset. This trade-off between accuracy and performance is crucial to consider when optimizing shadow rendering.

Best practices when using this variable include:

1. Keep it disabled (0) by default for better performance.
2. Enable it (1) when higher shadow accuracy is required for materials using WPO, and the performance cost is acceptable.
3. Test the impact on performance and visual quality when changing this setting, as it can significantly affect shadow rendering.

Regarding the associated variable CVarCacheWPOPrimitives:

The purpose of CVarCacheWPOPrimitives is the same as r.Shadow.CacheWPOPrimitives - to control the caching behavior of primitives using World Position Offset for shadowmaps.

It’s used in the Engine module, specifically in the PrimitiveSceneProxy.cpp file. The CacheShadowDepthsFromPrimitivesUsingWPO() function directly uses this variable to determine whether to cache shadow depths from primitives using WPO.

The value is set when the console variable is created, with a default of 0. It can be changed at runtime through the console or code.

CVarCacheWPOPrimitives directly interacts with r.Shadow.CacheWPOPrimitives, as they represent the same setting.

Developers should be aware that this variable is marked with ECVF_RenderThreadSafe and ECVF_Scalability flags, indicating it’s safe to modify on the render thread and is considered a scalability setting.

Best practices include using the CacheShadowDepthsFromPrimitivesUsingWPO() function to check the current state of this setting, rather than accessing the console variable directly in performance-critical code paths.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PrimitiveSceneProxy.cpp:54

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarCacheWPOPrimitives(
	TEXT("r.Shadow.CacheWPOPrimitives"),
	0,
	TEXT("Whether primitives whose materials use World Position Offset should be considered movable for cached shadowmaps.\n")
	TEXT("Enablings this gives more correct, but slower whole scene shadows from materials that use WPO."),
	ECVF_RenderThreadSafe | ECVF_Scalability
	);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:283

Scope (from outer to inner):

file
function     void FEngineModule::StartupModule

Source code excerpt:

	GGetMapNameDelegate.BindStatic(&GetMapNameStatic);

	static IConsoleVariable* CacheWPOPrimitivesVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.CacheWPOPrimitives"));
	CacheWPOPrimitivesVar->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&OnChangeEngineCVarRequiringRecreateRenderState));

	static auto CVARShowMaterialDrawEvents = IConsoleManager::Get().FindConsoleVariable(TEXT("r.ShowMaterialDrawEvents"));
	if (CVARShowMaterialDrawEvents)
	{
		CVARShowMaterialDrawEvents->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&OnChangeEngineCVarRequiringRecreateRenderState));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PrimitiveSceneProxy.cpp:53

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarCacheWPOPrimitives(
	TEXT("r.Shadow.CacheWPOPrimitives"),
	0,
	TEXT("Whether primitives whose materials use World Position Offset should be considered movable for cached shadowmaps.\n")
	TEXT("Enablings this gives more correct, but slower whole scene shadows from materials that use WPO."),
	ECVF_RenderThreadSafe | ECVF_Scalability
	);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PrimitiveSceneProxy.cpp:126

Scope (from outer to inner):

file
function     bool CacheShadowDepthsFromPrimitivesUsingWPO

Source code excerpt:

bool CacheShadowDepthsFromPrimitivesUsingWPO()
{
	return CVarCacheWPOPrimitives.GetValueOnAnyThread(true) != 0;
}

bool SupportsCachingMeshDrawCommands(const FMeshBatch& MeshBatch)
{
	return
		// Cached mesh commands only allow for a single mesh element per batch.