r.Shadow.Virtual.PageMarkingPixelStrideX

r.Shadow.Virtual.PageMarkingPixelStrideX

#Overview

name: r.Shadow.Virtual.PageMarkingPixelStrideX

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.PageMarkingPixelStrideX is to control the pixel stride used during page marking in the Virtual Shadow Map (VSM) system of Unreal Engine 5’s rendering pipeline.

This setting variable is primarily used by the rendering system, specifically the Virtual Shadow Map subsystem. Based on the callsites, it is utilized in the VirtualShadowMapArray.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVarVirtualShadowMapPageMarkingPixelStrideX) with a default value of 2. It can be adjusted at runtime using console commands or through project settings.

This variable interacts with a similar variable called CVarVirtualShadowMapPageMarkingPixelStrideY, which controls the vertical stride. Together, they determine the pixel stride used in page marking.

Developers must be aware that this variable affects the performance-quality tradeoff in shadow rendering. Increasing the value reduces computational costs but may introduce artifacts due to missing shadow map pages.

Best practices when using this variable include:

  1. Keep the value low (close to 1) for highest quality shadows, especially in scenes with fine details.
  2. Increase the value carefully to improve performance, monitoring for any introduced artifacts.
  3. Consider the nature of your scene when adjusting this value - scenes with large, soft shadows may tolerate higher values better than scenes with intricate, hard shadows.
  4. Test thoroughly across different hardware configurations to ensure a good balance between performance and quality.

Regarding the associated variable CVarVirtualShadowMapPageMarkingPixelStrideX:

This is the actual console variable that controls the r.Shadow.Virtual.PageMarkingPixelStrideX setting. It is defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime.

The purpose of this variable is the same as r.Shadow.Virtual.PageMarkingPixelStrideX - to control the horizontal pixel stride in VSM page marking.

It is used in the FVirtualShadowMapArray::BuildPageAllocations function to determine the PixelStride for page marking operations.

When using this variable, developers should note that:

  1. The value is clamped between 1 and 128 when used, ensuring it stays within a reasonable range.
  2. It’s accessed using GetValueOnRenderThread(), indicating it’s designed to be safely read from the render thread.
  3. Changes to this variable will take effect in real-time, allowing for dynamic adjustments during development or even in shipping builds if exposed to end-users.

Best practices for CVarVirtualShadowMapPageMarkingPixelStrideX align with those of r.Shadow.Virtual.PageMarkingPixelStrideX, focusing on finding the optimal balance between performance and shadow quality for your specific use case.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarVirtualShadowMapPageMarkingPixelStrideX(
	TEXT("r.Shadow.Virtual.PageMarkingPixelStrideX"),
	2,
	TEXT("During page marking, instead of testing every screen pixel, test every Nth pixel.\n")
	TEXT("Page marking from screen pixels is used to determine which VSM pages are seen from the camera and need to be rendered.\n")
	TEXT("Increasing this value reduces page-marking costs, but could introduce artifacts due to missing pages.\n")
	TEXT("With sufficiently low values, it is likely a neighbouring pixel will mark the required page anyway."),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarVirtualShadowMapPageMarkingPixelStrideX(
	TEXT("r.Shadow.Virtual.PageMarkingPixelStrideX"),
	2,
	TEXT("During page marking, instead of testing every screen pixel, test every Nth pixel.\n")
	TEXT("Page marking from screen pixels is used to determine which VSM pages are seen from the camera and need to be rendered.\n")
	TEXT("Increasing this value reduces page-marking costs, but could introduce artifacts due to missing pages.\n")
	TEXT("With sufficiently low values, it is likely a neighbouring pixel will mark the required page anyway."),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations
lambda-function

Source code excerpt:


					const FIntPoint PixelStride(
						FMath::Clamp(CVarVirtualShadowMapPageMarkingPixelStrideX.GetValueOnRenderThread(), 1, 128),
						FMath::Clamp(CVarVirtualShadowMapPageMarkingPixelStrideY.GetValueOnRenderThread(), 1, 128));
					
					// If Lumen has valid front layer history data use it, otherwise use same frame front layer depth
					bool bFrontLayerEnabled = false;
					if (IsVSMTranslucentHighQualityEnabled())
					{