r.PathTracing.LightGridVisualize

r.PathTracing.LightGridVisualize

#Overview

name: r.PathTracing.LightGridVisualize

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.PathTracing.LightGridVisualize is to enable a visualization mode for the light grid density in the path tracing system of Unreal Engine 5. This setting is primarily used for debugging and optimizing the light grid used in path tracing.

This setting variable is part of the rendering system, specifically the path tracing subsystem within Unreal Engine 5. It is defined and used in the Renderer module, as evidenced by its location in the “PathTracing.cpp” file.

The value of this variable is set through a console command, as it is defined using TAutoConsoleVariable. By default, it is set to 0 (off).

The variable interacts with the PathTracingData structure, specifically the VisualizeLightGrid member, as seen in the PreparePathTracingData function.

Developers should be aware that this variable has multiple visualization modes: 0: Off (default) 1: Light count heatmap (red indicates areas close to overflow) 2: Unique light lists visualization 3: Area light visualization

Best practices when using this variable include:

  1. Use it for debugging and optimizing light grid performance in path tracing.
  2. If the visualization shows many red areas in mode 1, consider increasing r.PathTracing.LightGridMaxCount.
  3. Use mode 2 to understand how lights are distributed across the grid.
  4. Use mode 3 to distinguish between point light sources and area light sources.

Regarding the associated variable CVarPathTracingLightGridVisualize:

This is the actual console variable object that controls the r.PathTracing.LightGridVisualize setting. It is of type TAutoConsoleVariable, which means it can be changed at runtime through console commands.

The purpose of CVarPathTracingLightGridVisualize is to provide a programmatic interface to control the light grid visualization mode in the path tracing system.

This variable is used in the Renderer module, specifically in the path tracing implementation.

Its value is set through the console command system of Unreal Engine, and it directly controls the behavior of the r.PathTracing.LightGridVisualize setting.

It interacts with the PathTracingData structure, where its value is queried and assigned to the VisualizeLightGrid member.

Developers should be aware that changes to this variable will immediately affect the visualization mode of the light grid in the path tracing system.

Best practices for using this variable include:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Consider exposing this setting in a debug UI for easier toggling during development.
  3. Remember to reset it to 0 (off) before shipping the game, as visualization modes can impact performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:273

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarPathTracingLightGridVisualize(
	TEXT("r.PathTracing.LightGridVisualize"),
	0,
	TEXT("Enables a visualization mode of the light grid density where red indicates the maximum light count has been reached (default = 0)\n")
	TEXT("0: off (default)\n")
	TEXT("1: light count heatmap (red - close to overflow, increase r.PathTracing.LightGridMaxCount)\n")
	TEXT("2: unique light lists (colors are a function of which lights occupy each cell)\n")
	TEXT("3: area light visualization (green: point light sources only, blue: some area light sources)\n"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:272

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingLightGridVisualize(
	TEXT("r.PathTracing.LightGridVisualize"),
	0,
	TEXT("Enables a visualization mode of the light grid density where red indicates the maximum light count has been reached (default = 0)\n")
	TEXT("0: off (default)\n")
	TEXT("1: light count heatmap (red - close to overflow, increase r.PathTracing.LightGridMaxCount)\n")
	TEXT("2: unique light lists (colors are a function of which lights occupy each cell)\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:637

Scope (from outer to inner):

file
function     static void PreparePathTracingData

Source code excerpt:

	PathTracingData.EnableCameraBackfaceCulling = CVarPathTracingEnableCameraBackfaceCulling.GetValueOnRenderThread();
	PathTracingData.SamplerType = CVarPathTracingSamplerType.GetValueOnRenderThread();
	PathTracingData.VisualizeLightGrid = CVarPathTracingLightGridVisualize.GetValueOnRenderThread();
	PathTracingData.VisualizeDecalGrid = CVarPathTracingDecalGridVisualize.GetValueOnRenderThread();
	PathTracingData.FilterWidth = CVarPathTracingFilterWidth.GetValueOnRenderThread();
	PathTracingData.CameraFocusDistance = 0;
	PathTracingData.CameraLensRadius = FVector2f::ZeroVector;
	if (ShowFlags.DepthOfField &&
		PPV.PathTracingEnableReferenceDOF &&