AdaptiveFirstBouncePhotonConeAngle

AdaptiveFirstBouncePhotonConeAngle

#Overview

name: AdaptiveFirstBouncePhotonConeAngle

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 AdaptiveFirstBouncePhotonConeAngle is to control the refinement of light bounces in the global illumination system of Unreal Engine 5. It is specifically used in the importance tracing settings for lightmass 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 part of the rendering system, particularly the offline lighting computation.

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

AdaptiveFirstBouncePhotonConeAngle interacts with other importance tracing settings, such as AdaptiveBrightnessThreshold and AdaptiveSkyVarianceThreshold. It’s also scaled by AdaptiveFirstBouncePhotonConeAngleScale based on the quality level settings.

Developers should be aware that this variable is measured in degrees but is converted to radians for internal use. It’s also clamped between 0 and 90 degrees to ensure valid values.

Best practices when using this variable include:

  1. Adjusting it carefully as it can significantly impact the quality and performance of lightmass calculations.
  2. Considering its interaction with other importance tracing settings for optimal results.
  3. Being mindful of the quality level settings, as they can scale this value.
  4. Understanding that smaller angles may lead to more refined calculations but also increased computation time.
  5. Testing different values to find the right balance between lighting quality and build times for your specific scene.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseRadiositySolverForSkylightMultibounce"), Scene.ImportanceTracingSettings.bUseRadiositySolverForSkylightMultibounce, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bCacheFinalGatherHitPointsForRadiosity"), Scene.ImportanceTracingSettings.bCacheFinalGatherHitPointsForRadiosity, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.ImportanceTracing"), TEXT("bUseRadiositySolverForLightMultibounce"), Scene.ImportanceTracingSettings.bUseRadiositySolverForLightMultibounce, GLightmassIni));
	}
	{

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

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

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

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FUniformHemisphereRefinementGrid
function     void RefineIncomingRadiance

Source code excerpt:


		const float InvNumHemisphereSamples = 1.0f / (NumThetaSteps * NumPhiSteps);
		float ImportanceConeAngle = LightingSystem.ImportanceTracingSettings.AdaptiveFirstBouncePhotonConeAngle;
		// Approximation for the cone angle of a root level cell
		const float RootCellAngle = PI * FMath::Sqrt((.5f / NumThetaSteps) * (.5f / NumThetaSteps) + (.5f / NumPhiSteps) * (.5f / NumPhiSteps));
		const float CosRootCellAngle = FMath::Cos(RootCellAngle);
		const float SinRootCellAngle = FMath::Sin(RootCellAngle);
		const float RootSolidAngle = 2 * PI * (1 - CosRootCellAngle);
		const float RootCombinedAngleThreshold = FMath::Cos(ImportanceConeAngle + RootCellAngle);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FImportanceTracingSettings

Source code excerpt:


	/** 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;

	/** 
	 * Whether to use radiosity iterations for solving skylight 2nd bounce and up, plus emissive 1st bounce and up. 
	 * These light sources are not represented by photons so they need to be handled separately to have multiple bounces.