r.Shadow.Virtual.ShowLightDrawEvents

r.Shadow.Virtual.ShowLightDrawEvents

#Overview

name: r.Shadow.Virtual.ShowLightDrawEvents

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

• type: Var
• help: Enable Virtual Shadow Maps per-light draw events - may affect performance especially when there are many small lights in the scene.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.ShowLightDrawEvents is to enable or disable the display of per-light draw events for Virtual Shadow Maps in Unreal Engine 5’s rendering system.

This setting variable is primarily used in the rendering system, specifically in the Virtual Shadow Maps subsystem. It’s part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

This variable interacts directly with GVSMShowLightDrawEvents, which is the actual integer variable that stores the setting’s value. They share the same value, with r.Shadow.Virtual.ShowLightDrawEvents being the console-accessible name and GVSMShowLightDrawEvents being the C++ variable used in the code.

Developers should be aware that enabling this variable may affect performance, especially in scenes with many small lights. This is because it adds additional draw events for each light, which can increase the overhead of rendering.

Best practices when using this variable include:

1. Use it primarily for debugging and profiling purposes.
2. Be cautious about enabling it in performance-critical scenarios or in scenes with many lights.
3. Consider disabling it for final builds or when not actively debugging shadow-related issues.

Regarding the associated variable GVSMShowLightDrawEvents:

The purpose of GVSMShowLightDrawEvents is to store the actual integer value that determines whether Virtual Shadow Maps per-light draw events are enabled or disabled.

This variable is used directly in the rendering code to conditionally execute draw events. It’s checked in performance-sensitive areas, so its value can have a direct impact on rendering performance.

The value of GVSMShowLightDrawEvents is set through the r.Shadow.Virtual.ShowLightDrawEvents console variable. It’s initialized to 0 (disabled) by default.

GVSMShowLightDrawEvents interacts primarily with the r.Shadow.Virtual.ShowLightDrawEvents console variable, as they share the same value.

Developers should be aware that this variable is used in conditional statements within rendering code, so changing its value will directly affect the execution of certain draw events.

Best practices for GVSMShowLightDrawEvents include:

1. Avoid modifying this variable directly in C++ code; instead, use the r.Shadow.Virtual.ShowLightDrawEvents console variable to change its value.
2. Be mindful of its performance implications when enabled, especially in scenes with many lights.
3. Use it in conjunction with profiling tools to understand the impact of Virtual Shadow Maps on rendering performance.

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

Scope: file

Source code excerpt:

int32 GVSMShowLightDrawEvents = 0;
FAutoConsoleVariableRef CVarVSMShowLightDrawEvents(
	TEXT("r.Shadow.Virtual.ShowLightDrawEvents"),
	GVSMShowLightDrawEvents,
	TEXT("Enable Virtual Shadow Maps per-light draw events - may affect performance especially when there are many small lights in the scene."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarEnableVirtualShadowMaps(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

extern TAutoConsoleVariable<float> CVarNaniteMinPixelsPerEdgeHW;

int32 GVSMShowLightDrawEvents = 0;
FAutoConsoleVariableRef CVarVSMShowLightDrawEvents(
	TEXT("r.Shadow.Virtual.ShowLightDrawEvents"),
	GVSMShowLightDrawEvents,
	TEXT("Enable Virtual Shadow Maps per-light draw events - may affect performance especially when there are many small lights in the scene."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarEnableVirtualShadowMaps(
	TEXT("r.Shadow.Virtual.Enable"),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::RenderVirtualShadowMapsNonNanite
lambda-function

Source code excerpt:

#if WITH_PROFILEGPU
							FString LightNameWithLevel;
							if (GVSMShowLightDrawEvents != 0)
							{
								FSceneRenderer::GetLightNameForDrawEvent(ProjectedShadowInfo->GetLightSceneInfo().Proxy, LightNameWithLevel);
							}
							SCOPED_CONDITIONAL_DRAW_EVENTF(RHICmdList, BatchedNonNanite, GVSMShowLightDrawEvents != 0, TEXT("%s"), *LightNameWithLevel);
#endif
							MeshCommandPass.DispatchDraw(nullptr, RHICmdList, &InstanceCullingDrawParams);
						}

						RHICmdList.EndRenderPass();
					});