bAllowMultiThreadedStaticLighting

bAllowMultiThreadedStaticLighting

#Overview

name: bAllowMultiThreadedStaticLighting

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 bAllowMultiThreadedStaticLighting is to control whether the static lighting system in Unreal Engine 5 can utilize multiple threads for processing. This setting is primarily used for performance optimization in the lighting build process.

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

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

This variable interacts with the NumUnusedLocalCores variable, which determines how many local CPU cores should be left unused. Together, these variables control the thread allocation for static lighting calculations.

Developers must be aware that enabling multi-threaded static lighting can significantly improve performance on multi-core systems, but it may also introduce additional complexity in debugging and potentially increase memory usage.

Best practices when using this variable include:

  1. Enable it on development machines with multiple cores to speed up lighting builds.
  2. Consider disabling it if encountering stability issues or for easier debugging.
  3. Adjust the NumUnusedLocalCores in conjunction with this setting to fine-tune performance based on the specific hardware.
  4. Be cautious when enabling this on machines with limited resources, as it may lead to increased memory usage.
  5. Always test the lighting build process with this setting both enabled and disabled to ensure consistent results.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

	//@todo - need a mechanism to automatically catch when a new setting has been added but doesn't get initialized
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bAllowMultiThreadedStaticLighting"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bAllowMultiThreadedStaticLighting = bConfigBool;
		Scene.GeneralSettings.NumUnusedLocalCores = NumUnusedLocalCores;
		Scene.GeneralSettings.NumIndirectLightingBounces = LevelSettings.NumIndirectLightingBounces;
		Scene.GeneralSettings.NumSkyLightingBounces = LevelSettings.NumSkyLightingBounces;
		Scene.GeneralSettings.IndirectLightingSmoothness = LevelSettings.IndirectLightingSmoothness;
		Scene.GeneralSettings.IndirectLightingQuality = LevelSettings.IndirectLightingQuality;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FStaticLightingSystem::FStaticLightingSystem

Source code excerpt:

,	NumOutstandingVolumeDataLayers(0)
,	OutstandingVolumeDataLayerIndex(-1)
,	NumStaticLightingThreads(InScene.GeneralSettings.bAllowMultiThreadedStaticLighting ? FMath::Max(InNumThreads, 1) : 1)
,	DebugIrradiancePhotonCalculationArrayIndex(INDEX_NONE)
,	DebugIrradiancePhotonCalculationPhotonIndex(INDEX_NONE)
,	Exporter(InExporter)
{
	const double SceneSetupStart = FPlatformTime::Seconds();
	UE_LOG(LogLightmass, Log, TEXT("FStaticLightingSystem started using GKDOPMaxTrisPerLeaf: %d"), DEFAULT_MAX_TRIS_PER_LEAF);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:

public:
	/** Debugging - whether to allow multiple static lighting threads. */
	bool bAllowMultiThreadedStaticLighting;

	/**
	 * Number of local cores to leave unused
	 */
	int32 NumUnusedLocalCores;