r.Shadow.Virtual.ForcePerLightShadowMaskClear

r.Shadow.Virtual.ForcePerLightShadowMaskClear

#Overview

name: r.Shadow.Virtual.ForcePerLightShadowMaskClear

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

• type: Var
• help: For debugging purposes. When enabled, the shadow mask texture is cleared before the projection pass writes to it. Projection pass writes all relevant pixels, so clearing should be unnecessary.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.ForcePerLightShadowMaskClear is for debugging the virtual shadow map system in Unreal Engine 5’s rendering pipeline. Specifically, it controls whether the shadow mask texture should be cleared before the projection pass writes to it.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the virtual shadow map subsystem. Based on the callsites, it’s utilized in the VirtualShadowMapProjection.cpp file, which is part of the virtual shadow mapping implementation.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning it’s disabled by default.

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

Developers must be aware that enabling this variable (setting it to a non-zero value) will force the shadow mask texture to be cleared before the projection pass, which is typically unnecessary as the projection pass writes all relevant pixels. This can impact performance and is intended for debugging purposes only.

Best practices when using this variable include:

1. Keep it disabled (set to 0) in production builds for optimal performance.
2. Use it only when debugging issues related to the virtual shadow map projection pass.
3. Be aware of potential performance impact when enabled.
4. Reset it to 0 after debugging to ensure it doesn’t affect normal operation.

Regarding the associated variable CVarForcePerLightShadowMaskClear:

The purpose of CVarForcePerLightShadowMaskClear is identical to r.Shadow.Virtual.ForcePerLightShadowMaskClear. It’s the internal representation of the console variable in the C++ code.

This variable is used in the Renderer module, specifically in the virtual shadow map projection system. It’s checked in the CreateShadowMaskTexture function to determine whether to clear the shadow mask texture.

The value of CVarForcePerLightShadowMaskClear is set through the console variable system, just like r.Shadow.Virtual.ForcePerLightShadowMaskClear.

It directly interacts with r.Shadow.Virtual.ForcePerLightShadowMaskClear, as they represent the same setting.

Developers should be aware that this variable is accessed on the render thread (GetValueOnRenderThread()), which is important for thread safety in the rendering pipeline.

Best practices for CVarForcePerLightShadowMaskClear are the same as for r.Shadow.Virtual.ForcePerLightShadowMaskClear, as they are effectively the same variable.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapProjection.cpp:140

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarForcePerLightShadowMaskClear(
	TEXT( "r.Shadow.Virtual.ForcePerLightShadowMaskClear" ),
	0,
	TEXT( "For debugging purposes. When enabled, the shadow mask texture is cleared before the projection pass writes to it. Projection pass writes all relevant pixels, so clearing should be unnecessary." ),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarVSMTranslucentQuality(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapProjection.cpp:139

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarForcePerLightShadowMaskClear(
	TEXT( "r.Shadow.Virtual.ForcePerLightShadowMaskClear" ),
	0,
	TEXT( "For debugging purposes. When enabled, the shadow mask texture is cleared before the projection pass writes to it. Projection pass writes all relevant pixels, so clearing should be unnecessary." ),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapProjection.cpp:509

Scope (from outer to inner):

file
function     static FRDGTextureRef CreateShadowMaskTexture

Source code excerpt:

	// NOTE: Projection pass writes all relevant pixels, so should not need to clear here
	if (CVarForcePerLightShadowMaskClear.GetValueOnRenderThread() != 0)
	{
		AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(Texture), ClearColor);
	}

	return Texture;
}