ConeFilterConstant

ConeFilterConstant

#Overview

name: ConeFilterConstant

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

#Summary

#Usage in the C++ source code

The purpose of ConeFilterConstant is to control the falloff of the filter applied to photon density estimations in Unreal Engine’s global illumination system, specifically in the photon mapping process.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for pre-computed lighting and global illumination calculations in Unreal Engine. It is part of the photon mapping settings, which are crucial for generating high-quality indirect lighting in static scenes.

The value of this variable is typically set in the Lightmass configuration file (GLightmassIni). It is read from the configuration file in the FLightmassExporter::WriteSceneSettings function, which is part of the Unreal Editor’s Lightmass exporter.

ConeFilterConstant interacts with other photon mapping settings, such as the number of photons emitted, search distance, and disk area calculations. It is used in various calculations related to photon irradiance, incident radiance, and exitant radiance.

Developers must be aware that this variable directly affects the quality and performance of the photon mapping process. A higher value will result in a smoother, but potentially less accurate, lighting result, while a lower value will produce more accurate but potentially noisier results.

Best practices when using this variable include:

  1. Keeping it above 1.0 (as enforced in the ValidateSettings function).
  2. Adjusting it in conjunction with other photon mapping settings for optimal results.
  3. Testing different values to find the right balance between lighting quality and performance for your specific scene.
  4. Being cautious when modifying it, as it can significantly impact the overall lighting quality and build times.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bEmitPhotonsOutsideImportanceVolume"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bEmitPhotonsOutsideImportanceVolume = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("ConeFilterConstant"), Scene.PhotonMappingSettings.ConeFilterConstant, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PhotonMapping"), TEXT("NumIrradianceCalculationPhotons"), Scene.PhotonMappingSettings.NumIrradianceCalculationPhotons, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("FinalGatherImportanceSampleFraction"), Scene.PhotonMappingSettings.FinalGatherImportanceSampleFraction, GLightmassIni));
		float FinalGatherImportanceSampleConeAngle;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("FinalGatherImportanceSampleConeAngle"), FinalGatherImportanceSampleConeAngle, GLightmassIni));
		Scene.PhotonMappingSettings.FinalGatherImportanceSampleCosConeAngle = FMath::Cos(FMath::Clamp(FinalGatherImportanceSampleConeAngle, 0.0f, 90.0f) * (float)PI / 180.0f);
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("IndirectPhotonEmitDiskRadius"), Scene.PhotonMappingSettings.IndirectPhotonEmitDiskRadius, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:924

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings

Source code excerpt:

	}

	InScene.PhotonMappingSettings.ConeFilterConstant = FMath::Max(InScene.PhotonMappingSettings.ConeFilterConstant, 1.0f);
	if (!InScene.IrradianceCachingSettings.bAllowIrradianceCaching)
	{
		InScene.IrradianceCachingSettings.bUseIrradianceGradients = false;
	}

	if (InScene.IrradianceCachingSettings.bUseIrradianceGradients)

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FLinearColor FStaticLightingSystem::CalculatePhotonIrradiance

Source code excerpt:

		// Estimate the photon density using a cone filter, from the paper "Global Illumination using Photon Maps"
		const float DiskArea = (float)PI * MaxFoundDistanceSquared;
		const float ConeFilterNormalizeConstant = 1.0f - 2.0f / (3.0f * PhotonMappingSettings.ConeFilterConstant);
		const float ConstantWeight = 1.0f / (ConeFilterNormalizeConstant * NumPhotonsEmitted * DiskArea);
		FCoherentRayCache UnusedRayCache;

		for (int32 PhotonIndex = 0; PhotonIndex < TempFoundPhotons.Num(); PhotonIndex++)
		{
			const FPhoton& CurrentPhoton = TempFoundPhotons[PhotonIndex];

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

Scope (from outer to inner):

file
function     FLinearColor FStaticLightingSystem::CalculatePhotonIrradiance

Source code excerpt:

				{
					const float PhotonDistance = (CurrentPhoton.GetPosition() - IrradiancePhoton.GetPosition()).Size3();
					const float ConeWeight = FMath::Max(1.0f - PhotonDistance / (PhotonMappingSettings.ConeFilterConstant * MaxFoundDistance), 0.0f);
					PhotonIrradiance += CurrentPhoton.GetPower() * ConeWeight * ConstantWeight;
				}
			}
		}
	}
	return PhotonIrradiance;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FGatheredLightSample FStaticLightingSystem::CalculatePhotonIncidentRadiance

Source code excerpt:

		// Estimate the photon density using a cone filter, from the paper "Global Illumination using Photon Maps"
		const float DiskArea = (float)PI * SearchDistance * SearchDistance;
		const float ConeFilterNormalizeConstant = 1.0f - 2.0f / (3.0f * PhotonMappingSettings.ConeFilterConstant);
		const float ConstantWeight = 1.0f / (ConeFilterNormalizeConstant * NumPhotonsEmitted * DiskArea);
		for (int32 PhotonIndex = 0; PhotonIndex < FoundPhotons.Num(); PhotonIndex++)
		{
			const FPhoton& CurrentPhoton = FoundPhotons[PhotonIndex];
			const FVector4f TangentPathDirection = Vertex.TransformWorldVectorToTangent(CurrentPhoton.GetIncidentDirection());
			if (TangentPathDirection.Z > 0)
			{
				const float PhotonDistance = (CurrentPhoton.GetPosition() - Vertex.WorldPosition).Size3();
				const float ConeWeight = FMath::Max(1.0f - PhotonDistance / (PhotonMappingSettings.ConeFilterConstant * SearchDistance), 0.0f);
				PhotonIncidentRadiance.AddWeighted(FGatheredLightSampleUtil::PointLightWorldSpace<2>(CurrentPhoton.GetPower(), TangentPathDirection, CurrentPhoton.GetIncidentDirection()), ConeWeight * ConstantWeight);
			}
		}
	}
	
	return PhotonIncidentRadiance;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     FLinearColor FStaticLightingSystem::CalculatePhotonExitantRadiance

Source code excerpt:

		// Estimate the photon density using a cone filter, from the paper "Global Illumination using Photon Maps"
		const float DiskArea = (float)PI * SearchDistance * SearchDistance;
		const float ConeFilterNormalizeConstant = 1.0f - 2.0f / (3.0f * PhotonMappingSettings.ConeFilterConstant);
		const float ConstantWeight = 1.0f / (ConeFilterNormalizeConstant * NumPhotonsEmitted * DiskArea);
		for (int32 PhotonIndex = 0; PhotonIndex < FoundPhotons.Num(); PhotonIndex++)
		{
			const FPhoton& CurrentPhoton = FoundPhotons[PhotonIndex];
			if (Dot3(Vertex.WorldTangentZ, CurrentPhoton.GetIncidentDirection()) > 0.0f)
			{
				const float PhotonDistance = (CurrentPhoton.GetPosition() - Vertex.WorldPosition).Size3();
				const float ConeWeight = FMath::Max(1.0f - PhotonDistance / (PhotonMappingSettings.ConeFilterConstant * SearchDistance), 0.0f);
				const FLinearColor BRDF = Mesh->EvaluateBRDF(Vertex, ElementIndex, CurrentPhoton.GetIncidentDirection(), OutgoingDirection);
				AccumulatedRadiance += CurrentPhoton.GetPower() * ConeWeight * ConstantWeight * BRDF;
			}
		}
	}
	return AccumulatedRadiance;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:


	/** Cone filter constant, which characterizes the falloff of the filter applied to photon density estimations. */
	float ConeFilterConstant;

	/** Number of photons to find in each photon map when calculating irradiance for an irradiance photon. */
	int32 NumIrradianceCalculationPhotons;

	/** 
	 * Fraction of NumHemisphereSamples to use for importance sampling instead of uniform sampling the final gather.