MaxSurfaceLightSamples

MaxSurfaceLightSamples

#Overview

name: MaxSurfaceLightSamples

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 MaxSurfaceLightSamples is to control the maximum number of light samples placed on surfaces, particularly for landscapes, in Unreal Engine’s lightmass system. This setting is used to limit memory usage during the precomputed lighting process.

This setting variable is primarily used by the Lightmass system, which is part of Unreal Engine’s global illumination and precomputed lighting solution. It’s referenced in both the editor-side code (UnrealEd module) and the Lightmass standalone program.

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

MaxSurfaceLightSamples interacts with several other variables:

  1. bUseMaxSurfaceSampleNum: A boolean that determines whether to use the MaxSurfaceLightSamples limit.
  2. SurfaceLightSampleSpacing: The spacing between light samples on surfaces.
  3. NumSurfaceSampleLayers: The number of layers of surface samples.

Developers should be aware that:

  1. This setting primarily affects landscapes currently.
  2. If the estimated number of light samples exceeds MaxSurfaceLightSamples, the SurfaceLightSampleSpacing is automatically increased to reduce the number of samples.
  3. The actual number of samples is influenced by the landscape size and the SurfaceLightSampleSpacing.

Best practices when using this variable include:

  1. Set it high enough to ensure adequate lighting quality for your landscapes, but not so high that it causes excessive memory usage.
  2. Monitor the Lightmass log for messages about SurfaceLightSampleSpacing being increased, which indicates that MaxSurfaceLightSamples was exceeded.
  3. Balance this setting with SurfaceLightSampleSpacing to achieve the desired trade-off between lighting quality and memory usage/build time.
  4. Consider the scale of your landscapes when setting this value, as larger landscapes will require more samples for the same level of detail.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("bUseMaxSurfaceSampleNum"), bConfigBool, GLightmassIni));
		Scene.DynamicObjectSettings.bUseMaxSurfaceSampleNum = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("MaxSurfaceLightSamples"), Scene.DynamicObjectSettings.MaxSurfaceLightSamples, GLightmassIni));

		Scene.DynamicObjectSettings.SurfaceLightSampleSpacing *= LevelSettings.VolumeLightSamplePlacementScale;
		Scene.DynamicObjectSettings.VolumeLightSampleSpacing *= LevelSettings.VolumeLightSamplePlacementScale;
		Scene.DynamicObjectSettings.DetailVolumeSampleSpacing *= LevelSettings.VolumeLightSamplePlacementScale;
	}
	{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/SampleVolume.cpp:247

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::BeginCalculateVolumeSamples

Source code excerpt:

		float LandscapeEstimateNum = 0.f;
		// Estimate Light sample number near Landscape surfaces
		if (DynamicObjectSettings.bUseMaxSurfaceSampleNum && DynamicObjectSettings.MaxSurfaceLightSamples > 100)
		{
			float SquaredSpacing = FMath::Square(DynamicObjectSettings.SurfaceLightSampleSpacing);
			if (SquaredSpacing == 0.f) SquaredSpacing = 1.0f;
			for (int32 MappingIndex = 0; MappingIndex < LandscapeMappings.Num(); MappingIndex++)
			{
				FStaticLightingVertex Vertices[3];

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/SampleVolume.cpp:269

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::BeginCalculateVolumeSamples

Source code excerpt:

			LandscapeEstimateNum *= DynamicObjectSettings.NumSurfaceSampleLayers;

			if (LandscapeEstimateNum > DynamicObjectSettings.MaxSurfaceLightSamples)
			{
				// Increase DynamicObjectSettings.SurfaceLightSampleSpacing to reduce light sample number
				float OldMaxSurfaceLightSamples = DynamicObjectSettings.SurfaceLightSampleSpacing;
				DynamicObjectSettings.SurfaceLightSampleSpacing = DynamicObjectSettings.SurfaceLightSampleSpacing * FMath::Sqrt((float)LandscapeEstimateNum / DynamicObjectSettings.MaxSurfaceLightSamples);
				UE_LOG(LogLightmass, Log, TEXT("Too many LightSamples : DynamicObjectSettings.SurfaceLightSampleSpacing is increased from %g to %g"), OldMaxSurfaceLightSamples, DynamicObjectSettings.SurfaceLightSampleSpacing);
				LandscapeEstimateNum = DynamicObjectSettings.MaxSurfaceLightSamples;
			}
		}

		//@todo - can this be presized more accurately?
		VolumeLightingSamples.Empty(FMath::Max<int32>(5000, LandscapeEstimateNum));
		FStaticLightingMappingContext MappingContext(nullptr, *this);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FDynamicObjectSettings

Source code excerpt:

	bool bUseMaxSurfaceSampleNum;
	/** Maximum samples placed in the surface light sample(only for Landscape currently), used to limit memory usage. */
	int32 MaxSurfaceLightSamples;
};

/** Settings for the volumetric lightmap. */
class FVolumetricLightmapSettings
{
public: