AdaptiveBrightnessThreshold

AdaptiveBrightnessThreshold

#Overview

name: AdaptiveBrightnessThreshold

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

#Summary

#Usage in the C++ source code

The purpose of AdaptiveBrightnessThreshold is to control the adaptive refinement process in Unreal Engine’s lightmass system, specifically for importance tracing in global illumination calculations.

This setting variable is primarily used by the Lightmass subsystem, which is responsible for precomputed lighting and global illumination in Unreal Engine. It’s particularly relevant to the importance tracing feature, which optimizes the lighting calculation process.

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

AdaptiveBrightnessThreshold interacts with several other variables in the importance tracing settings, such as AdaptiveFirstBouncePhotonConeAngle and AdaptiveSkyVarianceThreshold. It’s also scaled by AdaptiveBrightnessThresholdScale, which is read from a quality-specific section of the configuration.

Developers should be aware that this threshold affects the refinement process in lighting calculations. A lower threshold will result in more refinement, potentially leading to higher quality lighting but at the cost of increased computation time.

Best practices when using this variable include:

  1. Adjusting it in conjunction with other importance tracing settings for optimal results.
  2. Testing different values to find the right balance between lighting quality and performance for your specific scene.
  3. Considering the scale of your scene when setting this value, as larger scenes might require different thresholds compared to smaller ones.
  4. Documenting any changes made to this setting, as it can significantly impact the final lighting results.

Remember that changes to this variable will only take effect when rebuilding lighting, so frequent adjustments may lead to increased iteration times during development.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("MaxHemisphereRayAngle"), MaxHemisphereAngleDegrees, GLightmassIni));
		Scene.ImportanceTracingSettings.MaxHemisphereRayAngle = MaxHemisphereAngleDegrees * (float)PI / 180.0f;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("AdaptiveBrightnessThreshold"), Scene.ImportanceTracingSettings.AdaptiveBrightnessThreshold, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("AdaptiveFirstBouncePhotonConeAngle"), Scene.ImportanceTracingSettings.AdaptiveFirstBouncePhotonConeAngle, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("AdaptiveSkyVarianceThreshold"), Scene.ImportanceTracingSettings.AdaptiveSkyVarianceThreshold, GLightmassIni));

		float AdaptiveFirstBouncePhotonConeAngle;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.ImportanceTracing"), TEXT("AdaptiveFirstBouncePhotonConeAngle"), AdaptiveFirstBouncePhotonConeAngle, GLightmassIni));
		Scene.ImportanceTracingSettings.AdaptiveFirstBouncePhotonConeAngle = FMath::Clamp(AdaptiveFirstBouncePhotonConeAngle, 0.0f, 90.0f) * (float)PI / 180.0f;

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		float AdaptiveBrightnessThresholdScale;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("AdaptiveBrightnessThresholdScale"), AdaptiveBrightnessThresholdScale, GLightmassIni));
		Scene.ImportanceTracingSettings.AdaptiveBrightnessThreshold = Scene.ImportanceTracingSettings.AdaptiveBrightnessThreshold * AdaptiveBrightnessThresholdScale;

		float AdaptiveFirstBouncePhotonConeAngleScale;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(QualitySectionNames[QualityLevel], TEXT("AdaptiveFirstBouncePhotonConeAngleScale"), AdaptiveFirstBouncePhotonConeAngleScale, GLightmassIni));
		Scene.ImportanceTracingSettings.AdaptiveFirstBouncePhotonConeAngle = Scene.ImportanceTracingSettings.AdaptiveFirstBouncePhotonConeAngle * AdaptiveFirstBouncePhotonConeAngleScale;

		float AdaptiveSkyVarianceThresholdScale;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FUniformHemisphereRefinementGrid
function     void RefineIncomingRadiance

Source code excerpt:

		const float ConeIntersectionWeight = 1.0f / TangentImportancePhotonDirections.Num();

		float BrightnessThreshold = LightingSystem.ImportanceTracingSettings.AdaptiveBrightnessThreshold * BrightnessThresholdScale;
		float SkyOcclusionThreshold = LightingSystem.ImportanceTracingSettings.AdaptiveBrightnessThreshold * BrightnessThresholdScale;
		bool bRefineForSkyOcclusion = LightingSystem.SkyLights.Num() > 0;
		float SkyVarianceThreshold = LightingSystem.ImportanceTracingSettings.AdaptiveSkyVarianceThreshold;

		// This is basically disabled, causes too much noise in worst case scenarios (all GI coming from small bright spot)
		float ConeWeightThreshold = .006f;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FImportanceTracingSettings

Source code excerpt:


	/** Starting threshold for what relative brightness difference causes a refinement.  At each depth the effective threshold will be reduced. */
	float AdaptiveBrightnessThreshold;

	/** Starting threshold for what angle around a first bounce photon causes a refinement on all cells affected.  At each depth the effective threshold will be reduced. */
	float AdaptiveFirstBouncePhotonConeAngle;

	float AdaptiveSkyVarianceThreshold;