NumImportanceSamples

NumImportanceSamples

#Overview

name: NumImportanceSamples

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 NumImportanceSamples is to control the number of importance sampling rays used in precomputed visibility calculations for Unreal Engine’s lightmass system. This setting is specifically used to improve visibility detection through small cracks or openings that may have been missed by the initial sampling process.

This variable is primarily used in the Lightmass subsystem, which is responsible for offline lighting calculations in Unreal Engine. It’s particularly relevant to the precomputed visibility feature, which is used to optimize rendering performance by determining which objects are potentially visible from different locations in the scene.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.PrecomputedVisibility” section of this configuration file.

NumImportanceSamples interacts with other variables in the PrecomputedVisibilitySettings struct, such as MaxMeshSamples and NumCellSamples. These variables work together to determine the overall sampling strategy for visibility calculations.

Developers should be aware that increasing NumImportanceSamples can improve the accuracy of visibility detection, especially for complex geometry with small openings. However, it also increases computation time for lightmass calculations. Therefore, it’s important to balance accuracy with performance needs.

Best practices when using this variable include:

  1. Start with the default value and only increase it if you notice visibility issues in your scenes, particularly with small openings or distant objects.
  2. Consider the complexity of your scene geometry when adjusting this value. More complex scenes with many small details might benefit from higher values.
  3. Always test the impact on lightmass calculation time when changing this value, as it can significantly affect build times for large scenes.
  4. Use in conjunction with other PrecomputedVisibilitySettings to achieve the best balance of accuracy and performance for your specific project needs.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedVisibility"), TEXT("MaxMeshSamples"), Scene.PrecomputedVisibilitySettings.MaxMeshSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedVisibility"), TEXT("NumCellSamples"), Scene.PrecomputedVisibilitySettings.NumCellSamples, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedVisibility"), TEXT("NumImportanceSamples"), Scene.PrecomputedVisibilitySettings.NumImportanceSamples, GLightmassIni));
	}
	if (World->GetWorldSettings()->VisibilityAggressiveness != VIS_LeastAggressive)
	{
		const TCHAR* AggressivenessSectionNames[VIS_Max] = {
			TEXT(""), 
			TEXT("DevOptions.PrecomputedVisibilityModeratelyAggressive"),

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PrecomputedVisibility.cpp:924

Scope (from outer to inner):

file
namespace    Lightmass
function     bool ComputeBoxVisibility

Source code excerpt:

			// Trace importance sampled rays to try and find visible meshes through small cracks
			// This is only slightly effective, but doesn't cost much compared to explicit sampling due to the small number of rays
			for (int32 ImportanceSampleIndex = 0; ImportanceSampleIndex < PrecomputedVisibilitySettings.NumImportanceSamples && !bVisible && FurthestSamples.Num() > 0; ImportanceSampleIndex++)
			{
				// Pick one of the furthest samples with uniform probability
				const int32 SampleIndex = FMath::TruncToInt(RandomStream.GetFraction() * FurthestSamples.Num());
				const FVisibilityQuerySample& CurrentSample = *FurthestSamples[SampleIndex];
				const float VectorLength = (CurrentSample.CellPosition - CurrentSample.MeshPosition).Size3();
				const FVector4f CurrentDirection = (CurrentSample.MeshPosition - CurrentSample.CellPosition).GetSafeNormal();

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPrecomputedVisibilitySettings

Source code excerpt:


	/** Number of samples to use when importance sampling each cell - mesh query. */
	int32 NumImportanceSamples;
};

/** Settings for volume distance field generation. */
class FVolumeDistanceFieldSettings
{
public: