r.Mobile.ShadowmapRoundUpToPowerOfTwo

r.Mobile.ShadowmapRoundUpToPowerOfTwo

#Overview

name: r.Mobile.ShadowmapRoundUpToPowerOfTwo

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

• type: Var
• help: Round the shadow map up to power of two on mobile platform, in case there is any compatibility issue.\n 0: Disable (Default)\n 1: Enabled

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Mobile.ShadowmapRoundUpToPowerOfTwo is to control whether shadow map dimensions are rounded up to the nearest power of two on mobile platforms. This setting is part of the rendering system, specifically for shadow rendering on mobile devices.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the shadow setup and allocation process for mobile platforms.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with a default value of 0 (disabled). Developers can change this value at runtime or in configuration files.

The associated variable CVarMobileShadowmapRoundUpToPowerOfTwo directly interacts with r.Mobile.ShadowmapRoundUpToPowerOfTwo. They share the same value and purpose.

Developers must be aware that enabling this variable (setting it to 1) will cause the shadow map dimensions to be rounded up to the nearest power of two. This can potentially increase memory usage and affect performance, but it may solve compatibility issues on some mobile devices.

Best practices when using this variable include:

1. Leave it disabled (0) by default unless specific compatibility issues are encountered.
2. Test thoroughly on target mobile devices when enabled to ensure it solves the intended problem without introducing significant performance penalties.
3. Consider the impact on memory usage, especially on devices with limited resources.

Regarding the associated variable CVarMobileShadowmapRoundUpToPowerOfTwo:

• Its purpose is identical to r.Mobile.ShadowmapRoundUpToPowerOfTwo.
• It’s used in the same Renderer module, specifically in the FSceneRenderer::AllocateMobileCSMAndSpotLightShadowDepthTargets function.
• Its value is set and accessed using the GetValueOnRenderThread() method.
• When enabled, it modifies the WholeSceneAtlasSize by rounding up its dimensions to the nearest power of two using FMath::CeilLogTwo.
• Developers should be aware that this variable directly affects the size of shadow maps, which can impact both rendering quality and performance.
• Best practices include carefully monitoring performance and memory usage when enabling this option, and only using it when necessary to resolve specific compatibility issues on mobile platforms.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:354

Scope: file

Source code excerpt:

/** Whether to round the shadow map up to power of two on mobile platform. */
static TAutoConsoleVariable<int32> CVarMobileShadowmapRoundUpToPowerOfTwo(
	TEXT("r.Mobile.ShadowmapRoundUpToPowerOfTwo"),
	0,
	TEXT("Round the shadow map up to power of two on mobile platform, in case there is any compatibility issue.\n")
	TEXT(" 0: Disable (Default)\n")
	TEXT(" 1: Enabled"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:353

Scope: file

Source code excerpt:

/** Whether to round the shadow map up to power of two on mobile platform. */
static TAutoConsoleVariable<int32> CVarMobileShadowmapRoundUpToPowerOfTwo(
	TEXT("r.Mobile.ShadowmapRoundUpToPowerOfTwo"),
	0,
	TEXT("Round the shadow map up to power of two on mobile platform, in case there is any compatibility issue.\n")
	TEXT(" 0: Disable (Default)\n")
	TEXT(" 1: Enabled"),
	ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:6658

Scope (from outer to inner):

file
function     void FSceneRenderer::AllocateMobileCSMAndSpotLightShadowDepthTargets

Source code excerpt:

			FIntPoint WholeSceneAtlasSize(MobileCSMAndSpotLightShadowLayout.TextureLayout.GetSizeX(), MobileCSMAndSpotLightShadowLayout.TextureLayout.GetSizeY());

			if (CVarMobileShadowmapRoundUpToPowerOfTwo.GetValueOnRenderThread() != 0)
			{
				WholeSceneAtlasSize.X = 1 << FMath::CeilLogTwo(WholeSceneAtlasSize.X);
				WholeSceneAtlasSize.Y = 1 << FMath::CeilLogTwo(WholeSceneAtlasSize.Y);
			}

			FPooledRenderTargetDesc WholeSceneShadowMapDesc2D(FPooledRenderTargetDesc::Create2DDesc(WholeSceneAtlasSize, PF_ShadowDepth, FClearValueBinding::DepthOne, TexCreate_None, TexCreate_DepthStencilTargetable | TexCreate_ShaderResource, false));