bUsePhotonSegmentsForVolumeLighting

bUsePhotonSegmentsForVolumeLighting

#Overview

name: bUsePhotonSegmentsForVolumeLighting

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 bUsePhotonSegmentsForVolumeLighting is to control the use of photon segments for volumetric lighting calculations in Unreal Engine 5’s lighting system. This setting is part of the photon mapping system, which is used for global illumination and indirect lighting effects.

This setting variable is primarily used in the Lightmass subsystem of Unreal Engine, which is responsible for precomputed lighting calculations. It is referenced in both the editor (UnrealEd) and the Lightmass program itself.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It is read from the “DevOptions.PhotonMapping” section of the configuration file.

This variable interacts with other photon mapping settings, such as PhotonSegmentMaxLength and GeneratePhotonSegmentChance. These variables work together to control the behavior of the photon segment system for volumetric lighting.

Developers should be aware that enabling this feature (setting it to true) can have significant performance and memory implications. As noted in a comment, “Currently costs too much memory and queries are too slow to be a net positive.” This suggests that the feature may not be suitable for all projects or hardware configurations.

Best practices when using this variable include:

  1. Carefully consider the performance implications before enabling it.
  2. If enabled, experiment with the related settings (PhotonSegmentMaxLength and GeneratePhotonSegmentChance) to find the best balance between quality and performance.
  3. Test the lighting results and performance thoroughly on target hardware when making changes to this setting.
  4. Consider leaving this feature disabled unless there’s a specific need for improved volumetric lighting that outweighs the performance cost.
  5. If using this feature, ensure that there’s sufficient memory available, especially for large or complex scenes.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("IrradiancePhotonSearchConeAngle"), IrradiancePhotonSearchConeAngle, GLightmassIni));
		Scene.PhotonMappingSettings.MinCosIrradiancePhotonSearchCone = FMath::Cos((90.0f - FMath::Clamp(IrradiancePhotonSearchConeAngle, 1.0f, 90.0f)) * (float)PI / 180.0f);
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bUsePhotonSegmentsForVolumeLighting"), Scene.PhotonMappingSettings.bUsePhotonSegmentsForVolumeLighting, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("PhotonSegmentMaxLength"), Scene.PhotonMappingSettings.PhotonSegmentMaxLength, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("GeneratePhotonSegmentChance"), Scene.PhotonMappingSettings.GeneratePhotonSegmentChance, GLightmassIni));
	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.IrradianceCache"), TEXT("bAllowIrradianceCaching"), bConfigBool, GLightmassIni));
		Scene.IrradianceCachingSettings.bAllowIrradianceCaching = bConfigBool;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:27

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::GatherVolumeImportancePhotonDirections

Source code excerpt:

	bool bDebugThisSample) const
{
	if (GeneralSettings.NumIndirectLightingBounces > 0 && PhotonMappingSettings.bUsePhotonMapping && PhotonMappingSettings.bUsePhotonSegmentsForVolumeLighting)
	{
		TArray<FPhotonSegmentElement> FoundPhotonSegments;
		// Gather nearby first bounce photons, which give an estimate of the first bounce incident radiance function,
		// Which we can use to importance sample the real first bounce incident radiance function.
		// See the "Extended Photon Map Implementation" paper.

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:768

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotons

Source code excerpt:

			}

			if (PhotonMappingSettings.bUsePhotonSegmentsForVolumeLighting)
			{
				for (int32 PhotonIndex = 0; PhotonIndex < CurrentOutput.FirstBounceEscapedPhotons.Num(); PhotonIndex++)
				{
					FirstBounceEscapedPhotonMap.AddElement(FPhotonElement(CurrentOutput.FirstBounceEscapedPhotons[PhotonIndex]));
				}
			}

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:808

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotons

Source code excerpt:

	FirstBouncePhotonSegmentMap = FPhotonSegmentOctree(ImportanceBounds.Origin, ImportanceBounds.BoxExtent.GetMax());

	if (PhotonMappingSettings.bUsePhotonSegmentsForVolumeLighting)
	{
		const double SegmentStartTime = FPlatformTime::Seconds();
		BuildPhotonSegmentMap(FirstBouncePhotonMap, FirstBouncePhotonSegmentMap, PhotonMappingSettings.GeneratePhotonSegmentChance);
		BuildPhotonSegmentMap(FirstBounceEscapedPhotonMap, FirstBouncePhotonSegmentMap, 1.0f);
		const float BuildSegmentMapTime = (float)(FPlatformTime::Seconds() - SegmentStartTime);
		LogSolverMessage(FString::Printf(TEXT("Built photon segment map in %.1f seconds"), BuildSegmentMapTime));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1191

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotonsWorkRange

Source code excerpt:

		if (!PathIntersection.bIntersects 
			&& NumberOfPathVertices == 1 
			&& PhotonMappingSettings.bUsePhotonSegmentsForVolumeLighting)
		{
			if (RandomStream.GetFraction() < PhotonMappingSettings.GeneratePhotonSegmentChance)
			{
				// Apply transmission
				PathAlpha *= PathIntersection.Transmission;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:

	 * Currently costs too much memory and queries are too slow to be a net positive.
	 */
	bool bUsePhotonSegmentsForVolumeLighting;

	/** Maximum world space length of segments that photons are split into for volumetric queries. */
	float PhotonSegmentMaxLength;

	/** Probability that a first bounce photon will be put into the photon segment map for volumetric queries. */
	float GeneratePhotonSegmentChance;