r.Shadow.Virtual.Clipmap.LastCoarseLevel

r.Shadow.Virtual.Clipmap.LastCoarseLevel

#Overview

name: r.Shadow.Virtual.Clipmap.LastCoarseLevel

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.Clipmap.LastCoarseLevel is to control the last level of the virtual shadow map clipmap that will be marked for coarse pages. This setting is part of Unreal Engine 5’s virtual shadow map system, which is a component of the rendering subsystem.

This setting variable is primarily used in the Renderer module, specifically within the virtual shadow maps implementation. It’s defined and used in the VirtualShadowMapClipmap.cpp file, which suggests it’s closely tied to the clipmap functionality of virtual shadow maps.

The value of this variable is set through a console variable (CVar) system, which allows it to be adjusted at runtime. It’s initialized with a default value of 18, but this can be changed dynamically.

This variable interacts closely with other clipmap-related variables, particularly CVarVirtualShadowMapClipmapFirstCoarseLevel. Together, these variables define the range of clipmap levels that will be marked for coarse pages.

Developers should be aware that increasing this value will provide denser clipmap data for a longer radius, but it will also increase the total page counts. This trade-off between quality and performance should be carefully considered.

Best practices when using this variable include:

  1. Balancing it with CVarVirtualShadowMapClipmapFirstCoarseLevel to optimize the range of coarse pages.
  2. Monitoring performance impacts when adjusting this value, especially in scenes with complex shadowing.
  3. Considering the target hardware capabilities when setting this value, as higher values may be more demanding on resources.

Regarding the associated variable CVarVirtualShadowMapClipmapLastCoarseLevel:

This is the actual console variable object that controls the r.Shadow.Virtual.Clipmap.LastCoarseLevel setting. It’s defined using the TAutoConsoleVariable template, which is part of Unreal Engine’s console variable system.

The purpose of CVarVirtualShadowMapClipmapLastCoarseLevel is to provide a programmatic interface for getting and setting the r.Shadow.Virtual.Clipmap.LastCoarseLevel value. It’s used within the engine code to retrieve the current value of the setting and apply it to the virtual shadow map clipmap calculations.

This variable is typically accessed using the GetValueOnRenderThread() method, which ensures thread-safe access to the value from the render thread.

Developers should be aware that this variable has the ECVF_Scalability and ECVF_RenderThreadSafe flags, which indicate that it affects scalability settings and is safe to access from the render thread.

Best practices for using CVarVirtualShadowMapClipmapLastCoarseLevel include:

  1. Always accessing it from the appropriate thread (render thread in this case).
  2. Considering its impact on scalability when adjusting its value.
  3. Using it in conjunction with other clipmap-related variables for a holistic approach to virtual shadow map optimization.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarVirtualShadowMapClipmapLastCoarseLevel(
	TEXT("r.Shadow.Virtual.Clipmap.LastCoarseLevel"),
	18,
	TEXT("Last level of the clipmap to mark coarse pages for. Higher values provide dense clipmap data for a longer radius but increase total page counts."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

TAutoConsoleVariable<float> CVarVirtualShadowMapClipmapZRangeScale(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarVirtualShadowMapClipmapLastCoarseLevel(
	TEXT("r.Shadow.Virtual.Clipmap.LastCoarseLevel"),
	18,
	TEXT("Last level of the clipmap to mark coarse pages for. Higher values provide dense clipmap data for a longer radius but increase total page counts."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapClipmap.cpp:463

Scope (from outer to inner):

file
function     uint32 FVirtualShadowMapClipmap::GetCoarsePageClipmapIndexMask

Source code excerpt:

	const int LastLevel  = FMath::Max(FirstLevel, CVarVirtualShadowMapClipmapLastLevel.GetValueOnRenderThread());	
	int FirstCoarseIndex = CVarVirtualShadowMapClipmapFirstCoarseLevel.GetValueOnRenderThread() - FirstLevel;
	int LastCoarseIndex  = CVarVirtualShadowMapClipmapLastCoarseLevel.GetValueOnRenderThread() - FirstLevel;	

	ensureMsgf((LastLevel - FirstLevel) < 32, TEXT("Too many clipmap levels for coarse page bitmask."));

	FirstCoarseIndex = FMath::Max(0, FirstCoarseIndex);
	if (LastCoarseIndex >= FirstCoarseIndex)
	{