r.Lumen.Visualize.RayTracingGroups

r.Lumen.Visualize.RayTracingGroups

#Overview

name: r.Lumen.Visualize.RayTracingGroups

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Visualize.RayTracingGroups is to provide a visualization tool for ray tracing groups in the Lumen global illumination system of Unreal Engine 5. This setting is primarily used for debugging and performance analysis of the Lumen rendering system.

The Unreal Engine subsystem that relies on this setting variable is the Lumen rendering system, which is part of the core rendering module in Unreal Engine 5.

The value of this variable is set through the console variable system in Unreal Engine. It can be changed at runtime using console commands or through configuration files.

This variable interacts directly with its associated variable GVisualizeLumenRayTracingGroups. They share the same value, with r.Lumen.Visualize.RayTracingGroups being the console-accessible name and GVisualizeLumenRayTracingGroups being the C++ variable used in the code.

Developers must be aware that this variable is intended for visualization purposes only and should not be used in production builds. It’s a debugging tool that can impact performance when enabled.

Best practices for using this variable include:

  1. Use it only during development and debugging phases.
  2. Be aware of the performance impact when enabled.
  3. Use in conjunction with r.Lumen.Visualize.CardPlacementDistance to control the visualization distance.

Regarding the associated variable GVisualizeLumenRayTracingGroups:

The purpose of GVisualizeLumenRayTracingGroups is to serve as the internal C++ representation of the r.Lumen.Visualize.RayTracingGroups console variable.

This variable is used directly in the Lumen visualization code within the rendering module of Unreal Engine 5.

The value of this variable is set through the FAutoConsoleVariableRef system, which links it to the console variable r.Lumen.Visualize.RayTracingGroups.

GVisualizeLumenRayTracingGroups interacts with other variables in the visualization system, such as GVisualizeLumenCardPlacementDistance.

Developers should be aware that this variable controls the level of visualization: 0 - disable visualization 1 - visualize all groups 2 - visualize only groups with a single instance

Best practices for using this variable include:

  1. Use it in conjunction with other Lumen visualization tools for comprehensive debugging.
  2. Be mindful of the performance impact when enabled, especially when visualizing all groups.
  3. Use the appropriate visualization level (1 or 2) based on the specific debugging needs.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:215

Scope: file

Source code excerpt:

int32 GVisualizeLumenRayTracingGroups = 0;
FAutoConsoleVariableRef CVarVisualizeLumenRayTracingGroups(
	TEXT("r.Lumen.Visualize.RayTracingGroups"),
	GVisualizeLumenRayTracingGroups,
	TEXT("Visualize bounds for ray tracing groups. Control visualization distance using r.Lumen.Visualize.CardPlacementDistance.\n")
	TEXT("0 - disable\n")
	TEXT("1 - all groups\n")
	TEXT("2 - groups with a single instance"),
	ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:213

Scope: file

Source code excerpt:

);

int32 GVisualizeLumenRayTracingGroups = 0;
FAutoConsoleVariableRef CVarVisualizeLumenRayTracingGroups(
	TEXT("r.Lumen.Visualize.RayTracingGroups"),
	GVisualizeLumenRayTracingGroups,
	TEXT("Visualize bounds for ray tracing groups. Control visualization distance using r.Lumen.Visualize.CardPlacementDistance.\n")
	TEXT("0 - disable\n")
	TEXT("1 - all groups\n")
	TEXT("2 - groups with a single instance"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:1104

Scope (from outer to inner):

file
function     void VisualizeRayTracingGroups

Source code excerpt:

void VisualizeRayTracingGroups(const FViewInfo& View, const FLumenSceneData& LumenSceneData, FViewElementPDI& ViewPDI)
{
	if (GVisualizeLumenRayTracingGroups == 0)
	{
		return;
	}

	FConvexVolume ViewFrustum;
	GetViewFrustumBounds(ViewFrustum, View.ViewMatrices.GetViewProjectionMatrix(), true);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:1114

Scope (from outer to inner):

file
function     void VisualizeRayTracingGroups

Source code excerpt:

	for (const FLumenPrimitiveGroup& PrimitiveGroup : LumenSceneData.PrimitiveGroups)
	{
		if ((GVisualizeLumenRayTracingGroups != 2 || !PrimitiveGroup.HasMergedInstances())
			&& PrimitiveGroup.HasMergedPrimitives()
			&& PrimitiveGroup.WorldSpaceBoundingBox.ComputeSquaredDistanceToPoint((FVector3f)View.ViewMatrices.GetViewOrigin()) < GVisualizeLumenCardPlacementDistance * GVisualizeLumenCardPlacementDistance
			&& ViewFrustum.IntersectBox((FVector)PrimitiveGroup.WorldSpaceBoundingBox.GetCenter(), (FVector)PrimitiveGroup.WorldSpaceBoundingBox.GetExtent()))
		{
			const uint32 GroupIdHash = GetTypeHash(PrimitiveGroup.RayTracingGroupMapElementId.GetIndex());
			const uint8 DepthPriority = SDPG_World;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:1337

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::LumenScenePDIVisualization

Source code excerpt:

	{
		if (GVisualizeLumenCardPlacement != 0
			|| GVisualizeLumenRayTracingGroups != 0
			|| GVisualizeLumenCardGenerationCluster != 0
			|| GVisualizeLumenCardGenerationSurfels != 0)
		{
			FViewElementPDI ViewPDI(&Views[0], nullptr, &Views[0].DynamicPrimitiveCollector);
			VisualizeRayTracingGroups(Views[0], LumenSceneData, ViewPDI);
			VisualizeCardPlacement(Allocator, Views[0], LumenSceneData, ViewPDI);