PhotonSegmentMaxLength

PhotonSegmentMaxLength

#Overview

name: PhotonSegmentMaxLength

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 PhotonSegmentMaxLength is to control the maximum world space length of segments that photons are split into for volumetric queries in Unreal Engine’s lighting system. This setting is specifically used in the photon mapping process, which is a part of the global illumination system.

This setting variable is primarily used by the Lightmass subsystem, which is responsible for precomputed lighting in Unreal Engine. It’s referenced in both the editor-side code (UnrealEd module) and the Lightmass standalone application.

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

PhotonSegmentMaxLength interacts with other photon mapping settings, such as bUsePhotonSegmentsForVolumeLighting and GeneratePhotonSegmentChance. These settings collectively control how photons are processed and stored for volumetric lighting calculations.

Developers must be aware that this setting directly affects the precision and memory usage of volumetric lighting calculations. A smaller PhotonSegmentMaxLength will result in more precise volumetric lighting but will increase memory usage and potentially processing time.

Best practices when using this variable include:

  1. Balancing between quality and performance by adjusting the value based on the scene’s scale and lighting complexity.
  2. Using it in conjunction with other photon mapping settings for optimal results.
  3. Testing different values to find the best trade-off between lighting quality and performance for your specific project.
  4. Documenting the chosen value and its impact on the project’s lighting to ensure consistency across the development team.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.IrradianceCache"), TEXT("bUseIrradianceGradients"), bConfigBool, GLightmassIni));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::BuildPhotonSegmentMap

Source code excerpt:

			if (AddToSegmentMapChance >= 1 || RandomStream.GetFraction() < AddToSegmentMapChance)
			{
				const int32 NumSegments = FMath::DivideAndRoundUp(PhotonElement.Photon.GetDistance(), PhotonMappingSettings.PhotonSegmentMaxLength);
				const float InvNumSegments = 1.0f / NumSegments;

				for (int32 SegmentIndex = 0; SegmentIndex < NumSegments; SegmentIndex++)
				{
					FPhotonSegmentElement NewElement(&PhotonElement.Photon, SegmentIndex * InvNumSegments, InvNumSegments);
					OutPhotonSegementMap.AddElement(NewElement);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:


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

/** Settings controlling irradiance caching behavior. */