bUseEmbreeInstancing

bUseEmbreeInstancing

#Overview

name: bUseEmbreeInstancing

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

#Summary

#Usage in the C++ source code

The purpose of bUseEmbreeInstancing is to control the use of static mesh instancing in the Unreal Engine’s lightmass system, which is part of the static lighting computation process. This setting is specifically designed to reduce memory consumption in large scenes with many repeated meshes, such as forests.

This setting variable is primarily used in the static lighting and lightmass subsystems of Unreal Engine. It is referenced in the UnrealLightmass program and the UnrealEd module, which are responsible for baking lighting and handling editor-related tasks, respectively.

The value of this variable is set in the Unreal Engine configuration files, specifically in the “DevOptions.StaticLighting” section of the LightmassIni file. It is read using the GConfig->GetBool function in the FLightmassExporter::WriteSceneSettings method.

This variable interacts with other lighting and geometry-related variables in the FStaticLightingSettings class, such as bUseEmbreePacketTracing and bUseFastVoxelization. It also affects how the FEmbreeAggregateMesh class handles mesh instances.

Developers must be aware that while this setting can significantly reduce memory usage in large scenes with many repeated static meshes, it may potentially slow down the lighting computation for smaller scenes. Therefore, it’s important to consider the scale and composition of the scene when deciding whether to enable this option.

Best practices when using this variable include:

  1. Enable it for large scenes with many repeated static meshes, such as forests or cityscapes.
  2. Consider disabling it for smaller scenes or scenes with few repeated elements to potentially improve performance.
  3. Test the lighting build times and quality with this option both enabled and disabled to determine the optimal setting for your specific project.
  4. Monitor memory usage during lightmass calculations to ensure it’s providing the desired benefits.
  5. Use in conjunction with other lightmass optimization settings for best results.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbreePacketTracing"), Scene.GeneralSettings.bUseEmbreePacketTracing, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseFastVoxelization"), Scene.GeneralSettings.bUseFastVoxelization, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbreeInstancing"), Scene.GeneralSettings.bUseEmbreeInstancing, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MappingSurfaceCacheDownsampleFactor"), Scene.GeneralSettings.MappingSurfaceCacheDownsampleFactor, GLightmassIni));

		int32 CheckQualityLevel;
		GConfig->GetInt( TEXT("LightingBuildOptions"), TEXT("QualityLevel"), CheckQualityLevel, GEditorPerProjectIni);
		CheckQualityLevel = FMath::Clamp<int32>(CheckQualityLevel, Quality_Preview, Quality_Production);
		UE_LOG(LogLightmassSolver, Log, TEXT("LIGHTMASS: Writing scene settings: Quality level %d (%d in INI)"), (int32)(QualityLevel), CheckQualityLevel);

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/Embree.cpp:641

Scope (from outer to inner):

file
namespace    Lightmass
function     void FEmbreeAggregateMesh::AddMesh

Source code excerpt:

 		SceneBounds = SceneBounds + Mesh->BoundingBox;

		if (Scene.GeneralSettings.bUseEmbreeInstancing && Mesh->GetInstanceableStaticMesh() != nullptr)
		{
			const FStaticMeshStaticLightingMesh* StaticMeshInstance = Mesh->GetInstanceableStaticMesh();

			const FStaticMeshLOD* LOD = &StaticMeshInstance->StaticMesh->GetLOD(StaticMeshInstance->GetMeshLODIndex());

			if (!StaticMeshGeometries.Find(LOD))

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/Embree.cpp:739

Scope (from outer to inner):

file
namespace    Lightmass
function     void FEmbreeAggregateMesh::DumpStats

Source code excerpt:

	UE_LOG(LogLightmass, Log, TEXT("\n"));
	UE_LOG(LogLightmass, Log, TEXT("Collision Mesh Overview:"));
	if (Scene.GeneralSettings.bUseEmbreeInstancing)
	{
		UE_LOG(LogLightmass, Log, TEXT("Num Triangles         : %d (Instanced to %d)"), TotalNumTriangles, TotalNumTriangles + TotalNumTrianglesInstanced);
	}
	else
	{
		UE_LOG(LogLightmass, Log, TEXT("Num Triangles         : %d"), TotalNumTriangles);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:


	/** Whether to use static mesh instancing to reduce memory consumption in scenes like large forest. Might slow down small scenes. */
	bool bUseEmbreeInstancing;

	/** 
	 * Direct lighting, skylight radiosity and irradiance photons are cached on mapping surfaces to accelerate final gathering.
	 * This controls the downsample factor for that cache, relative to the mapping's lightmap resolution.
	 */
	int32 MappingSurfaceCacheDownsampleFactor;