MinimumImportanceVolumeExtentWithoutWarning

MinimumImportanceVolumeExtentWithoutWarning

#Overview

name: MinimumImportanceVolumeExtentWithoutWarning

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

#Summary

#Usage in the C++ source code

The purpose of MinimumImportanceVolumeExtentWithoutWarning is to define a threshold size for the importance volume in static lighting calculations. It is used to determine when to issue warnings about the size of the automatically generated importance volume and to limit its extent if necessary.

This setting variable is primarily used in the static lighting system and the GPU Lightmass plugin. It’s referenced in both the core Unreal Engine static lighting system (UnrealEd module) and the experimental GPU Lightmass plugin.

The value of this variable is set in the configuration file, specifically in the “DevOptions.StaticLightingSceneConstants” section of the GLightmassIni file. It’s retrieved using the GConfig->GetFloat() function.

This variable interacts with the automatically calculated scene bounds (AutomaticImportanceVolumeBounds) and is used to determine if the scene is too large for efficient lighting calculations without a manually placed importance volume.

Developers must be aware that this variable affects the performance and quality of static lighting calculations. If the automatically generated importance volume exceeds this threshold, it can lead to suboptimal lighting results and increased build times.

Best practices when using this variable include:

  1. Manually placing importance volumes in the scene to avoid relying on automatic generation.
  2. Adjusting the value carefully if needed, considering the trade-off between performance and lighting quality.
  3. Monitoring lighting build logs for warnings related to importance volume size.
  4. Considering scene scale when setting up levels to avoid exceeding this threshold unnecessarily.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Scene.cpp:155

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FScene::GatherImportanceVolumes

Source code excerpt:

	if (CombinedImportanceVolume.GetExtent().SizeSquared() == 0)
	{
		float MinimumImportanceVolumeExtentWithoutWarning = 0.0f;
		verify(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("MinimumImportanceVolumeExtentWithoutWarning"), MinimumImportanceVolumeExtentWithoutWarning, GLightmassIni));

		FBox AutomaticImportanceVolumeBounds(ForceInit);

		for (FGeometryAndItsArray GeomIt : Geometries)
		{
			FGeometry& Geometry = GeomIt.GetGeometry();

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Scene.cpp:171

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FScene::GatherImportanceVolumes

Source code excerpt:


		FBox ReasonableSceneBounds = AutomaticImportanceVolumeBounds;
		if (ReasonableSceneBounds.GetExtent().SizeSquared() > (MinimumImportanceVolumeExtentWithoutWarning * MinimumImportanceVolumeExtentWithoutWarning))
		{
			// Emit a serious warning to the user about performance.
			FMessageLog("LightingResults").PerformanceWarning(LOCTEXT("LightmassError_MissingImportanceVolume", "No importance volume found and the scene is so large that the automatically synthesized volume will not yield good results.  Please add a tightly bounding lightmass importance volume to optimize your scene's quality and lighting build times."));

			// Clamp the size of the importance volume we create to a reasonable size
			ReasonableSceneBounds = FBox(ReasonableSceneBounds.GetCenter() - MinimumImportanceVolumeExtentWithoutWarning, ReasonableSceneBounds.GetCenter() + MinimumImportanceVolumeExtentWithoutWarning);
		}
		else
		{
			// The scene isn't too big, so we'll use the scene's bounds as a synthetic importance volume
			// NOTE: We don't want to pop up a message log for this common case when creating a new level, so we just spray a log message.  It's not very important to a user.
			UE_LOG(LogGPULightmass, Warning, TEXT("No importance volume found, so the scene bounding box was used.  You can optimize your scene's quality and lighting build times by adding importance volumes."));

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/StaticLightingSystem/StaticLightingSystem.cpp:2127

Scope (from outer to inner):

file
function     void FStaticLightingSystem::GatherScene

Source code excerpt:

	}

	float MinimumImportanceVolumeExtentWithoutWarning = 0.0f;
	verify(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("MinimumImportanceVolumeExtentWithoutWarning"), MinimumImportanceVolumeExtentWithoutWarning, GLightmassIni));

	// If we have no importance volumes, then we'll synthesize one now.  A scene without any importance volumes will not yield
	// expected lighting results, so it's important to have a volume to pass to Lightmass.
	if (LightmassExporter->GetImportanceVolumes().Num() == 0)
	{
		FBox ReasonableSceneBounds = AutomaticImportanceVolumeBounds;
		if (ReasonableSceneBounds.GetExtent().SizeSquared() > (MinimumImportanceVolumeExtentWithoutWarning * MinimumImportanceVolumeExtentWithoutWarning))
		{
			// Emit a serious warning to the user about performance.
			FMessageLog("LightingResults").PerformanceWarning(LOCTEXT("LightmassError_MissingImportanceVolume", "No importance volume found and the scene is so large that the automatically synthesized volume will not yield good results.  Please add a tightly bounding lightmass importance volume to optimize your scene's quality and lighting build times."));

			// Clamp the size of the importance volume we create to a reasonable size
			ReasonableSceneBounds = FBox(ReasonableSceneBounds.GetCenter() - MinimumImportanceVolumeExtentWithoutWarning, ReasonableSceneBounds.GetCenter() + MinimumImportanceVolumeExtentWithoutWarning);
		}
		else
		{
			// The scene isn't too big, so we'll use the scene's bounds as a synthetic importance volume
			// NOTE: We don't want to pop up a message log for this common case when creating a new level, so we just spray a log message.  It's not very important to a user.
			UE_LOG(LogStaticLightingSystem, Warning, TEXT("No importance volume found, so the scene bounding box was used.  You can optimize your scene's quality and lighting build times by adding importance volumes."));