MaxImportancePhotonSearchDistance

MaxImportancePhotonSearchDistance

#Overview

name: MaxImportancePhotonSearchDistance

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

#Summary

#Usage in the C++ source code

The purpose of MaxImportancePhotonSearchDistance is to define the maximum distance for searching importance photons in Unreal Engine 5’s lighting system, specifically for the Lightmass global illumination solution.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for precomputed lighting in Unreal Engine. It’s part of the photon mapping settings used for global illumination calculations.

The value of this variable is set through the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.PhotonMapping” section of the config file using the GConfig system.

MaxImportancePhotonSearchDistance interacts with other photon mapping settings, particularly:

  1. MinImportancePhotonSearchDistance
  2. NumImportanceSearchPhotons

These variables work together to control the photon search process for importance sampling in the global illumination calculations.

Developers should be aware that:

  1. This variable directly affects the quality and performance of global illumination calculations.
  2. It’s scaled by the StaticLightingLevelScale, which means it adapts to the overall scale of the level.
  3. The value is used in both the editor (for exporting scene settings) and in the Lightmass program itself.

Best practices when using this variable include:

  1. Balancing it with MinImportancePhotonSearchDistance for optimal performance and quality.
  2. Adjusting it based on the scale of your level and the desired quality of indirect lighting.
  3. Using it in conjunction with other Lightmass settings to fine-tune the global illumination results.
  4. Testing different values to find the optimal balance between quality and build time for your specific scene.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("IndirectPhotonEmitConeAngle"), IndirectPhotonEmitConeAngleDegrees, GLightmassIni));
		Scene.PhotonMappingSettings.IndirectPhotonEmitConeAngle = FMath::Clamp(IndirectPhotonEmitConeAngleDegrees, 0.0f, 90.0f) * (float)PI / 180.0f;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("MaxImportancePhotonSearchDistance"), Scene.PhotonMappingSettings.MaxImportancePhotonSearchDistance, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("MinImportancePhotonSearchDistance"), Scene.PhotonMappingSettings.MinImportancePhotonSearchDistance, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PhotonMapping"), TEXT("NumImportanceSearchPhotons"), Scene.PhotonMappingSettings.NumImportanceSearchPhotons, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("OutsideImportanceVolumeDensityScale"), Scene.PhotonMappingSettings.OutsideImportanceVolumeDensityScale, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("DirectPhotonDensity"), Scene.PhotonMappingSettings.DirectPhotonDensity, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("DirectIrradiancePhotonDensity"), Scene.PhotonMappingSettings.DirectIrradiancePhotonDensity, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("DirectPhotonSearchDistance"), Scene.PhotonMappingSettings.DirectPhotonSearchDistance, GLightmassIni));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::ApplyStaticLightingScale

Source code excerpt:

	/*
	PhotonMappingSettings.IndirectPhotonEmitDiskRadius *= SceneConstants.StaticLightingLevelScale;
	PhotonMappingSettings.MaxImportancePhotonSearchDistance *= SceneConstants.StaticLightingLevelScale;
	PhotonMappingSettings.MinImportancePhotonSearchDistance *= SceneConstants.StaticLightingLevelScale;
	// Scale surface densities in world units
	const float ScaleSquared = SceneConstants.StaticLightingLevelScale * SceneConstants.StaticLightingLevelScale;
	PhotonMappingSettings.DirectPhotonDensity /= ScaleSquared;
	PhotonMappingSettings.DirectIrradiancePhotonDensity /= ScaleSquared;
	PhotonMappingSettings.DirectPhotonSearchDistance *= SceneConstants.StaticLightingLevelScale;
	PhotonMappingSettings.IndirectPhotonPathDensity /= ScaleSquared;
	PhotonMappingSettings.IndirectPhotonDensity /= ScaleSquared;
	PhotonMappingSettings.IndirectIrradiancePhotonDensity /= ScaleSquared;
	PhotonMappingSettings.IndirectPhotonSearchDistance *= SceneConstants.StaticLightingLevelScale;
	*/
}

//----------------------------------------------------------------------------
//	Light base class
//----------------------------------------------------------------------------
void FLight::Import( FLightmassImporter& Importer )
{
	Importer.ImportData( (FLightData*)this );

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::GatherVolumeImportancePhotonDirections

Source code excerpt:

			PhotonMappingSettings.NumImportanceSearchPhotons, 
			PhotonMappingSettings.MinImportancePhotonSearchDistance, 
			PhotonMappingSettings.MaxImportancePhotonSearchDistance, 
			FoundPhotonSegments,
			bDebugThisSample);

		FirstHemisphereImportancePhotonDirections.Empty(FoundPhotonSegments.Num());
		SecondHemisphereImportancePhotonDirections.Empty(FoundPhotonSegments.Num());

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FFinalGatherSample FStaticLightingSystem::CachePointIncomingRadiance

Source code excerpt:

						PhotonMappingSettings.NumImportanceSearchPhotons, 
						PhotonMappingSettings.MinImportancePhotonSearchDistance, 
						PhotonMappingSettings.MaxImportancePhotonSearchDistance, 
						bDebugThisTexel, 
						false,
						FoundPhotons,
						DummyStats);

					MappingContext.Stats.TotalFoundImportancePhotons += FoundPhotons.Num();

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:


	/** Maximum distance to search for importance photons. */
	float MaxImportancePhotonSearchDistance;

	/** 
	 * Distance to start searching for importance photons at. 
	 * For some scenes a small start distance (relative to MaxImportancePhotonSearchDistance) will speed up the search
	 * Since it can early out once enough photons are found.  For other scenes a small start distance will just cause redundant photon map searches.
	 */
	float MinImportancePhotonSearchDistance;

	/** Number of importance photons to find at each irradiance cache sample that will be used to guide the final gather. */
	int32 NumImportanceSearchPhotons;

	/** Scales the density at which to gather photons outside of the importance volume, if one exists. */
	float OutsideImportanceVolumeDensityScale;