r.TexelDebugging

r.TexelDebugging

#Overview

name: r.TexelDebugging

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.TexelDebugging is to enable a debugging feature for lightmap texels in the Unreal Engine editor. This setting is primarily used for the lighting system, specifically for debugging Lightmass, which is Unreal Engine’s global illumination solver.

This setting variable is mainly used in the Engine module, particularly in the lighting and lightmap subsystems. It’s referenced in the LightMap.cpp file, which is part of the core engine’s lighting functionality.

The value of this variable is set through a console variable (CVarTexelDebugging) in the engine. It’s initialized with a default value of 0, meaning the feature is disabled by default.

The associated variable CVarTexelDebugging interacts directly with r.TexelDebugging. They essentially represent the same setting, with CVarTexelDebugging being the actual TAutoConsoleVariable that controls the behavior.

Developers must be aware of several important points when using this variable:

  1. This debugging feature only works when Lightmass is compiled with ALLOW_LIGHTMAP_SAMPLE_DEBUGGING enabled.
  2. When enabled, it allows selecting lightmap texels by holding down the ‘T’ key and left-clicking in the editor.
  3. This feature is intended for debugging purposes and may have performance implications when enabled.

Best practices for using this variable include:

  1. Only enable it when actively debugging lightmap issues.
  2. Ensure that Lightmass is compiled with the necessary debug flag (ALLOW_LIGHTMAP_SAMPLE_DEBUGGING) for this feature to work.
  3. Disable the feature when not in use to avoid any potential performance impact.
  4. Use in conjunction with other lighting and lightmap debugging tools for comprehensive analysis.

Regarding the associated variable CVarTexelDebugging:

The purpose of CVarTexelDebugging is to provide a runtime-configurable way to enable or disable the texel debugging feature. It’s implemented as a TAutoConsoleVariable, which allows it to be changed during runtime through console commands.

This variable is used in the Engine module, specifically in the lightmap and lighting systems. It’s defined and used in the LightMap.cpp file.

The value of CVarTexelDebugging is set when the engine initializes the console variables, but it can be changed at runtime through console commands.

The IsTexelDebuggingEnabled() function directly uses CVarTexelDebugging to determine if the feature is enabled. This function likely serves as the primary interface for other parts of the engine to check if texel debugging is active.

Developers should be aware that changing this variable at runtime will immediately affect the texel debugging feature’s availability. They should also note that this variable is specific to the game thread, as indicated by the GetValueOnGameThread() call.

Best practices for using CVarTexelDebugging include:

  1. Use the console command system to toggle this feature on and off during development and debugging sessions.
  2. Be cautious about enabling this in shipping builds, as it’s primarily a development and debugging tool.
  3. When writing code that depends on this feature, always check its state using the IsTexelDebuggingEnabled() function rather than accessing the console variable directly.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:83

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarTexelDebugging(
	TEXT("r.TexelDebugging"),
	0,	
	TEXT("Whether T + Left mouse click in the editor selects lightmap texels for debugging Lightmass.  Lightmass must be recompiled with ALLOW_LIGHTMAP_SAMPLE_DEBUGGING enabled for this to work."),
	ECVF_Default);

static TAutoConsoleVariable<int32> CVarVirtualTexturedLightMaps(
	TEXT("r.VirtualTexturedLightmaps"),

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/Lighting.h:8

Scope: file

Source code excerpt:

 * Set to 1 to allow selecting lightmap texels by holding down T and left clicking in the editor,
 * And having debug information about that texel tracked during subsequent lighting rebuilds.
 * Have to enable 'r.TexelDebugging' in the editor as well.
 */
#define ALLOW_LIGHTMAP_SAMPLE_DEBUGGING	0

#if USE_EMBREE
#include <embree2/rtcore.h>
#include <embree2/rtcore_ray.h>
#else
typedef void* RTCDevice;
#endif

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:82

Scope: file

Source code excerpt:

#endif

static TAutoConsoleVariable<int32> CVarTexelDebugging(
	TEXT("r.TexelDebugging"),
	0,	
	TEXT("Whether T + Left mouse click in the editor selects lightmap texels for debugging Lightmass.  Lightmass must be recompiled with ALLOW_LIGHTMAP_SAMPLE_DEBUGGING enabled for this to work."),
	ECVF_Default);

static TAutoConsoleVariable<int32> CVarVirtualTexturedLightMaps(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:111

Scope (from outer to inner):

file
function     bool IsTexelDebuggingEnabled

Source code excerpt:

bool IsTexelDebuggingEnabled()
{
	return CVarTexelDebugging.GetValueOnGameThread() != 0;
}

#include "TextureLayout.h"

FLightMap::FLightMap()
	: bAllowHighQualityLightMaps(true)