r.Ortho.VSM.EstimateClipmapLevels

r.Ortho.VSM.EstimateClipmapLevels

#Overview

name: r.Ortho.VSM.EstimateClipmapLevels

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

• type: Var
• help: Enable/Disable calculating the FirstLevel VSM based on the current camera OrthoWidth

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Ortho.VSM.EstimateClipmapLevels is to control the calculation of the first level of Virtual Shadow Map (VSM) for orthographic cameras based on the current camera’s OrthoWidth. This setting is part of the rendering system, specifically related to shadow mapping for orthographic projections.

This setting variable is primarily used in the Virtual Shadow Map (VSM) subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s implemented in the VirtualShadowMapClipmap.cpp file, which is part of the renderer’s private implementation.

The value of this variable is set through a console variable (CVar) system. It’s defined as a boolean with a default value of true, meaning the estimation of clipmap levels is enabled by default.

This variable interacts with other VSM-related variables, particularly CVarVirtualShadowMapClipmapLastLevel and is used in conjunction with the orthographic camera settings.

Developers must be aware that this variable only affects orthographic cameras. When enabled, it optimizes the VSM generation by reducing the number of clipmaps and scaling the precision based on the scene’s requirements.

Best practices when using this variable include:

1. Keep it enabled (default) for most scenarios to benefit from optimized VSM generation for orthographic cameras.
2. Consider disabling it if you need consistent VSM behavior across perspective and orthographic cameras.
3. Monitor performance and shadow quality when adjusting this setting, as it can impact both.

Regarding the associated variable CVarOrthoVSMEstimateClipmapLevels:

The purpose of CVarOrthoVSMEstimateClipmapLevels is to serve as the internal representation of the r.Ortho.VSM.EstimateClipmapLevels console variable within the engine’s code.

This variable is used directly in the rendering subsystem, specifically in the VirtualShadowMapClipmap class constructor.

The value of this variable is set when the console variable is initialized and can be accessed using the GetValueOnRenderThread() method.

It interacts closely with the bIsOrthographicCamera flag and other VSM-related variables.

Developers should be aware that this variable is checked on the render thread, which means changes to it will affect the next frame render.

Best practices include:

1. Use this variable for render-thread specific logic related to VSM clipmap level estimation.
2. Be cautious when modifying its value during runtime, as it can affect ongoing rendering processes.
3. Consider the performance implications of frequently querying this value in performance-critical sections of 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:94

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarOrthoVSMEstimateClipmapLevels(
	TEXT("r.Ortho.VSM.EstimateClipmapLevels"),
	true,
	TEXT("Enable/Disable calculating the FirstLevel VSM based on the current camera OrthoWidth"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarOrthoVSMClipmapLODBias(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<bool> CVarOrthoVSMEstimateClipmapLevels(
	TEXT("r.Ortho.VSM.EstimateClipmapLevels"),
	true,
	TEXT("Enable/Disable calculating the FirstLevel VSM based on the current camera OrthoWidth"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     FVirtualShadowMapClipmap::FVirtualShadowMapClipmap

Source code excerpt:

	FirstLevel = GetFirstLevel();
	int32 LastLevel = CVarVirtualShadowMapClipmapLastLevel.GetValueOnRenderThread();	
	if (bIsOrthographicCamera && CVarOrthoVSMEstimateClipmapLevels.GetValueOnRenderThread())
	{
		/**
		* For Ortho projections, this branch bases the first level VSM on the set OrthoWidth. This reduces the number of clipmaps generated
		* and also scales the precision of the clipmaps depending on the scene.
		* 
		* To be on the safe side, we output -1 FirstLevel compared to what the full OrthoWidth would output. The InvProjectionMatrix outputs