EmissiveIntensityThreshold

EmissiveIntensityThreshold

#Overview

name: EmissiveIntensityThreshold

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

#Summary

#Usage in the C++ source code

The purpose of EmissiveIntensityThreshold is to set a minimum threshold for emissive materials to contribute to scene lighting in Unreal Engine’s lightmass system. This variable is used in the global illumination and lighting calculations, particularly for mesh area lights.

This setting variable is primarily used by the Lightmass system, which is Unreal Engine’s global illumination solution. It’s part of the lighting and rendering subsystem, specifically for static lighting calculations.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the configuration file in the UnrealEd module, specifically in the FLightmassExporter::WriteSceneSettings function.

EmissiveIntensityThreshold interacts with other Mesh Area Light settings, such as MeshAreaLightGridSize and MeshAreaLightSimplifyNormalAngleThreshold. It’s used in conjunction with these variables to determine how emissive materials are processed and contribute to lighting.

Developers must be aware that this threshold affects which emissive materials will be considered for lighting calculations. Setting it too high might exclude subtle emissive effects, while setting it too low could increase computation time by including very low-intensity emissive materials.

Best practices when using this variable include:

  1. Carefully balancing the threshold to optimize between lighting quality and performance.
  2. Considering the overall brightness of your scene when setting this value.
  3. Testing different values to find the optimal balance for your specific project.
  4. Documenting the chosen value and the reasoning behind it for future reference.
  5. Coordinating with the art team to ensure that important emissive materials meet or exceed this threshold.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.MeshAreaLights"), TEXT("bVisualizeMeshAreaLightPrimitives"), bConfigBool, GLightmassIni));
		Scene.MeshAreaLightSettings.bVisualizeMeshAreaLightPrimitives = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("EmissiveIntensityThreshold"), Scene.MeshAreaLightSettings.EmissiveIntensityThreshold, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightGridSize"), Scene.MeshAreaLightSettings.MeshAreaLightGridSize, GLightmassIni));
		float MeshAreaLightSimplifyNormalAngleThreshold;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightSimplifyNormalAngleThreshold"), MeshAreaLightSimplifyNormalAngleThreshold, GLightmassIni));
		Scene.MeshAreaLightSettings.MeshAreaLightSimplifyNormalCosAngleThreshold = FMath::Cos(FMath::Clamp(MeshAreaLightSimplifyNormalAngleThreshold, 0.0f, 90.0f) * (float)PI / 180.0f);
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightSimplifyCornerDistanceThreshold"), Scene.MeshAreaLightSettings.MeshAreaLightSimplifyCornerDistanceThreshold, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightSimplifyMeshBoundingRadiusFractionThreshold"), Scene.MeshAreaLightSettings.MeshAreaLightSimplifyMeshBoundingRadiusFractionThreshold, GLightmassIni));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingMesh::CreateMeshAreaLights

Source code excerpt:

					{
						// Push the current texel onto the stack if it is emissive and hasn't been processed yet
						AddLightTexel(TexelToCornersMap, MaterialIndex, LightIndices, X, Y, Scene.MeshAreaLightSettings.EmissiveIntensityThreshold, TexelsInCurrentLight, CurrentMaterial.EmissiveSize, CurrentMaterial.EmissiveSize);
						if (TexelsInCurrentLight.Num() > 0)
						{
							// This is the first texel in a new light group
							const int32 CurrentLightIndex = NextLightIndex;
							// Update the next light index
							NextLightIndex++;

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

Scope (from outer to inner):

file
function     void FStaticLightingMesh::CreateMeshAreaLights

Source code excerpt:

								LightIndices[NextTexel.Y * TexelToCornersMap.GetSizeX() + NextTexel.X] = CurrentLightIndex;
								// Push all of the texel's emissive, unprocessed neighbors onto the stack
								AddLightTexel(TexelToCornersMap, MaterialIndex, LightIndices, NextTexel.X - 1, NextTexel.Y, Scene.MeshAreaLightSettings.EmissiveIntensityThreshold, TexelsInCurrentLight, CurrentMaterial.EmissiveSize, CurrentMaterial.EmissiveSize);
								AddLightTexel(TexelToCornersMap, MaterialIndex, LightIndices, NextTexel.X + 1, NextTexel.Y, Scene.MeshAreaLightSettings.EmissiveIntensityThreshold, TexelsInCurrentLight, CurrentMaterial.EmissiveSize, CurrentMaterial.EmissiveSize);
								AddLightTexel(TexelToCornersMap, MaterialIndex, LightIndices, NextTexel.X, NextTexel.Y - 1, Scene.MeshAreaLightSettings.EmissiveIntensityThreshold, TexelsInCurrentLight, CurrentMaterial.EmissiveSize, CurrentMaterial.EmissiveSize);
								AddLightTexel(TexelToCornersMap, MaterialIndex, LightIndices, NextTexel.X, NextTexel.Y + 1, Scene.MeshAreaLightSettings.EmissiveIntensityThreshold, TexelsInCurrentLight, CurrentMaterial.EmissiveSize, CurrentMaterial.EmissiveSize);
							}
						}
					}
				}

				TArray<int32> PrimitiveIndices;

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

Scope: file

Source code excerpt:

								const float XFraction = X / (float)CurrentMaterial.EmissiveSize;
								const FLinearColor CurrentEmissive = EvaluateEmissive(FVector2f(XFraction, YFraction), MaterialIndex);
								checkSlow(CurrentEmissive.R > Scene.MeshAreaLightSettings.EmissiveIntensityThreshold 
									|| CurrentEmissive.G > Scene.MeshAreaLightSettings.EmissiveIntensityThreshold 
									|| CurrentEmissive.B > Scene.MeshAreaLightSettings.EmissiveIntensityThreshold);

								// Add a new primitive representing this texel to the light the texel was assigned to in the first pass
								EmissivePrimitives[LightIndex][PrimitiveIndex].AddSubPrimitive(
									CurrentTexelCorners, 
									FIntPoint(X, Y), 
									CurrentEmissive,

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

Scope (from outer to inner):

file
namespace    Lightmass

Source code excerpt:


	/** Emissive intensities must be larger than this to contribute toward scene lighting. */
	float EmissiveIntensityThreshold;

	/** 
	* Size of the grid that each mesh area light will use to cache information.  
	* Larger grids take longer to precompute, but result in accelerated light sampling.
	*/
	int32 MeshAreaLightGridSize;