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:
- Adjust it based on the scale and complexity of your scene. Larger, more complex scenes might benefit from a higher number of buckets.
- Consider the available computational resources when setting this value. More buckets allow for more parallel processing but require more memory.
- Test different values to find the optimal balance between performance and memory usage for your specific project.
- Keep in mind that changing this value will affect the precomputed visibility calculations, so you may need to rebuild lighting after adjusting it.
- 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]
- INI Section:
DevOptions.PrecomputedVisibility
- Raw value:
800
- 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: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;