r.Forward.LightGridDebug

r.Forward.LightGridDebug

#Overview

name: r.Forward.LightGridDebug

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Forward.LightGridDebug is to enable visual debugging of the forward light grid system in Unreal Engine 5. It allows developers to display on-screen information about culled lights per tile in the rendering process.

This setting variable is primarily used in the rendering system, specifically in the forward lighting pipeline. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system. It is defined as an FAutoConsoleVariableRef, which allows it to be changed at runtime through console commands or configuration files.

The r.Forward.LightGridDebug variable interacts directly with the GForwardLightGridDebug variable. They share the same value, with GForwardLightGridDebug being the actual int32 variable used in the C++ code.

Developers must be aware that this variable has four possible values: 0: Off (default) 1: Show light count on the depth buffer 2: Show max light count per tile, accounting for each slice except the last one 3: Show max light count per tile, accounting for all slices including the last one

When using this variable, developers should consider the following best practices:

  1. Use it only for debugging purposes, as it may impact performance when enabled.
  2. Be mindful of the different visualization modes and choose the appropriate one for the specific debugging task.
  3. Remember to disable it (set to 0) in production builds or when not actively debugging the light grid system.

Regarding the associated variable GForwardLightGridDebug:

The purpose of GForwardLightGridDebug is to store the actual integer value of the debug mode for the forward light grid system. It is used internally in the C++ code to control the behavior of the light grid visualization.

This variable is used in the Renderer module, specifically in the LightGridInjection.cpp file. It is closely tied to the forward rendering pipeline and light culling system.

The value of GForwardLightGridDebug is set through the r.Forward.LightGridDebug console variable. They share the same value, with GForwardLightGridDebug being the actual int32 variable used in the C++ code.

GForwardLightGridDebug interacts directly with the r.Forward.LightGridDebug console variable. It is also used in functions like ShouldVisualizeLightGrid() to determine if the light grid visualization should be enabled.

Developers should be aware that modifying GForwardLightGridDebug directly in code is not recommended. Instead, they should use the r.Forward.LightGridDebug console variable to change its value.

Best practices for using GForwardLightGridDebug include:

  1. Avoid modifying it directly in code; use the console variable system instead.
  2. Use it in conditional statements to enable or disable light grid visualization features.
  3. Be cautious when using it in performance-critical code paths, as checking its value may introduce minor overhead.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:52

Scope: file

Source code excerpt:

int32 GForwardLightGridDebug = 0;
FAutoConsoleVariableRef CVarLightGridDebug(
	TEXT("r.Forward.LightGridDebug"),
	GForwardLightGridDebug,
	TEXT("Whether to display on screen culledlight per tile.\n")
	TEXT(" 0: off (default)\n")
	TEXT(" 1: on - showing light count onto the depth buffer\n")
	TEXT(" 2: on - showing max light count per tile accoung for each slice but the last one (culling there is too conservative)\n")
	TEXT(" 3: on - showing max light count per tile accoung for each slice and the last one \n"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:50

Scope: file

Source code excerpt:

);

int32 GForwardLightGridDebug = 0;
FAutoConsoleVariableRef CVarLightGridDebug(
	TEXT("r.Forward.LightGridDebug"),
	GForwardLightGridDebug,
	TEXT("Whether to display on screen culledlight per tile.\n")
	TEXT(" 0: off (default)\n")
	TEXT(" 1: on - showing light count onto the depth buffer\n")
	TEXT(" 2: on - showing max light count per tile accoung for each slice but the last one (culling there is too conservative)\n")
	TEXT(" 3: on - showing max light count per tile accoung for each slice and the last one \n"),
	ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:102

Scope (from outer to inner):

file
function     bool ShouldVisualizeLightGrid

Source code excerpt:

bool ShouldVisualizeLightGrid()
{
	return GForwardLightGridDebug > 0;
}

// If this is changed, the LIGHT_GRID_USES_16BIT_BUFFERS define from LightGridCommon.ush should also be updated.
bool LightGridUses16BitBuffers(EShaderPlatform Platform)
{
	// CulledLightDataGrid, is typically 16bit elements to save on memory and bandwidth. So to not introduce any regressions it will stay as texel buffer on all platforms, except mobile and Metal (which does not support type conversions).

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:1149

Scope (from outer to inner):

file
function     FScreenPassTexture AddVisualizeLightGridPass

Source code excerpt:

		PassParameters->MiniFontTexture = GetMiniFontTexture();
		PassParameters->RenderTargets[0] = FRenderTargetBinding(ScreenPassSceneColor.Texture, ERenderTargetLoadAction::ELoad);
		PassParameters->DebugMode = GForwardLightGridDebug;

		FRHIBlendState* PreMultipliedColorTransmittanceBlend = TStaticBlendState<CW_RGB, BO_Add, BF_One, BF_SourceAlpha, BO_Add, BF_Zero, BF_One>::GetRHI();

		FPixelShaderUtils::AddFullscreenPass<FDebugLightGridPS>(GraphBuilder, View.ShaderMap, RDG_EVENT_NAME("DebugLightGridCS"), PixelShader, PassParameters,
			ScreenPassSceneColor.ViewRect, PreMultipliedColorTransmittanceBlend);
	}