NumCellSamples

NumCellSamples

#Overview

name: NumCellSamples

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 NumCellSamples is to control the number of samples taken for each cell in the precomputed visibility system of Unreal Engine 5. This setting is primarily used for the rendering system, specifically for optimizing visibility calculations in static environments.

The Unreal Engine subsystem that relies on this setting variable is the Lightmass system, which is responsible for precomputed lighting and visibility calculations. This can be seen from the file locations where the variable is referenced, such as “UnrealLightmass/Private/Lighting/PrecomputedVisibility.cpp” and “UnrealEd/Private/Lightmass/Lightmass.cpp”.

The value of this variable is set in the configuration file, as evidenced by the GConfig->GetInt call in the Lightmass.cpp file. It’s likely stored in a section called “DevOptions.PrecomputedVisibility” with the key “NumCellSamples”.

This variable interacts with other visibility-related variables such as MinMeshSamples, MaxMeshSamples, and NumImportanceSamples. Together, these variables control the granularity and accuracy of the precomputed visibility system.

Developers must be aware that increasing NumCellSamples will improve the accuracy of visibility calculations but at the cost of increased computation time and memory usage. It’s a trade-off between performance and visual quality.

Best practices when using this variable include:

  1. Balancing it with other visibility settings for optimal performance and quality.
  2. Adjusting it based on the complexity of your scene and the target hardware.
  3. Using it in conjunction with VisibilityAggressiveness settings for fine-tuning.
  4. Testing different values to find the sweet spot for your specific project needs.
  5. Considering the impact on build times and memory usage when changing this value.

Remember that changes to this variable will require regenerating the precomputed visibility data, which can be a time-consuming process for large scenes.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedVisibility"), TEXT("MinMeshSamples"), Scene.PrecomputedVisibilitySettings.MinMeshSamples, GLightmassIni));
		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(""),

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

Scope (from outer to inner):

file
namespace    Lightmass
function     bool ComputeBoxVisibility

Source code excerpt:


		// Generate samples for explicit visibility sampling of the mesh
		for (int32 CellSampleIndex = 0; CellSampleIndex < PrecomputedVisibilitySettings.NumCellSamples; CellSampleIndex++)
		{
			for (int32 MeshSampleIndex = 0; MeshSampleIndex < NumMeshSamples; MeshSampleIndex++)
			{
				FVisibilityQuerySample NewSample;
				{
					float PDF;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     bool ComputeBoxVisibility

Source code excerpt:

		float FurthestDistanceSquared = 0;
		// Early out if any sample finds the mesh visible, unless we are debugging this cell and want to see all the samples
		for (int32 CellSampleIndex = 0; (CellSampleIndex < PrecomputedVisibilitySettings.NumCellSamples) && (!bVisible || bDebugThisCell); CellSampleIndex++)
		{
			for (int32 MeshSampleIndex = 0; MeshSampleIndex < NumMeshSamples; MeshSampleIndex++)
			{
				FVisibilityQuerySample& CurrentSample = SamplePositions[CellSampleIndex * NumMeshSamples + MeshSampleIndex];
				const FVector4f CellSamplePosition = CurrentSample.CellPosition;
				const FVector4f MeshSamplePosition = CurrentSample.MeshPosition;

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPrecomputedVisibilitySettings

Source code excerpt:


	/** Number of samples on each cell for each cell - mesh query. */
	int32 NumCellSamples;

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

/** Settings for volume distance field generation. */