bUseDebugMaterial

bUseDebugMaterial

#Overview

name: bUseDebugMaterial

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bUseDebugMaterial is to provide a debugging option for the static lighting system in Unreal Engine 5. It allows developers to override the normal materials associated with meshes and use a debug material instead.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for static lighting calculations in Unreal Engine. It’s referenced in both the editor-side code (UnrealEd module) and the standalone Lightmass program.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.StaticLightingMaterial” section with the key “bUseDebugMaterial”.

bUseDebugMaterial interacts with other variables, notably:

  1. DebugDiffuse: A FLinearColor value that defines the diffuse color of the debug material.
  2. MaterialSettings.ViewMaterialAttribute: Determines which material attribute to visualize when using the debug material.

Developers should be aware that:

  1. This is a debugging feature and should not be enabled in production builds.
  2. When enabled, it overrides all material properties of static meshes in the Lightmass calculations with a simple debug material.
  3. It affects the entire scene, not individual meshes.

Best practices when using this variable include:

  1. Use it temporarily for debugging lighting issues, not as a permanent solution.
  2. Combine it with MaterialSettings.ViewMaterialAttribute to isolate specific material properties for debugging.
  3. Remember to disable it before final lightmap generation to ensure accurate results.
  4. Use version control to track changes to the Lightmass configuration file to avoid accidentally committing debug settings.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:52, section: [DevOptions.StaticLightingMaterial]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2189

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLightingMaterial"), TEXT("bUseDebugMaterial"), bConfigBool, GLightmassIni));
		Scene.MaterialSettings.bUseDebugMaterial = bConfigBool;
		FString ShowMaterialAttributeName;
		VERIFYLIGHTMASSINI(GConfig->GetString(TEXT("DevOptions.StaticLightingMaterial"), TEXT("ShowMaterialAttribute"), ShowMaterialAttributeName, GLightmassIni));

		Scene.MaterialSettings.ViewMaterialAttribute = Lightmass::VMA_None;
		if (ShowMaterialAttributeName.Contains(TEXT("Emissive")) )
		{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingMesh.cpp:92

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingMesh::SetDebugMaterial

Source code excerpt:

void FStaticLightingMesh::SetDebugMaterial(bool bInUseDebugMaterial, FLinearColor InDiffuse)
{
	bUseDebugMaterial = bInUseDebugMaterial;
	DebugDiffuse = InDiffuse;
}

void FStaticLightingMesh::Import( FLightmassImporter& Importer )
{
	// Import into a temporary struct and manually copy settings over,

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingMesh.cpp:155

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingMesh::Import

Source code excerpt:

	}
	bColorInvalidTexels = true;
	bUseDebugMaterial = false;
	DebugDiffuse = FLinearColor::Black;
}

/** Determines whether two triangles overlap each other's AABB's. */
static bool AxisAlignedTriangleIntersectTriangle2d(
	const FVector2f& V0, const FVector2f& V1, const FVector2f& V2,

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingMesh : public virtual FRefCountedObject, public FStaticLightingMeshInstanceData

Source code excerpt:


	/** Indicates whether DebugDiffuse should override the materials associated with this mesh. */
	bool bUseDebugMaterial;
	FLinearColor DebugDiffuse;

	/** 
	 * Materials used by the mesh, guaranteed to contain at least one. 
	 * These are indexed by the primitive type specific ElementIndex.
	 */

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingMesh : public virtual FRefCountedObject, public FStaticLightingMeshInstanceData

Source code excerpt:


	/** For debugging */
	virtual void SetDebugMaterial(bool bUseDebugMaterial, FLinearColor Diffuse);

	/** 
	 * Whether mesh is always opaque for visibility calculations, 
	 * otherwise opaque property will be checked for each triangle 
	 */
	virtual bool IsAlwaysOpaqueForVisibility() const { return false; }

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingMesh : public virtual FRefCountedObject, public FStaticLightingMeshInstanceData
function     inline FLinearColor EvaluateDiffuse

Source code excerpt:

		checkSlow(!IsTranslucent(ElementIndex));
		FLinearColor Diffuse(DebugDiffuse);
		if (!bUseDebugMaterial)
		{
			float MaterialDiffuseBoost;
			const FMaterialElement& MaterialElement = MaterialElements[ElementIndex];
			MaterialElement.Material->SampleDiffuse(UVs, Diffuse, MaterialDiffuseBoost);
			Diffuse.R = FMath::Max(Diffuse.R, 0.0f);
			Diffuse.G = FMath::Max(Diffuse.G, 0.0f);

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:329

Scope (from outer to inner):

file
namespace    Lightmass
function     FStaticLightingSystem::FStaticLightingSystem

Source code excerpt:

				Stats.NumMeshAreaLightMeshes++;
			}
			Meshes[MeshIndex]->SetDebugMaterial(MaterialSettings.bUseDebugMaterial, MaterialSettings.DebugDiffuse);
		}
	}

	for (int32 MeshIndex = 0; MeshIndex < Meshes.Num(); MeshIndex++)
	{
		for (int32 LightIndex = 0; LightIndex < MeshAreaLights.Num(); LightIndex++)

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:192

Scope (from outer to inner):

file
namespace    Lightmass

Source code excerpt:

{
	/** Debugging - Whether to use the debug material */
	bool bUseDebugMaterial;

	/** Debugging - Indicates which material attribute to visualize. */
	EViewMaterialAttribute ViewMaterialAttribute;

	/** The size of the emissive sample */
	int32 EmissiveSize;