r.Shadow.Virtual.Clipmap.FirstCoarseLevel

r.Shadow.Virtual.Clipmap.FirstCoarseLevel

#Overview

name: r.Shadow.Virtual.Clipmap.FirstCoarseLevel

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.FirstCoarseLevel is to control the resolution of virtual shadow map pages in Unreal Engine 5’s rendering system, specifically for the virtual shadow map clipmap feature. It determines the first level of the clipmap where coarse pages are marked, affecting the balance between shadow quality and performance.

This setting variable is primarily used by the rendering subsystem, particularly in the virtual shadow maps module. Based on the callsites, it’s implemented in the VirtualShadowMapClipmap.cpp file, which is part of the Renderer module.

The value of this variable is set using a TAutoConsoleVariable, which means it can be adjusted at runtime through console commands or configuration files. The default value is set to 15.

This variable interacts closely with another variable, CVarVirtualShadowMapClipmapLastCoarseLevel, which sets the last level of the clipmap for coarse pages. Together, these variables define the range of clipmap levels where coarse pages are used.

Developers should be aware that lowering the value of this variable will allow higher resolution coarse pages near the camera, potentially improving shadow quality in the foreground. However, this comes at the cost of increased total page counts, which can impact performance and memory usage.

Best practices when using this variable include:

  1. Balancing it with CVarVirtualShadowMapClipmapLastCoarseLevel for optimal performance and quality.
  2. Testing different values to find the right trade-off between shadow quality and performance for your specific game or application.
  3. Considering the target hardware capabilities when adjusting this value, as lower-end devices may benefit from higher values to reduce memory usage.

Regarding the associated variable CVarVirtualShadowMapClipmapFirstCoarseLevel:

This is the actual console variable object that stores and manages the r.Shadow.Virtual.Clipmap.FirstCoarseLevel setting. It’s defined using TAutoConsoleVariable, which allows for runtime modification.

The purpose of this variable is the same as r.Shadow.Virtual.Clipmap.FirstCoarseLevel, controlling the first level of the clipmap to mark coarse pages for in the virtual shadow map system.

It’s used in the GetCoarsePageClipmapIndexMask function of the FVirtualShadowMapClipmap class to calculate the range of coarse page levels. This function likely determines which pages in the clipmap should be rendered as coarse pages.

Developers should be aware that this variable is accessed using the GetValueOnRenderThread() method, ensuring thread-safe access in the render thread.

Best practices for using this variable include:

  1. Modifying it through the console or configuration files rather than changing the hard-coded default value.
  2. Considering its impact on both visual quality and performance when adjusting it.
  3. Testing changes thoroughly across different scenes and lighting conditions to ensure optimal results.

#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:50

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarVirtualShadowMapClipmapFirstCoarseLevel(
	TEXT("r.Shadow.Virtual.Clipmap.FirstCoarseLevel"),
	15,
	TEXT("First level of the clipmap to mark coarse pages for. Lower values allow higher resolution coarse pages near the camera but increase total page counts."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarVirtualShadowMapClipmapLastCoarseLevel(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarVirtualShadowMapClipmapFirstCoarseLevel(
	TEXT("r.Shadow.Virtual.Clipmap.FirstCoarseLevel"),
	15,
	TEXT("First level of the clipmap to mark coarse pages for. Lower values allow higher resolution coarse pages near the camera but increase total page counts."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     uint32 FVirtualShadowMapClipmap::GetCoarsePageClipmapIndexMask

Source code excerpt:

	const int FirstLevel = GetFirstLevel();
	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)