r.Shadow.Virtual.MarkPixelPagesMipModeLocal

r.Shadow.Virtual.MarkPixelPagesMipModeLocal

#Overview

name: r.Shadow.Virtual.MarkPixelPagesMipModeLocal

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

• type: Var
• help: When enabled, this uses a subset of mips to reduce instance duplication in VSMs. Will result in better performance but a harsher falloff on mip transitions.\n 0 - Disabled: Use all 8 mips\n 1 - Quality Mode: Use 4 higher res mips (16k, 4k, 1k, 256)\n 2 - Performance Mode: Use 4 lower res mips (8k, 2k, 512, 128)\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.MarkPixelPagesMipModeLocal is to control the mip level selection for Virtual Shadow Maps (VSMs) in Unreal Engine’s rendering system. It allows developers to optimize performance and visual quality by adjusting the number and resolution of mip levels used in VSMs.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the Virtual Shadow Maps subsystem. It is referenced in the VirtualShadowMapArray.cpp file, which is part of the core rendering pipeline.

The value of this variable is set through a console variable (CVarMarkPixelPagesMipModeLocal) defined in the C++ code. It can be modified at runtime or through configuration files.

The associated variable CVarMarkPixelPagesMipModeLocal directly interacts with r.Shadow.Virtual.MarkPixelPagesMipModeLocal. They share the same value and purpose.

Developers must be aware of the following when using this variable:

1. It affects the performance and visual quality of Virtual Shadow Maps.
2. There are three modes available: Disabled (0), Quality Mode (1), and Performance Mode (2).
3. Changing this setting may result in a trade-off between performance and shadow quality.

Best practices when using this variable include:

1. Use the Disabled mode (0) for highest quality shadows if performance allows.
2. Use Quality Mode (1) for a balance between performance and quality.
3. Use Performance Mode (2) when prioritizing performance over shadow quality.
4. Test thoroughly with different settings to find the optimal balance for your specific project.

Regarding the associated variable CVarMarkPixelPagesMipModeLocal:

• It is an internal representation of the r.Shadow.Virtual.MarkPixelPagesMipModeLocal setting.
• It is used directly in the rendering code to determine the mip mode for Virtual Shadow Maps.
• The value is retrieved using GetValueOnRenderThread() method, ensuring thread-safe access.
• Developers should not manipulate this variable directly but instead use the r.Shadow.Virtual.MarkPixelPagesMipModeLocal console command to change the setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:112

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarMarkPixelPagesMipModeLocal(
	TEXT("r.Shadow.Virtual.MarkPixelPagesMipModeLocal"),
	0,
	TEXT("When enabled, this uses a subset of mips to reduce instance duplication in VSMs. Will result in better performance but a harsher falloff on mip transitions.\n")
	TEXT(" 0 - Disabled: Use all 8 mips\n")
	TEXT(" 1 - Quality Mode: Use 4 higher res mips (16k, 4k, 1k, 256)\n")
	TEXT(" 2 - Performance Mode: Use 4 lower res mips (8k, 2k, 512, 128)\n"),
	ECVF_RenderThreadSafe | ECVF_Scalability

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:111

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarMarkPixelPagesMipModeLocal(
	TEXT("r.Shadow.Virtual.MarkPixelPagesMipModeLocal"),
	0,
	TEXT("When enabled, this uses a subset of mips to reduce instance duplication in VSMs. Will result in better performance but a harsher falloff on mip transitions.\n")
	TEXT(" 0 - Disabled: Use all 8 mips\n")
	TEXT(" 1 - Quality Mode: Use 4 higher res mips (16k, 4k, 1k, 256)\n")
	TEXT(" 2 - Performance Mode: Use 4 lower res mips (8k, 2k, 512, 128)\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:1531

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations
lambda-function

Source code excerpt:

					PassParameters->Substrate = Substrate::BindSubstrateGlobalUniformParameters(View);
					PassParameters->PixelStride = PixelStride;
					PassParameters->MipModeLocal = CVarMarkPixelPagesMipModeLocal.GetValueOnRenderThread();
					
					const FIntPoint StridedPixelSize = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), PixelStride);
					// Note: we use the tile size defined by the water as the group-size - this is needed because the tile mask testing code relies on the size being the same to scalarize efficiently.
					const FIntPoint GridSize = FIntPoint::DivideAndRoundUp(StridedPixelSize, SLW_TILE_SIZE_XY);

					if (InputType == EVirtualShadowMapProjectionInputType::HairStrands)