bUseMaxSurfaceSampleNum

bUseMaxSurfaceSampleNum

#Overview

name: bUseMaxSurfaceSampleNum

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 bUseMaxSurfaceSampleNum is to control whether a maximum number restriction is applied to surface light samples in Unreal Engine’s lightmass system. This setting is specifically related to the lighting and rendering system, particularly for precomputed dynamic object lighting.

This setting variable is primarily used in the Lightmass subsystem of Unreal Engine, which is responsible for precalculating lighting information. It’s referenced in the UnrealEd module and the UnrealLightmass program, which are core components of Unreal Engine’s lighting pipeline.

The value of this variable is set from the configuration file (GLightmassIni) in the FLightmassExporter::WriteSceneSettings function. It’s read using the GConfig->GetBool function, suggesting it’s a boolean value stored in the engine’s configuration.

This variable interacts closely with other lighting-related variables, particularly MaxSurfaceLightSamples. When bUseMaxSurfaceSampleNum is true and MaxSurfaceLightSamples is greater than 100, it affects the calculation of volume samples, especially for landscape surfaces.

Developers must be aware that this setting primarily impacts landscape lighting calculations. It’s used to limit the number of light samples on surfaces, which can help manage memory usage and performance, especially in scenes with large landscapes.

Best practices when using this variable include:

1. Consider enabling it (setting to true) when working with large landscapes to prevent excessive memory usage.
2. Adjust the MaxSurfaceLightSamples value in conjunction with this setting to find the right balance between lighting quality and performance.
3. Be aware that changing this setting may significantly impact lighting build times and quality, so thorough testing is recommended after making changes.
4. Use this in combination with other lightmass settings to optimize the lighting pipeline for your specific project needs.

#Setting Variables

#References In INI files

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

• INI Section: DevOptions.PrecomputedDynamicObjectLighting
• Raw value: True
• Is Array: False

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;
		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/Public/SceneExport.h:326

Scope (from outer to inner):

file
namespace    Lightmass
class        class FDynamicObjectSettings

Source code excerpt:

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

/** Settings for the volumetric lightmap. */
class FVolumetricLightmapSettings