MaxVolumeSamples

MaxVolumeSamples

#Overview

name: MaxVolumeSamples

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 MaxVolumeSamples is to limit the number of volume samples generated for precomputed dynamic object lighting in Unreal Engine 5. This setting is primarily used in the lighting and rendering system, specifically for the Lightmass system which handles global illumination calculations.

This setting variable is utilized by the Unreal Engine’s Lightmass subsystem, which is responsible for precomputed lighting calculations. It’s specifically used in the precomputed dynamic object lighting module.

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

MaxVolumeSamples interacts with other variables such as VolumeLightSampleSpacing and EffectiveVolumeSpacing. If the number of requested volume samples exceeds MaxVolumeSamples, the EffectiveVolumeSpacing is adjusted to limit the total number of samples to MaxVolumeSamples.

Developers must be aware that this variable directly impacts memory usage and computation time for lighting calculations. Setting it too high may lead to excessive memory consumption and longer build times, while setting it too low might result in lower quality lighting for dynamic objects.

Best practices when using this variable include:

  1. Balancing it with the size of your level and the desired lighting quality.
  2. Monitoring memory usage and build times when adjusting this value.
  3. Consider the relationship between this variable and VolumeLightSampleSpacing for optimal results.
  4. Test different values to find the sweet spot between performance and lighting quality for your specific project.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("DetailVolumeSampleSpacing"), Scene.DynamicObjectSettings.DetailVolumeSampleSpacing, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("VolumeLightSampleSpacing"), Scene.DynamicObjectSettings.VolumeLightSampleSpacing, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedDynamicObjectLighting"), TEXT("MaxVolumeSamples"), Scene.DynamicObjectSettings.MaxVolumeSamples, GLightmassIni));
		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;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::BeginCalculateVolumeSamples

Source code excerpt:

		float EffectiveVolumeSpacing = DynamicObjectSettings.VolumeLightSampleSpacing;

		// Clamp the number of volume samples generated to DynamicObjectSettings.MaxVolumeSamples if necessary by resizing EffectiveVolumeSpacing
		if (RequestedVolumeSamples > DynamicObjectSettings.MaxVolumeSamples)
		{
			EffectiveVolumeSpacing = FMath::Pow(8.0f * float(VolumeBounds.BoxExtent.X * VolumeBounds.BoxExtent.Y * VolumeBounds.BoxExtent.Z / DynamicObjectSettings.MaxVolumeSamples), .3333333f);		// LWC_TODO: Precision loss - float cast
		}
			
		int32 NumUniformVolumeSamples = 0;
		// Generate samples in a uniform 3d grid inside the importance volume.  These will be used for low resolution lighting in unimportant areas.
		for (float SampleX = VolumeBounds.Origin.X - VolumeBounds.BoxExtent.X; SampleX < VolumeBounds.Origin.X + VolumeBounds.BoxExtent.X + EffectiveVolumeSpacing; SampleX += EffectiveVolumeSpacing)
		{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FDynamicObjectSettings

Source code excerpt:

	float VolumeLightSampleSpacing;
	/** Maximum samples placed in the 3d volume, used to limit memory usage. */
	int32 MaxVolumeSamples;
	/** Use Maximum number restriction for Surface Light Sample. */
	bool bUseMaxSurfaceSampleNum;
	/** Maximum samples placed in the surface light sample(only for Landscape currently), used to limit memory usage. */
	int32 MaxSurfaceLightSamples;
};