r.Shadow.Virtual.Clipmap.ZRangeScale

r.Shadow.Virtual.Clipmap.ZRangeScale

#Overview

name: r.Shadow.Virtual.Clipmap.ZRangeScale

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

• type: Var
• help: Scale of the clipmap level depth range relative to the radius. Affects z-near/z-far of the shadow map. Should generally be at least 10 or it will result in excessive cache invalidations. Values that are too large cause depth imprecisions and shadow flickering.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.Clipmap.ZRangeScale is to control the scale of the clipmap level depth range relative to the radius in the Virtual Shadow Map system. This setting variable is specifically for the rendering system, particularly for shadow rendering.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the Virtual Shadow Maps subsystem. Based on the callsites, it’s utilized in the VirtualShadowMapClipmap.cpp file, which is part of the virtual shadow map implementation.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1000.0f, but can be changed at runtime through console commands or project settings.

The associated variable CVarVirtualShadowMapClipmapZRangeScale directly interacts with r.Shadow.Virtual.Clipmap.ZRangeScale. They share the same value and purpose.

Developers must be aware of several important aspects when using this variable:

1. It affects the z-near and z-far planes of the shadow map.
2. Values below 10 may result in excessive cache invalidations.
3. Values that are too large can cause depth imprecisions and shadow flickering.

Best practices when using this variable include:

1. Keep the value at least 10 to avoid excessive cache invalidations.
2. Adjust the value carefully, as it directly impacts shadow quality and performance.
3. Monitor for depth imprecisions and shadow flickering when increasing the value.
4. Consider the trade-off between shadow map coverage and precision when adjusting this value.

Regarding the associated variable CVarVirtualShadowMapClipmapZRangeScale:

• It’s purpose is identical to r.Shadow.Virtual.Clipmap.ZRangeScale.
• It’s used in the same Renderer module and Virtual Shadow Maps subsystem.
• The value is set through the same CVar system.
• It’s used directly in the FVirtualShadowMapClipmap constructor to calculate the view radius Z scale.
• The same awareness points and best practices apply to this variable as well.

Developers should treat CVarVirtualShadowMapClipmapZRangeScale as the programmatic way to access and modify the r.Shadow.Virtual.Clipmap.ZRangeScale setting within C++ code.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<float> CVarVirtualShadowMapClipmapZRangeScale(
	TEXT("r.Shadow.Virtual.Clipmap.ZRangeScale"),
	1000.0f,
	TEXT("Scale of the clipmap level depth range relative to the radius. Affects z-near/z-far of the shadow map. Should generally be at least 10 or it will result in excessive cache invalidations. Values that are too large cause depth imprecisions and shadow flickering."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarVirtualShadowMapClipmapMinCameraViewportWidth(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<float> CVarVirtualShadowMapClipmapZRangeScale(
	TEXT("r.Shadow.Virtual.Clipmap.ZRangeScale"),
	1000.0f,
	TEXT("Scale of the clipmap level depth range relative to the radius. Affects z-near/z-far of the shadow map. Should generally be at least 10 or it will result in excessive cache invalidations. Values that are too large cause depth imprecisions and shadow flickering."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     FVirtualShadowMapClipmap::FVirtualShadowMapClipmap

Source code excerpt:

	// NOTE: It's tempting to use a single global Z range for the entire clipmap (which avoids some SMRT overhead too)
	// but this can cause precision issues with cached pages very near the camera.
	const double ViewRadiusZScale = CVarVirtualShadowMapClipmapZRangeScale.GetValueOnRenderThread();
	const FVector ViewCenter = WorldToLightViewRotationMatrix.TransformPosition(WorldOrigin);

	for (int32 Index = 0; Index < LevelCount; ++Index)
	{
		FLevelData& Level = LevelData[Index];
		const int32 AbsoluteLevel = Index + FirstLevel;		// Absolute (virtual) level index