r.IESAtlas.Debug

r.IESAtlas.Debug

#Overview

name: r.IESAtlas.Debug

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.IESAtlas.Debug is to enable debug information for the IES (Illuminating Engineering Society) atlas in Unreal Engine’s rendering system. This setting is primarily used for diagnostic and development purposes within the lighting and rendering subsystems.

This setting variable is utilized by the Renderer module of Unreal Engine, specifically within the IES texture management system. It’s referenced in the IESTextureManager.cpp file, which is responsible for handling IES light profiles and their atlas textures.

The value of this variable is set through the console variable system (CVarIESTextureDebug). It’s initialized with a default value of 0, meaning the debug information is disabled by default. Users can change this value at runtime using console commands.

The associated variable CVarIESTextureDebug directly interacts with r.IESAtlas.Debug. They share the same value and purpose, with CVarIESTextureDebug being the actual console variable object used in the code.

Developers should be aware that enabling this debug information may have performance implications, as it adds additional rendering passes and visual output. It should primarily be used during development and debugging phases, not in production builds.

Best practices for using this variable include:

  1. Only enable it when actively debugging IES atlas-related issues.
  2. Be mindful of potential performance impact when enabled.
  3. Use in conjunction with other rendering debug tools for comprehensive analysis.
  4. Disable the debug output before creating production builds.

Regarding the associated variable CVarIESTextureDebug:

The purpose of CVarIESTextureDebug is to provide programmatic access to the r.IESAtlas.Debug setting within the C++ code. It allows the engine to check the current debug state and conditionally execute debug-related code.

This variable is used within the Renderer module, specifically in the IES texture management system. It’s checked in the AddDebugPass function to determine whether to add an additional debug rendering pass.

The value of CVarIESTextureDebug is set through the console variable system, initialized with the same parameters as r.IESAtlas.Debug.

CVarIESTextureDebug directly interacts with r.IESAtlas.Debug, essentially serving as its in-code representation.

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it’s safe to access from the render thread. However, they should still use the appropriate getter method (GetValueOnRenderThread()) when accessing it from render thread code.

Best practices for using CVarIESTextureDebug include:

  1. Always use the appropriate getter method based on the current thread context.
  2. Consider caching the value if it’s accessed frequently in performance-critical code paths.
  3. Use it to conditionally compile or execute debug code, ensuring minimal impact on release builds.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:38

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarIESTextureDebug(
	TEXT("r.IESAtlas.Debug"),
	0,
	TEXT("Enable IES atlas debug information."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarIESForceUpdate(
	TEXT("r.IESAtlas.ForceUpdate"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:37

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarIESTextureDebug(
	TEXT("r.IESAtlas.Debug"),
	0,
	TEXT("Enable IES atlas debug information."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarIESForceUpdate(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/IESTextureManager.cpp:609

Scope (from outer to inner):

file
namespace    IESAtlas
function     void AddDebugPass

Source code excerpt:

void AddDebugPass(FRDGBuilder& GraphBuilder, const FViewInfo& View, FRDGTextureRef OutputTexture)
{
	if (CVarIESTextureDebug.GetValueOnRenderThread() > 0 && ShaderPrint::IsSupported(View.Family->GetShaderPlatform()))
	{
		if (FRDGTextureRef DebugOutput = AddIESDebugPass(GraphBuilder, View, OutputTexture->Desc))
		{
			// Debug output is blend on top of the SceneColor/OutputTexture, as debug pass is a CS pass, and SceneColor/OutputTexture might not have a UAV flag
			FCopyRectPS::FParameters* Parameters = GraphBuilder.AllocParameters<FCopyRectPS::FParameters>();
			Parameters->InputTexture = DebugOutput;