r.Shadow.Virtual.Visualize.LightName

r.Shadow.Virtual.Visualize.LightName

#Overview

name: r.Shadow.Virtual.Visualize.LightName

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.Visualize.LightName is to set the name of a specific light to visualize in the virtual shadow map system. This setting is primarily used for developer debugging and analysis in non-shipping builds of Unreal Engine 5.

This setting variable is part of Unreal Engine’s rendering system, specifically the virtual shadow map subsystem. It is used within the Renderer module, as evidenced by its location in the VirtualShadowMapArray.cpp file.

The value of this variable is set through the console command system, as it’s declared as an FAutoConsoleVariableRef. This means developers can change its value at runtime using console commands.

The r.Shadow.Virtual.Visualize.LightName setting interacts directly with the associated variable GVirtualShadowMapVisualizeLightName. They share the same value, with GVirtualShadowMapVisualizeLightName being the actual string that stores the light name.

Developers should be aware that this variable is intended for development and debugging purposes only. It should not be relied upon in shipping builds or for gameplay-critical features. Its primary use is to help isolate and visualize specific lights in the virtual shadow map system, which can be invaluable for debugging complex lighting setups.

Best practices when using this variable include:

  1. Only use it in development builds.
  2. Be specific with light names to avoid ambiguity.
  3. Remember to clear the value when done debugging to avoid unintended visualization effects.

Regarding the associated variable GVirtualShadowMapVisualizeLightName:

The purpose of GVirtualShadowMapVisualizeLightName is to store the actual string value of the light name to be visualized. It works in conjunction with r.Shadow.Virtual.Visualize.LightName.

This variable is used within the Renderer module, specifically in the virtual shadow map system. It’s primarily used in the FVirtualShadowMapVisualizeLightSearch::CheckLight function to determine if a given light should be visualized.

The value of GVirtualShadowMapVisualizeLightName is set indirectly through r.Shadow.Virtual.Visualize.LightName console command.

It interacts with the CheckLightName variable in the CheckLight function, where it’s used for exact and partial name matching.

Developers should be aware that this variable is used for both exact and partial name matching. This means that setting a partial name could potentially visualize multiple lights if their names contain the specified string.

Best practices for using GVirtualShadowMapVisualizeLightName include:

  1. Use unique and specific light names in your project to make debugging easier.
  2. Be aware of the partial matching feature and use it intentionally when needed.
  3. Clear this variable (by clearing r.Shadow.Virtual.Visualize.LightName) after debugging to ensure normal rendering behavior.

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

Scope: file

Source code excerpt:

FString GVirtualShadowMapVisualizeLightName;
FAutoConsoleVariableRef CVarVisualizeLightName(
	TEXT("r.Shadow.Virtual.Visualize.LightName"),
	GVirtualShadowMapVisualizeLightName,
	TEXT("Sets the name of a specific light to visualize (for developer use in non-shipping builds)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarVisualizeLayout(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

FString GVirtualShadowMapVisualizeLightName;
FAutoConsoleVariableRef CVarVisualizeLightName(
	TEXT("r.Shadow.Virtual.Visualize.LightName"),
	GVirtualShadowMapVisualizeLightName,
	TEXT("Sets the name of a specific light to visualize (for developer use in non-shipping builds)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarVisualizeLayout(
	TEXT("r.Shadow.Virtual.Visualize.Layout"),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapVisualizeLightSearch::CheckLight

Source code excerpt:

	SortKey CheckKey;
	CheckKey.Packed = 0;
	CheckKey.Fields.bExactNameMatch = (CheckLightName == GVirtualShadowMapVisualizeLightName);
	CheckKey.Fields.bPartialNameMatch = CheckKey.Fields.bExactNameMatch || CheckLightName.Contains(GVirtualShadowMapVisualizeLightName);
	CheckKey.Fields.bSelected = Component->IsSelected();
	CheckKey.Fields.bOwnerSelected = Component->IsOwnerSelected();
	CheckKey.Fields.bDirectionalLight = CheckProxy->GetLightType() == LightType_Directional;
	CheckKey.Fields.bExists = 1;

	if (CheckKey.Packed > FoundKey.Packed)		//-V547