PhotonSearchAngleThreshold

PhotonSearchAngleThreshold

#Overview

name: PhotonSearchAngleThreshold

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 PhotonSearchAngleThreshold is to control the photon mapping process in Unreal Engine’s global illumination system. It is used to determine which photons are valid search results during the lighting calculation process.

This setting variable is primarily used in the Lightmass subsystem, which is Unreal Engine’s global illumination and static lighting solution. It’s specifically part of the photon mapping algorithm used for indirect lighting calculations.

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

PhotonSearchAngleThreshold interacts with other photon mapping settings such as IndirectIrradiancePhotonDensity, IndirectPhotonSearchDistance, and IrradiancePhotonSearchConeAngle. It’s used in conjunction with these variables to fine-tune the photon search process.

Developers must be aware that this variable directly affects the quality and performance of the global illumination calculation. A smaller angle threshold will result in more accurate lighting but may increase computation time, while a larger threshold might speed up calculations at the cost of accuracy.

Best practices when using this variable include:

  1. Adjusting it in small increments and observing the effects on lighting quality and build times.
  2. Balancing it with other photon mapping settings for optimal results.
  3. Considering the specific lighting requirements of your scene when setting this value.
  4. Documenting any changes made to this setting for future reference and team communication.

Remember that changes to this variable will require a full lighting rebuild to take effect, which can be time-consuming for large scenes.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("IndirectIrradiancePhotonDensity"), Scene.PhotonMappingSettings.IndirectIrradiancePhotonDensity, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("IndirectPhotonSearchDistance"), Scene.PhotonMappingSettings.IndirectPhotonSearchDistance, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("PhotonSearchAngleThreshold"), Scene.PhotonMappingSettings.PhotonSearchAngleThreshold, GLightmassIni));
		float IrradiancePhotonSearchConeAngle;
		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));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     float FStaticLightingSystem::FindNearbyPhotonsIterative

Source code excerpt:

				if (DistanceSquared < FurthestPhotonDistanceSquared
					// Whose normal is within the specified angle from the search normal
					&& CosNormalTheta > PhotonMappingSettings.PhotonSearchAngleThreshold
					// And whose incident direction is in the same hemisphere as the search normal.
					&& CosIncidentDirectionTheta > 0.0f)
				{
					if (bEnforceSearchNumber)
					{
						if (FoundPhotons.Num() < NumPhotonsToFind)

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

Scope (from outer to inner):

file
namespace    Lightmass
function     float FStaticLightingSystem::FindNearbyPhotonsSorted

Source code excerpt:

				if (DistanceSquared < FurthestPhotonDistanceSquared
					// Whose normal is within the specified angle from the search normal
					&& CosNormalTheta > PhotonMappingSettings.PhotonSearchAngleThreshold
					// And whose incident direction is in the same hemisphere as the search normal.
					&& CosIncidentDirectionTheta > 0.0f)
				{
					SearchStats.NumElementsAccepted++;
					if (FoundPhotons.Num() < NumPhotonsToFind)
					{

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FIrradiancePhoton* FStaticLightingSystem::FindNearestIrradiancePhoton

Source code excerpt:


				// Only searching for irradiance photons with normals similar to the search normal
				if (CosTheta > PhotonMappingSettings.PhotonSearchAngleThreshold
					// And closer to the search position than the max search distance.
					&& ((CurrentPhoton.HasDirectContribution() && (DistanceSquared < FMath::Square(PhotonMappingSettings.DirectPhotonSearchDistance)))
					|| (!CurrentPhoton.HasDirectContribution() && (DistanceSquared < FMath::Square(PhotonMappingSettings.IndirectPhotonSearchDistance)))))
				{
					// Only accept irradiance photons within an angle of the plane defined by the vertex normal
					// This avoids expensive visibility traces to photons that are probably not on the same surface

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:


	/** Maximum cosine of the angle between the search normal and the surface normal of a candidate photon for that photon to be a valid search result. */
	float PhotonSearchAngleThreshold;

	/** Cosine of the angle from the search normal that defines a cone which irradiance photons must be outside of to be valid for that search. */
	float MinCosIrradiancePhotonSearchCone;

	/** 
	 * Whether to build a photon segment map, to guide importance sampling for volume queries.