DebugDiffuse

DebugDiffuse

#Overview

name: DebugDiffuse

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 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DebugDiffuse is to provide a debug override for the diffuse color of materials in the static lighting system of Unreal Engine 5. It is primarily used for debugging and testing purposes in the Lightmass system, which is responsible for generating static lighting in the engine.

This setting variable is mainly relied upon by the Lightmass subsystem, which is part of Unreal Engine’s lighting and rendering pipeline. It is used in both the editor (UnrealEd) and the Lightmass program itself.

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

DebugDiffuse interacts with other variables, particularly:

  1. bUseDebugMaterial: A boolean flag that determines whether DebugDiffuse should override the materials associated with a mesh.
  2. MaterialSettings: A struct that contains various material-related settings for static lighting calculations.

Developers must be aware that:

  1. This variable is intended for debugging purposes and should not be used in production environments.
  2. It overrides the actual material properties of meshes when enabled, which can significantly affect the appearance and lighting calculations of the scene.
  3. The variable is a FLinearColor, meaning it has separate R, G, and B components that can be set independently.

Best practices when using this variable include:

  1. Only enable it temporarily for debugging specific lighting issues.
  2. Remember to disable it (by setting bUseDebugMaterial to false) when done debugging to ensure accurate lighting calculations.
  3. Use it in conjunction with other debugging tools and variables in the Lightmass system for comprehensive analysis.
  4. Document any changes made to this variable during development to avoid confusion in team settings.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:62, 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:2218

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLightingMaterial"), TEXT("NormalSampleSize"), Scene.MaterialSettings.NormalSize, GLightmassIni));

		const FString DiffuseStr = GConfig->GetStr(TEXT("DevOptions.StaticLightingMaterial"), TEXT("DebugDiffuse"), GLightmassIni);
		VERIFYLIGHTMASSINI(FParse::Value(*DiffuseStr, TEXT("R="), Scene.MaterialSettings.DebugDiffuse.R));
		VERIFYLIGHTMASSINI(FParse::Value(*DiffuseStr, TEXT("G="), Scene.MaterialSettings.DebugDiffuse.G));
		VERIFYLIGHTMASSINI(FParse::Value(*DiffuseStr, TEXT("B="), Scene.MaterialSettings.DebugDiffuse.B));

		Scene.MaterialSettings.EnvironmentColor = FLinearColor(LevelSettings.EnvironmentColor) * LevelSettings.EnvironmentIntensity;

		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.NormalMapsForStaticLighting"));
		Scene.MaterialSettings.bUseNormalMapsForLighting = CVar->GetValueOnGameThread() != 0;
	}

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingMesh::SetDebugMaterial

Source code excerpt:

{
	bUseDebugMaterial = bInUseDebugMaterial;
	DebugDiffuse = InDiffuse;
}

void FStaticLightingMesh::Import( FLightmassImporter& Importer )
{
	// Import into a temporary struct and manually copy settings over,
	// Since the import will overwrite padding in FStaticLightingMeshInstanceData which is actual data in derived classes.

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

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, 
	const FVector2f& OtherV0, const FVector2f& OtherV1, const FVector2f& OtherV2)

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

Scope (from outer to inner):

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

Source code excerpt:

	bool bColorInvalidTexels;

	/** 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.
	 */
	TArray<FMaterialElement, TInlineAllocator<5>> MaterialElements;

#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:216

Scope (from outer to inner):

file
namespace    Lightmass

Source code excerpt:

	 * This is the diffuse term in the modified Phong BRDF, not the original.
	 */
	FLinearColor DebugDiffuse;

	/** Debugging - Emissive value assigned to secondary rays which miss all geometry in the scene. */
	FLinearColor EnvironmentColor;
};

/** Settings for meshes which emit light from their emissive areas. */