bUseEmbree

bUseEmbree

#Overview

name: bUseEmbree

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

#Summary

#Usage in the C++ source code

The purpose of bUseEmbree is to control whether the Unreal Engine uses the Embree ray tracing library for certain operations, particularly in the context of static lighting and distance field generation.

This setting variable is primarily used in the Mesh Utilities and Lightmass subsystems of Unreal Engine. It’s particularly relevant for static lighting calculations and distance field generation for meshes.

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

bUseEmbree interacts with several other variables:

  1. bVerifyEmbree: Used to enable coherency checks when Embree is in use.
  2. bUseEmbreePacketTracing: Controls whether to use Embree’s packet tracing feature.
  3. bUseEmbreeInstancing: Determines if Embree instancing should be used.

Developers should be aware that:

  1. Embree is an external library, so its availability might depend on the build configuration.
  2. Using Embree can significantly impact performance and memory usage, especially for complex scenes.
  3. The effectiveness of Embree can vary depending on the specific use case and scene complexity.

Best practices when using this variable include:

  1. Ensure that Embree is properly integrated into your Unreal Engine build if you plan to enable this feature.
  2. Test performance with and without Embree to determine if it provides benefits for your specific use case.
  3. Be cautious when enabling additional Embree features like packet tracing or instancing, as they may have different performance implications.
  4. When debugging ray tracing issues, consider using the bVerifyEmbree option to check for coherency problems.
  5. Remember that this setting affects both editor-time operations (like building lighting) and potentially runtime performance if used for dynamic operations.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshDistanceFieldUtilities.cpp:274

Scope (from outer to inner):

file
function     void FMeshUtilities::GenerateSignedDistanceFieldVolumeData

Source code excerpt:

			EmbreeScene);

		check(EmbreeScene.bUseEmbree);

		// If Embree setup fails, there will be no scene to operate on. Early out.
		if (!EmbreeScene.EmbreeScene)
		{
			return;
		}

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshRepresentationCommon.cpp:141

Scope (from outer to inner):

file
function     void MeshRepresentation::SetupEmbreeScene

Source code excerpt:


#if USE_EMBREE
	EmbreeScene.bUseEmbree = true;

	if (EmbreeScene.bUseEmbree)
	{
		EmbreeScene.EmbreeDevice = rtcNewDevice(nullptr);
		rtcSetDeviceErrorFunction(EmbreeScene.EmbreeDevice, EmbreeErrorFunc, nullptr);

		RTCError ReturnErrorNewDevice = rtcGetDeviceError(EmbreeScene.EmbreeDevice);
		if (ReturnErrorNewDevice != RTC_ERROR_NONE)

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshRepresentationCommon.cpp:291

Scope (from outer to inner):

file
function     void MeshRepresentation::SetupEmbreeScene

Source code excerpt:

		}

		if (EmbreeScene.bUseEmbree)
		{
			EmbreeIndices[FilteredTriangleIndex * 3 + 0] = I0;
			EmbreeIndices[FilteredTriangleIndex * 3 + 1] = I1;
			EmbreeIndices[FilteredTriangleIndex * 3 + 2] = I2;

			EmbreeVertices[I0] = V0;

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshRepresentationCommon.cpp:318

Scope (from outer to inner):

file
function     void MeshRepresentation::SetupEmbreeScene

Source code excerpt:


#if USE_EMBREE
	if (EmbreeScene.bUseEmbree)
	{
		RTCGeometry Geometry = rtcNewGeometry(EmbreeScene.EmbreeDevice, RTC_GEOMETRY_TYPE_TRIANGLE);
		EmbreeScene.Geometry.InternalGeometry = Geometry;

		rtcSetSharedGeometryBuffer(Geometry, RTC_BUFFER_TYPE_VERTEX, 0, RTC_FORMAT_FLOAT3, EmbreeVertices, 0, sizeof(FVector3f), NumVertices);
		rtcSetSharedGeometryBuffer(Geometry, RTC_BUFFER_TYPE_INDEX, 0, RTC_FORMAT_UINT3, EmbreeIndices, 0, sizeof(uint32) * 3, FilteredTriangles.Num());

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshRepresentationCommon.cpp:375

Scope (from outer to inner):

file
function     void MeshRepresentation::DeleteEmbreeScene

Source code excerpt:

{
#if USE_EMBREE
	if (EmbreeScene.bUseEmbree)
	{
		rtcReleaseScene(EmbreeScene.EmbreeScene);
		rtcReleaseDevice(EmbreeScene.EmbreeDevice);
	}
#endif
}

#Loc: <Workspace>/Engine/Source/Developer/MeshUtilities/Private/MeshRepresentationCommon.h:81

Scope (from outer to inner):

file
class        class FEmbreeScene

Source code excerpt:

{
public:
	bool bUseEmbree = false;
	int32 NumIndices = 0;
	bool bMostlyTwoSided = false;

	// Embree
	RTCDevice EmbreeDevice = nullptr;
	RTCScene EmbreeScene = nullptr;

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2135

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MaxTriangleLightingSamples"), Scene.GeneralSettings.MaxTriangleLightingSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MaxTriangleIrradiancePhotonCacheSamples"), Scene.GeneralSettings.MaxTriangleIrradiancePhotonCacheSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbree"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bUseEmbree = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bVerifyEmbree"), bConfigBool, GLightmassIni));
		Scene.GeneralSettings.bVerifyEmbree = Scene.GeneralSettings.bUseEmbree && bConfigBool;
		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;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::Import

Source code excerpt:


#if USE_EMBREE
	if (TempHeader.GeneralSettings.bUseEmbree)
	{
		EmbreeDevice = rtcNewDevice(NULL);
		check(rtcDeviceGetError(EmbreeDevice) == RTC_NO_ERROR);
		bVerifyEmbree = TempHeader.GeneralSettings.bVerifyEmbree;
	}
#endif

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:

	 * Whether to use Embree for ray tracing or not.
	 */
	bool bUseEmbree;

	/** 
	 * Whether to check for Embree coherency.
	 */
	bool bVerifyEmbree;