MaxHemisphereRayAngle

MaxHemisphereRayAngle

#Overview

name: MaxHemisphereRayAngle

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

#Summary

#Usage in the C++ source code

The purpose of MaxHemisphereRayAngle is to control the maximum angle of hemisphere rays used in importance tracing for lighting calculations in Unreal Engine’s Lightmass system. This setting is primarily used for the rendering system, specifically for global illumination and lightmap generation.

This setting variable is relied upon by the Lightmass module, which is responsible for precalculating global illumination and generating lightmaps for static lighting in Unreal Engine. It is used within the UnrealLightmass program and the Lightmass exporter in the UnrealEd module.

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

MaxHemisphereRayAngle interacts with other importance tracing settings, such as NumAdaptiveRefinementLevels, AdaptiveBrightnessThreshold, and AdaptiveFirstBouncePhotonConeAngle. These settings collectively control the behavior of the importance tracing algorithm used in Lightmass.

Developers must be aware that this variable is specified in degrees in the configuration file but is converted to radians when used in the actual calculations. The conversion happens in the FLightmassExporter::WriteSceneSettings function.

Best practices when using this variable include:

  1. Carefully adjusting its value to balance between accuracy and performance. A smaller angle may provide more accurate results but at the cost of increased computation time.
  2. Consider the geometry of your scenes when setting this value. Scenes with many flat surfaces might benefit from a slightly smaller angle to prevent self-intersection artifacts.
  3. Always test the impact of changes to this setting on both lighting quality and build times, as it can significantly affect both.
  4. Use this setting in conjunction with other importance tracing settings for optimal results.
  5. Document any custom values used for this setting in your project to ensure consistency across team members and builds.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.ImportanceTracing"), TEXT("NumAdaptiveRefinementLevels"), Scene.ImportanceTracingSettings.NumAdaptiveRefinementLevels, GLightmassIni));
		float MaxHemisphereAngleDegrees;
		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));

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ValidateSettings
function     void FStaticLightingSystem::CacheSamples

Source code excerpt:

		for (int32 SampleIndex = 0; SampleIndex < NumUniformHemisphereSamples; SampleIndex++)
		{
			const FVector4f& CurrentSample = GetUniformHemisphereVector(RandomStream, ImportanceTracingSettings.MaxHemisphereRayAngle);
			CachedHemisphereSamples.Add(CurrentSample);
		}
	}

	{
		FVector4f CombinedVector(0);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FImportanceTracingSettings

Source code excerpt:

	 * Useful for preventing rays nearly perpendicular to the normal which may self intersect a flat surface due to imprecision in the normal.
	 */
	float MaxHemisphereRayAngle;

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