MaxRecordRadius

MaxRecordRadius

#Overview

name: MaxRecordRadius

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 MaxRecordRadius is to control the maximum size of irradiance cache records in Unreal Engine 5’s lighting system. It is specifically used in the static lighting and global illumination calculations.

This setting variable is primarily used by the Lightmass subsystem, which is responsible for precomputing static lighting in Unreal Engine. It’s particularly relevant to the irradiance caching feature, which is an optimization technique used in global illumination calculations.

The value of this variable is typically set in the Lightmass configuration file (GLightmassIni). It’s read from the config file in the FLightmassExporter::WriteSceneSettings function in Lightmass.cpp.

MaxRecordRadius interacts with other irradiance caching settings, such as RecordRadiusScale. It’s also affected by the StaticLightingLevelScale, which scales the MaxRecordRadius value based on the level’s scale.

Developers must be aware that this variable directly impacts the trade-off between lighting quality and performance. A larger MaxRecordRadius can potentially improve performance by allowing larger cache records, but may reduce the accuracy of fine lighting details.

Best practices when using this variable include:

  1. Adjusting it in conjunction with other irradiance caching settings for optimal results.
  2. Being mindful of the level’s scale, as it affects the effective maximum radius.
  3. Testing different values to find the right balance between performance and lighting quality for your specific scene.
  4. Considering the smallest important lighting detail in your scene when setting this value, to ensure that important lighting variations are not smoothed out.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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));
	}

	// Modify settings based on the quality level required
	// Preview is assumed to have a scale of 1 for all settings and therefore is not in the ini

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/LightmassScene.cpp:527

Scope (from outer to inner):

file
namespace    Lightmass
function     void FScene::ApplyStaticLightingScale

Source code excerpt:

	ShadowSettings.StaticShadowDepthMapTransitionSampleDistanceY *= SceneConstants.StaticLightingLevelScale;
	IrradianceCachingSettings.RecordRadiusScale *= SceneConstants.StaticLightingLevelScale;
	IrradianceCachingSettings.MaxRecordRadius *= SceneConstants.StaticLightingLevelScale;

	// Photon mapping does not scale down properly, so this is disabled
	/*
	PhotonMappingSettings.IndirectPhotonEmitDiskRadius *= SceneConstants.StaticLightingLevelScale;
	PhotonMappingSettings.MaxImportancePhotonSearchDistance *= SceneConstants.StaticLightingLevelScale;
	PhotonMappingSettings.MinImportancePhotonSearchDistance *= SceneConstants.StaticLightingLevelScale;

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

Scope (from outer to inner):

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

Source code excerpt:

		{
			// Clamp to be larger than the texel
			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/Public/SceneExport.h:759

Scope (from outer to inner):

file
namespace    Lightmass
class        class FIrradianceCachingSettings

Source code excerpt:


	/** Largest radius an irradiance cache record can have. */
	float MaxRecordRadius;

	/** 
	 * Task size for parallelization of irradiance cache population within a mapping.  A mapping will be split into pieces of this size which allows other threads to help.
	 * Smaller settings result in more redundant irradiance cache samples, but allow better parallelization.
	 * Setting this to a large value like 4096 will effectively make the irradiance caching single threaded for a given mapping, which is useful for debugging.
	 */