MeshAreaLightGeneratedDynamicLightSurfaceOffset

MeshAreaLightGeneratedDynamicLightSurfaceOffset

#Overview

name: MeshAreaLightGeneratedDynamicLightSurfaceOffset

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

#Summary

#Usage in the C++ source code

The purpose of MeshAreaLightGeneratedDynamicLightSurfaceOffset is to control the placement of generated dynamic lights that approximate the influence of mesh area lights on dynamic objects in Unreal Engine 5’s lighting system.

This setting variable is primarily used in the lighting and rendering subsystems of Unreal Engine 5, specifically in the Lightmass module, which is responsible for static lighting calculations.

The value of this variable is typically set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.MeshAreaLights” section. It is read during the scene export process for Lightmass calculations.

MeshAreaLightGeneratedDynamicLightSurfaceOffset interacts with other mesh area light settings, such as MeshAreaLightSimplifyCornerDistanceThreshold and MeshAreaLightSimplifyMeshBoundingRadiusFractionThreshold. It is also affected by the StaticLightingLevelScale, which scales the offset value.

Developers should be aware that this variable affects the positioning of generated dynamic lights relative to the mesh area light’s surface. A larger offset value will place the generated light further away from the mesh surface, which can help prevent light bleeding or intersections with the mesh geometry.

Best practices when using this variable include:

  1. Adjusting the value based on the scale of your scene to ensure proper light placement.
  2. Balancing the offset with other mesh area light settings to achieve the desired lighting effect.
  3. Testing the impact of different offset values on both static and dynamic objects in the scene to find the optimal setting.
  4. Considering the performance implications of generated dynamic lights, especially in scenes with many mesh area lights.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightSimplifyCornerDistanceThreshold"), Scene.MeshAreaLightSettings.MeshAreaLightSimplifyCornerDistanceThreshold, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightSimplifyMeshBoundingRadiusFractionThreshold"), Scene.MeshAreaLightSettings.MeshAreaLightSimplifyMeshBoundingRadiusFractionThreshold, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.MeshAreaLights"), TEXT("MeshAreaLightGeneratedDynamicLightSurfaceOffset"), Scene.MeshAreaLightSettings.MeshAreaLightGeneratedDynamicLightSurfaceOffset, GLightmassIni));
	}
	{
		Scene.AmbientOcclusionSettings.bUseAmbientOcclusion = LevelSettings.bUseAmbientOcclusion;
		Scene.AmbientOcclusionSettings.bGenerateAmbientOcclusionMaterialMask = LevelSettings.bGenerateAmbientOcclusionMaterialMask;
		Scene.AmbientOcclusionSettings.bVisualizeAmbientOcclusion = LevelSettings.bVisualizeAmbientOcclusion;
		Scene.AmbientOcclusionSettings.DirectIlluminationOcclusionFraction = LevelSettings.DirectIlluminationOcclusionFraction;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/Exporter.cpp:97

Scope (from outer to inner):

file
namespace    Lightmass
function     void FLightmassSolverExporter::ExportMeshAreaLightData

Source code excerpt:

	 * So that UE5 can create dynamic lights to approximate the mesh area light's influence on dynamic objects.
	 */
	void FLightmassSolverExporter::ExportMeshAreaLightData(const TIndirectArray<FMeshAreaLight>& MeshAreaLights, float MeshAreaLightGeneratedDynamicLightSurfaceOffset) const
	{
		const FString ChannelName = CreateChannelName(MeshAreaLightDataGuid, LM_MESHAREALIGHTDATA_VERSION, LM_MESHAREALIGHTDATA_EXTENSION);
		const int32 ErrorCode = Swarm->OpenChannel(*ChannelName, LM_MESHAREALIGHT_CHANNEL_FLAGS, true);
		if( ErrorCode >= 0 )
		{
			int32 NumMeshAreaLights = MeshAreaLights.Num();

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/Exporter.cpp:126

Scope (from outer to inner):

file
namespace    Lightmass
function     void FLightmassSolverExporter::ExportMeshAreaLightData

Source code excerpt:

				}
				// Offset the position somewhat to reduce the chance of the generated light being inside the mesh
				LightData.Position = CurrentLight.Position + AverageNormal *MeshAreaLightGeneratedDynamicLightSurfaceOffset;
				// Use the average normal for the generated light's direction
				LightData.Direction = AverageNormal;
				LightData.Radius = CurrentLight.InfluenceRadius;
				// Approximate the mesh area light's cosine lobe falloff using a Unreal spotlight's cone angle falloff
				LightData.ConeAngle = PI / 2.0f;
				FLinearColor LightIntensity = CurrentLight.TotalPower / CurrentLight.TotalSurfaceArea;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/Exporter.h:60

Scope (from outer to inner):

file
namespace    Lightmass
class        class FLightmassSolverExporter

Source code excerpt:

		 * So that Unreal can create dynamic lights to approximate the mesh area light's influence on dynamic objects.
		 */
		void ExportMeshAreaLightData(const class TIndirectArray<FMeshAreaLight>& MeshAreaLights, float MeshAreaLightGeneratedDynamicLightSurfaceOffset) const;

		/** Exports the volume distance field. */
		void ExportVolumeDistanceField(int32 VolumeSizeX, int32 VolumeSizeY, int32 VolumeSizeZ, float VolumeMaxDistance, const FBox3f& DistanceFieldVolumeBounds, const TArray<FColor>& VolumeDistanceField) const;

	private:
		class FLightmassSwarm*	Swarm;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/LightmassScene.cpp:515

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::ApplyStaticLightingScale

Source code excerpt:

	SceneConstants.SmallestTexelRadius *= SceneConstants.StaticLightingLevelScale;
	MeshAreaLightSettings.MeshAreaLightSimplifyCornerDistanceThreshold *= SceneConstants.StaticLightingLevelScale;
	MeshAreaLightSettings.MeshAreaLightGeneratedDynamicLightSurfaceOffset *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.FirstSurfaceSampleLayerHeight *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.SurfaceLightSampleSpacing *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.SurfaceSampleLayerHeightSpacing *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.DetailVolumeSampleSpacing *= SceneConstants.StaticLightingLevelScale;
	DynamicObjectSettings.VolumeLightSampleSpacing *= SceneConstants.StaticLightingLevelScale;
	VolumeDistanceFieldSettings.VoxelSize *= SceneConstants.StaticLightingLevelScale;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ExportNonMappingTasks

Source code excerpt:

	if (bShouldExportMeshAreaLightData)
	{
		Exporter.ExportMeshAreaLightData(MeshAreaLights, MeshAreaLightSettings.MeshAreaLightGeneratedDynamicLightSurfaceOffset);

		// Tell Swarm the task is complete (if we're not in debugging mode).
		if ( !IsDebugMode() )
		{
			FLightmassSwarm* Swarm = GetExporter().GetSwarm();
			Swarm->TaskCompleted( MeshAreaLightDataGuid );

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

Scope (from outer to inner):

file
namespace    Lightmass

Source code excerpt:


	/** Distance along the average normal from the bounds origin of the mesh area light to place a light to handle influencing dynamic objects. */
	float MeshAreaLightGeneratedDynamicLightSurfaceOffset;
};

/** AO settings */
class FAmbientOcclusionSettings
{
public: