GeneratePhotonSegmentChance

GeneratePhotonSegmentChance

#Overview

name: GeneratePhotonSegmentChance

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 GeneratePhotonSegmentChance is to control the probability of generating photon segments for volumetric lighting in Unreal Engine’s lightmass system. This setting is part of the photon mapping process used in global illumination calculations.

This setting variable is primarily used in the Lightmass subsystem of Unreal Engine, which is responsible for precalculating lighting information. It’s specifically utilized in the photon mapping module for indirect lighting calculations.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the config file in the FLightmassExporter::WriteSceneSettings function in Lightmass.cpp.

GeneratePhotonSegmentChance interacts with other photon mapping settings, such as bUsePhotonSegmentsForVolumeLighting and PhotonSegmentMaxLength. It’s used in conjunction with these variables to control the generation and behavior of photon segments.

Developers must be aware that this variable directly affects the performance and quality of volumetric lighting calculations. A higher value will result in more accurate volumetric lighting but at the cost of increased computation time and memory usage.

Best practices when using this variable include:

  1. Balancing the value between performance and quality based on the specific needs of the scene.
  2. Adjusting it in conjunction with other photon mapping settings for optimal results.
  3. Testing different values to find the sweet spot for your specific scene, as the ideal value can vary depending on scene complexity and lighting conditions.
  4. Considering lowering the value for performance-critical areas or for lower-end hardware targets.
  5. Documenting the chosen value and its effects for future reference and team communication.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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));
		Scene.IrradianceCachingSettings.bUseIrradianceGradients = bConfigBool;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotons

Source code excerpt:

	{
		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));
	}

	Stats.EmitIndirectPhotonsThreadTime = FPlatformTime::Seconds() - StartEmittingIndirectPhotonsMainThread;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotonsWorkRange

Source code excerpt:

	//@todo - re-evaluate these sizes
	Output.FirstBouncePhotons.Empty(FMath::TruncToInt(WorkRange.NumIndirectPhotonsToEmit * .6f * IndirectPhotonEfficiency));
	Output.FirstBounceEscapedPhotons.Empty(FMath::TruncToInt(WorkRange.NumIndirectPhotonsToEmit * .6f * IndirectPhotonEfficiency * PhotonMappingSettings.GeneratePhotonSegmentChance));
	Output.SecondBouncePhotons.Empty(FMath::TruncToInt(WorkRange.NumIndirectPhotonsToEmit * .4f * IndirectPhotonEfficiency));
	if (PhotonMappingSettings.bUseIrradiancePhotons)
	{
		// Attempt to preallocate irradiance photons based on the percentage of photons that go into the irradiance photon map.
		// The actual number of irradiance photons is based on probability.
		Output.IrradiancePhotons->Empty(FMath::TruncToInt(IndirectIrradiancePhotonFraction * IndirectPhotonEfficiency * WorkRange.NumIndirectPhotonsToEmit));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotonsWorkRange

Source code excerpt:

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

				checkSlow(FLinearColorUtils::AreFloatsValid(PathAlpha));

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:


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

/** Settings controlling irradiance caching behavior. */
class FIrradianceCachingSettings
{
public: