NumUnusedLocalCores

NumUnusedLocalCores

#Overview

name: NumUnusedLocalCores

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 NumUnusedLocalCores is to specify the number of CPU cores that should be left unused during lightmass processing in Unreal Engine’s static lighting system. This setting allows developers to reserve some processing power for other tasks while the lighting build is in progress.

This setting variable is primarily used by the Unreal Engine’s static lighting system, specifically within the Lightmass module. It is referenced in the UnrealEd and Engine modules, which are responsible for editor functionality and core engine features, respectively.

The value of this variable is typically set through the FLightingBuildOptions structure, which is used to configure various aspects of the lighting build process. It can be modified programmatically using the SetNumUnusedLocalCores function of the FLightmassExporter class.

NumUnusedLocalCores interacts with other lighting-related variables, such as QualityLevel and various settings within the FStaticLightingSettings structure. These variables collectively determine how the lighting build process is executed.

Developers should be aware that setting NumUnusedLocalCores too high may significantly increase the time required for lighting builds, as fewer cores will be available for processing. Conversely, setting it too low might impact system responsiveness during builds.

Best practices when using this variable include:

  1. Setting it to a value that balances build performance with system responsiveness.
  2. Considering the total number of available cores on the target machine.
  3. Adjusting the value based on the specific needs of the project and the hardware capabilities of the development team.
  4. Testing different values to find the optimal setting for your specific use case.
  5. Documenting the chosen value and the reasoning behind it for team reference.

Remember that the optimal value may vary depending on the project’s size, complexity, and the hardware specifications of the development machines.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEditorPerProjectUserSettings.ini:508, section: [LightingBuildOptions]

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;

		if (QualityLevel == Quality_Preview)

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.h:72

Scope (from outer to inner):

file
class        class FLightmassExporter
function     void SetNumUnusedLocalCores

Source code excerpt:

	void SetNumUnusedLocalCores(int32 InNumUnusedLocalCores)
	{
		NumUnusedLocalCores = InNumUnusedLocalCores;
	}

	void SetQualityLevel(ELightingBuildQuality InQualityLevel)
	{
		QualityLevel = InQualityLevel;
	}

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.h:210

Scope (from outer to inner):

file
class        class FLightmassExporter

Source code excerpt:

	FLightmassWorldInfoSettings LevelSettings;
	/** The number of local cores to leave unused */
	int32 NumUnusedLocalCores;
	/** The quality level of the lighting build */
	ELightingBuildQuality QualityLevel;

	/** Amortize Export stage that we currently are in */
	enum AmortizedExportStage
	{

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

Scope (from outer to inner):

file
function     void FStaticLightingSystem::GatherScene

Source code excerpt:

		LightmassExporter->SetLevelSettings(TempSettings);
	}
	LightmassExporter->SetNumUnusedLocalCores(Options.NumUnusedLocalCores);
	LightmassExporter->SetQualityLevel(Options.QualityLevel);

	if (World->PersistentLevel && Options.ShouldBuildLightingForLevel( World->PersistentLevel ))
	{
		LightmassExporter->SetLevelName(World->PersistentLevel->GetPathName());
	}

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:

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

	/** 
	 * Number of indirect lighting bounces to simulate, 0 is direct lighting only. 
	 * The first bounce always costs the most in terms of computation time, with the second bounce following.  
	 * With photon mapping, bounces after the second are nearly free.
	 */

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/LightingBuildOptions.h:22

Scope (from outer to inner):

file
class        class FLightingBuildOptions
function     FLightingBuildOptions

Source code excerpt:

	,	bShowLightingBuildInfo(false)
	,	QualityLevel(Quality_Preview)
	,	NumUnusedLocalCores(1)
	{}

	/**
	 * @return true if the lighting should be built for the level, given the current set of lighting build options.
	 */
	ENGINE_API bool ShouldBuildLightingForLevel(ULevel* Level) const;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/LightingBuildOptions.h:49

Scope (from outer to inner):

file
class        class FLightingBuildOptions

Source code excerpt:

	static ELightingBuildQuality	HalfResolutionLightmapQualityLevel;
	/** The number of cores to leave 'unused'										*/
	int32						NumUnusedLocalCores;
	/** The set of levels selected in the Level Browser.							*/
	TArray<ULevel*>			SelectedLevels;
};