DistanceSmoothFactor

DistanceSmoothFactor

#Overview

name: DistanceSmoothFactor

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 DistanceSmoothFactor is to control the smoothness of irradiance caching in Unreal Engine’s lighting system. It is specifically used to filter the irradiance on flat surfaces, affecting the quality and performance of indirect lighting calculations.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for global illumination and static lighting calculations in Unreal Engine. It is part of the IrradianceCachingSettings structure, which contains various parameters for controlling the behavior of irradiance caching.

The value of this variable is typically set in the Lightmass configuration file (GLightmassIni). It is read from the “DevOptions.IrradianceCache” section of the config file and assigned to the Scene.IrradianceCachingSettings.DistanceSmoothFactor property.

DistanceSmoothFactor interacts with other variables in the lighting system, such as:

  1. GeneralSettings.IndirectLightingSmoothness, which is used to scale the DistanceSmoothFactor.
  2. AngleSmoothFactor, which is used in conjunction with DistanceSmoothFactor to control irradiance smoothing.
  3. IrradianceCacheSmoothFactor, which is used to further scale both DistanceSmoothFactor and AngleSmoothFactor.

Developers should be aware of the following when using this variable:

  1. The value is clamped to a minimum of 1.0 in the ValidateSettings function.
  2. Increasing this value will result in smoother indirect lighting on flat surfaces but may also reduce detail and accuracy.
  3. It directly affects the interpolation radius of irradiance cache records, which impacts performance and quality.

Best practices when using this variable include:

  1. Adjusting it in small increments and observing the results, as its effects can be subtle but significant.
  2. Balancing it with AngleSmoothFactor to achieve the desired lighting quality on both flat and curved surfaces.
  3. Considering the overall performance impact, as higher values may increase the interpolation radius and potentially reduce the number of irradiance cache samples needed.
  4. Testing the settings with different types of scenes to ensure they work well across various lighting scenarios.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:215, section: [DevOptions.IrradianceCache]

#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:2408

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("InterpolationMaxAngle"), Scene.IrradianceCachingSettings.InterpolationMaxAngle, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("PointBehindRecordMaxAngle"), Scene.IrradianceCachingSettings.PointBehindRecordMaxAngle, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("DistanceSmoothFactor"), Scene.IrradianceCachingSettings.DistanceSmoothFactor, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("AngleSmoothFactor"), Scene.IrradianceCachingSettings.AngleSmoothFactor, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("SkyOcclusionSmoothnessReduction"), Scene.IrradianceCachingSettings.SkyOcclusionSmoothnessReduction, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.IrradianceCache"), TEXT("MaxRecordRadius"), Scene.IrradianceCachingSettings.MaxRecordRadius, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.IrradianceCache"), TEXT("CacheTaskSize"), Scene.IrradianceCachingSettings.CacheTaskSize, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.IrradianceCache"), TEXT("InterpolateTaskSize"), Scene.IrradianceCachingSettings.InterpolateTaskSize, GLightmassIni));
	}

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2479

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		float IrradianceCacheSmoothFactor;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("IrradianceCacheSmoothFactor"), IrradianceCacheSmoothFactor, GLightmassIni));
		Scene.IrradianceCachingSettings.DistanceSmoothFactor *= IrradianceCacheSmoothFactor;
		Scene.IrradianceCachingSettings.AngleSmoothFactor *= IrradianceCacheSmoothFactor;

		VERIFYLIGHTMASSINI(GConfig->GetInt(QualitySectionNames[QualityLevel], TEXT("NumAdaptiveRefinementLevels"), Scene.ImportanceTracingSettings.NumAdaptiveRefinementLevels, GLightmassIni));

		float AdaptiveBrightnessThresholdScale;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("AdaptiveBrightnessThresholdScale"), AdaptiveBrightnessThresholdScale, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingCache.cpp:8

Scope (from outer to inner):

file
namespace    Lightmass
function     FLightingCacheBase::FLightingCacheBase

Source code excerpt:

FLightingCacheBase::FLightingCacheBase(const FStaticLightingSystem& InSystem, int32 InBounceNumber) :
	MinCosPointBehindPlane(FMath::Cos((InSystem.IrradianceCachingSettings.PointBehindRecordMaxAngle + 90.0f) * (float)PI / 180.0f)),
	DistanceSmoothFactor(FMath::Max(InSystem.IrradianceCachingSettings.DistanceSmoothFactor * InSystem.GeneralSettings.IndirectLightingSmoothness, 1.0f)),
	bUseIrradianceGradients(InSystem.IrradianceCachingSettings.bUseIrradianceGradients),
	bShowGradientsOnly(InSystem.IrradianceCachingSettings.bShowGradientsOnly),
	bVisualizeIrradianceSamples(InSystem.IrradianceCachingSettings.bVisualizeIrradianceSamples),
	BounceNumber(InBounceNumber),
	NextRecordId(0),
	System(InSystem)

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingCache.h:129

Scope (from outer to inner):

file
namespace    Lightmass
class        class FLightingCacheBase

Source code excerpt:

	float InterpolationAngleNormalizationSmooth;
	const float MinCosPointBehindPlane;
	const float DistanceSmoothFactor;
	const bool bUseIrradianceGradients;
	const bool bShowGradientsOnly;
	const bool bVisualizeIrradianceSamples;
	const int32 BounceNumber;
	int32 NextRecordId;
	mutable FIrradianceCacheStats Stats;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingCache.h:194

Scope (from outer to inner):

file
namespace    Lightmass
class        class TLightingCache : public FLightingCacheBase
class        class FRecord
function     FRecord

Source code excerpt:

			Radius = FMath::Clamp(GatherInfo.MinDistance, SampleRadius, IrradianceCachingSettings.MaxRecordRadius) * IrradianceCachingSettings.RecordRadiusScale;
			// Use a larger radius to interpolate, which smooths the error
			InterpolationRadius = Radius * FMath::Max(IrradianceCachingSettings.DistanceSmoothFactor * GeneralSettings.IndirectLightingSmoothness, 1.0f);

			BoundingRadius = FMath::Max(Radius, InterpolationRadius);

			BackfacingHitsFraction = GatherInfo.BackfacingHitsFraction;
		}
	};

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings

Source code excerpt:

	InScene.IrradianceCachingSettings.InterpolationMaxAngle = FMath::Clamp(InScene.IrradianceCachingSettings.InterpolationMaxAngle, 0.0f, 90.0f);
	InScene.IrradianceCachingSettings.PointBehindRecordMaxAngle = FMath::Clamp(InScene.IrradianceCachingSettings.PointBehindRecordMaxAngle, 0.0f, 90.0f);
	InScene.IrradianceCachingSettings.DistanceSmoothFactor = FMath::Max(InScene.IrradianceCachingSettings.DistanceSmoothFactor, 1.0f);
	InScene.IrradianceCachingSettings.AngleSmoothFactor = FMath::Max(InScene.IrradianceCachingSettings.AngleSmoothFactor, 1.0f);
	InScene.IrradianceCachingSettings.SkyOcclusionSmoothnessReduction = FMath::Clamp(InScene.IrradianceCachingSettings.SkyOcclusionSmoothnessReduction, 0.1f, 1.0f);

	if (InScene.GeneralSettings.IndirectLightingQuality > 50)
	{
		InScene.ImportanceTracingSettings.NumAdaptiveRefinementLevels += 2;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FIrradianceCachingSettings

Source code excerpt:

	 * This effectively filters the irradiance on flat surfaces.
	 */
	float DistanceSmoothFactor;

	/** 
	 * How much to increase InterpolationMaxAngle for the shading pass. 
	 * This effectively filters the irradiance on curved surfaces.
	 */
	float AngleSmoothFactor;