bUseEmbreePacketTracing

bUseEmbreePacketTracing

#Overview

name: bUseEmbreePacketTracing

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 bUseEmbreePacketTracing is to enable packet tracing in Embree, which is a high-performance ray tracing kernel library used in Unreal Engine’s static lighting system. This setting is specifically related to the rendering and lighting systems within Unreal Engine.

Based on the callsites, 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.

The value of this variable is set in the Lightmass.ini configuration file, as evidenced by the code that reads the value from the config file:

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

This variable interacts with other Embree-related settings, such as bUseEmbree, bVerifyEmbree, and bUseEmbreeInstancing. It is used in conjunction with these settings to configure the behavior of the Embree ray tracing library within Unreal Engine’s lighting system.

Developers must be aware that this is a work-in-progress feature, as indicated by the comment in the SceneExport.h file. The comment suggests that while the option exists, no lightmass algorithms currently emit packet tracing requests. This means that enabling this option may not have any immediate effect on the lighting calculations.

Best practices when using this variable include:

1. Only enable it if you’re specifically working on implementing or testing packet tracing in lightmass algorithms.
2. Be aware of potential performance implications, as packet tracing can affect rendering speed and memory usage.
3. Keep track of Unreal Engine updates, as this feature may become more fully implemented in future versions.
4. Consider this setting in conjunction with other Embree-related settings for optimal configuration of the static lighting system.
5. Test thoroughly when enabling this option, as it may interact with other lighting and rendering settings in complex ways.

#Setting Variables

#References In INI files

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

• INI Section: DevOptions.StaticLighting
• Raw value: false
• Is Array: False

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;
		GConfig->GetInt( TEXT("LightingBuildOptions"), TEXT("QualityLevel"), CheckQualityLevel, GEditorPerProjectIni);

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FEmbreeAggregateMesh::FEmbreeAggregateMesh

Source code excerpt:

	uint32 AlgorithmFlags = RTC_INTERSECT1;

	if (InScene.GeneralSettings.bUseEmbreePacketTracing)
	{
		AlgorithmFlags |= RTC_INTERSECT4;
	}

	EmbreeScene = rtcDeviceNewScene(InScene.EmbreeDevice, RTC_SCENE_STATIC, (RTCAlgorithmFlags)AlgorithmFlags);
	check(rtcDeviceGetError(EmbreeDevice) == RTC_NO_ERROR);

	if (InScene.GeneralSettings.bUseEmbreePacketTracing)
	{
#if RTCORE_VERSION_MAJOR >= 2 && RTCORE_VERSION_MINOR >= 14
		ssize_t SupportsPacketTracing = rtcDeviceGetParameter1i(EmbreeDevice, RTC_CONFIG_INTERSECT4);
		check(SupportsPacketTracing);
#endif
	}

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticLightingSettings

Source code excerpt:

	/** 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;

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