NumCellDistributionBuckets

NumCellDistributionBuckets

#Overview

name: NumCellDistributionBuckets

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 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of NumCellDistributionBuckets is to control the distribution of visibility cells for precomputed visibility calculations in Unreal Engine 5. This setting is primarily used in the lighting and visibility systems of the engine.

The Unreal Engine subsystems that rely on this setting variable are primarily the lighting system, specifically the Lightmass module, which handles global illumination and precomputed visibility. It’s also used in the UnrealEd module for exporting scene settings.

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.

NumCellDistributionBuckets interacts with other visibility-related variables such as VisibilityCellSize, PlayAreaHeight, MeshBoundsScale, and various sample count settings (MinMeshSamples, MaxMeshSamples, NumCellSamples, NumImportanceSamples).

Developers must be aware that this variable affects the distribution of precomputed visibility calculations. It determines how the visibility cells are split up into tasks for processing. A higher number of buckets could lead to more granular distribution of work but might increase overhead.

Best practices when using this variable include:

  1. Adjust it based on the scale and complexity of your scene. Larger, more complex scenes might benefit from a higher number of buckets.
  2. Consider the available computational resources when setting this value. More buckets allow for more parallel processing but require more memory.
  3. Test different values to find the optimal balance between performance and memory usage for your specific project.
  4. Keep in mind that changing this value will affect the precomputed visibility calculations, so you may need to rebuild lighting after adjusting it.
  5. Document any changes to this setting in your project to maintain consistency across the development team.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		Scene.PrecomputedVisibilitySettings.bPlaceCellsOnlyAlongCameraTracks = World->GetWorldSettings()->bPlaceCellsOnlyAlongCameraTracks;
		Scene.PrecomputedVisibilitySettings.CellSize = World->GetWorldSettings()->VisibilityCellSize;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedVisibility"), TEXT("NumCellDistributionBuckets"), Scene.PrecomputedVisibilitySettings.NumCellDistributionBuckets, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedVisibility"), TEXT("PlayAreaHeight"), Scene.PrecomputedVisibilitySettings.PlayAreaHeight, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PrecomputedVisibility"), TEXT("MeshBoundsScale"), Scene.PrecomputedVisibilitySettings.MeshBoundsScale, GLightmassIni));
		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));

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2765

Scope (from outer to inner):

file
function     void FLightmassProcessor::InitiateExport

Source code excerpt:

	double StartTime = FPlatformTime::Seconds();

	int32 NumCellDistributionBuckets;
	VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PrecomputedVisibility"), TEXT("NumCellDistributionBuckets"), NumCellDistributionBuckets, GLightmassIni));
	
	for ( int32 LevelIndex=0; LevelIndex < System.GetWorld()->GetNumLevels(); LevelIndex++ )
	{
		ULevel* Level = System.GetWorld()->GetLevel(LevelIndex);
		FGuid LevelGuid = FGuid(0,0,0,LevelIndex);
		Exporter->LevelGuids.Add(LevelGuid, Level);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2779

Scope (from outer to inner):

file
function     void FLightmassProcessor::InitiateExport

Source code excerpt:

	if (System.GetWorld()->GetWorldSettings()->bPrecomputeVisibility)
	{
		for (int32 DistributionBucketIndex = 0; DistributionBucketIndex < NumCellDistributionBuckets; DistributionBucketIndex++)
		{
			Exporter->VisibilityBucketGuids.Add(FGuid::NewGuid());
		}
	}

	if (System.GetWorld()->GetWorldSettings()->LightmassSettings.VolumeLightingMethod == VLM_VolumetricLightmap

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

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculatePrecomputedVisibility

Source code excerpt:

{
	const double StartTime = FPlatformTime::Seconds();
	check(BucketIndex >= 0 && BucketIndex < PrecomputedVisibilitySettings.NumCellDistributionBuckets);
	// Create a new link for the output of this task
	TList<FPrecomputedVisibilityData>* DataLink = new TList<FPrecomputedVisibilityData>(FPrecomputedVisibilityData(),NULL);
	DataLink->Element.Guid = Scene.VisibilityBucketGuids[BucketIndex];
	
	// Determine the range of cells to process from the bucket index
	const int32 StartCellIndex = BucketIndex * AllPrecomputedVisibilityCells.Num() / PrecomputedVisibilitySettings.NumCellDistributionBuckets;
	const int32 MaxCellIndex = BucketIndex + 1 == PrecomputedVisibilitySettings.NumCellDistributionBuckets ? 
		// Last bucket processes up to the end of the array
		AllPrecomputedVisibilityCells.Num() :
		(BucketIndex + 1) * AllPrecomputedVisibilityCells.Num() / PrecomputedVisibilitySettings.NumCellDistributionBuckets;

	DataLink->Element.PrecomputedVisibilityCells.Empty(MaxCellIndex - StartCellIndex);
	
	FStaticLightingMappingContext MappingContext(NULL, *this);

	// These are re-used across operations on the same thread to reduce reallocations

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPrecomputedVisibilitySettings

Source code excerpt:


	/** Number of tasks that visibility cells are being split up into. */
	int32 NumCellDistributionBuckets;

	/** World space size of visibility cells in the z dimension. */
	float PlayAreaHeight;

	/** Amount to increase the bounds of meshes when querying their visibility.  Larger scales reduce visibility errors at the cost of less effective culling. */
	float MeshBoundsScale;