bVerifyEmbree

bVerifyEmbree

#Overview

name: bVerifyEmbree

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

#Summary

#Usage in the C++ source code

The purpose of bVerifyEmbree is to enable or disable verification checks for the Embree ray tracing library in Unreal Engine’s static lighting system. Embree is a high-performance ray tracing library used to accelerate ray tracing operations in the lightmass calculations.

This setting variable is primarily used in the static lighting and lightmass subsystems of Unreal Engine. It is referenced in the UnrealEd module and the UnrealLightmass program, which are responsible for handling static lighting calculations and exports.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It is read from the config file in the FLightmassExporter::WriteSceneSettings function within Lightmass.cpp.

bVerifyEmbree interacts closely with bUseEmbree. The verification is only enabled when both bUseEmbree and bVerifyEmbree are true, as seen in the line:

Scene.GeneralSettings.bVerifyEmbree = Scene.GeneralSettings.bUseEmbree && bConfigBool;

Developers should be aware that enabling this variable may impact performance, as it adds additional verification checks to the Embree ray tracing operations. It should primarily be used for debugging and ensuring the correctness of Embree calculations.

Best practices when using this variable include:

  1. Only enable it when debugging issues related to Embree ray tracing in static lighting calculations.
  2. Disable it in production builds to avoid unnecessary performance overhead.
  3. Use it in conjunction with other Embree-related settings (bUseEmbree, bUseEmbreePacketTracing, bUseEmbreeInstancing) for comprehensive testing and verification.
  4. Be prepared for potential performance impacts when this setting is enabled, especially in complex scenes with extensive static lighting.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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:69

Scope (from outer to inner):

file
namespace    Lightmass
function     FScene::FScene

Source code excerpt:

FScene::FScene() : 
	EmbreeDevice(NULL),
	bVerifyEmbree(false)
{
	FMemory::Memzero( (FSceneFileHeader*)this, sizeof(FSceneFileHeader) );
}

FScene::~FScene()
{

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::Import

Source code excerpt:

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

	// The assignment above overwrites ImportanceVolumes since FSceneFileHeader has some padding which coincides with ImportanceVolumes
	FMemory::Memzero(&ImportanceVolumes, sizeof(ImportanceVolumes));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/LightmassScene.h:779

Scope (from outer to inner):

file
namespace    Lightmass
class        class FScene : public FSceneFileHeader

Source code excerpt:


	RTCDevice EmbreeDevice;
	bool bVerifyEmbree;

	/** The mapping whose texel is selected in Unreal and is being debugged. */
	const class FStaticLightingMapping* DebugMapping;

	const FLight* FindLightByGuid(const FGuid& Guid) const;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FStaticLightingSystem::FStaticLightingSystem

Source code excerpt:

	if (Scene.EmbreeDevice)
	{
		if (Scene.bVerifyEmbree)
		{
			AggregateMesh = new FEmbreeVerifyAggregateMesh(Scene);
		}
		else
		{
			AggregateMesh = new FEmbreeAggregateMesh(Scene);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:

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

	/** Whether to build Embree data structures for packet tracing. WIP feature - no lightmass algorithms emit packet tracing requests yet. */
	bool bUseEmbreePacketTracing;

	/** Whether to use kDOP trees to accelerate volumetric lightmap voxelization. Useful in scenes like large forest. */
	bool bUseFastVoxelization;