bUseFastVoxelization
bUseFastVoxelization
#Overview
name: bUseFastVoxelization
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 11 C++ source files.
#Summary
#Usage in the C++ source code
The purpose of bUseFastVoxelization is to enable faster voxelization for volumetric lightmaps using kDOP (k-Discrete Oriented Polytope) trees. This setting is particularly useful in large scenes like forests where it can significantly accelerate the voxelization process.
This setting variable is primarily used by the Unreal Engine’s lightmass system, which is responsible for static lighting calculations. It’s part of the static lighting settings and affects how the engine processes volumetric lightmaps.
The value of this variable is typically set in the lighting build options or project settings. It can be configured per-project or even per-level basis, depending on the specific needs of the scene.
This variable interacts closely with other volumetric lightmap settings and general lighting settings. For example, it’s often used in conjunction with bUseEmbreeInstancing, which is another optimization technique for large scenes.
Developers should be aware that while this setting can greatly improve performance in large scenes, it may not provide significant benefits or could even introduce overhead in smaller scenes. Therefore, it’s important to profile and test the impact of this setting on a per-project basis.
Best practices when using this variable include:
- Enable it for large outdoor scenes, especially those with many trees or complex foliage.
- Consider disabling it for smaller, more contained indoor scenes where the overhead might outweigh the benefits.
- Always test the lighting build times and quality with this setting both on and off to determine the optimal configuration for your specific scene.
- Use in combination with other optimizations like bUseEmbreeInstancing for maximum benefit in large scenes.
- Monitor memory usage, as faster voxelization might come at the cost of increased memory consumption.
Overall, bUseFastVoxelization is a powerful tool for optimizing volumetric lightmap generation in large scenes, but its use should be carefully considered and tested for each project.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:33, section: [DevOptions.StaticLighting]
- INI Section:
DevOptions.StaticLighting - Raw value:
false - 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:2140
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
Scene.GeneralSettings.bVerifyEmbree = Scene.GeneralSettings.bUseEmbree && bConfigBool;
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbreePacketTracing"), Scene.GeneralSettings.bUseEmbreePacketTracing, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseFastVoxelization"), Scene.GeneralSettings.bUseFastVoxelization, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLighting"), TEXT("bUseEmbreeInstancing"), Scene.GeneralSettings.bUseEmbreeInstancing, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLighting"), TEXT("MappingSurfaceCacheDownsampleFactor"), Scene.GeneralSettings.MappingSurfaceCacheDownsampleFactor, GLightmassIni));
int32 CheckQualityLevel;
GConfig->GetInt( TEXT("LightingBuildOptions"), TEXT("QualityLevel"), CheckQualityLevel, GEditorPerProjectIni);
CheckQualityLevel = FMath::Clamp<int32>(CheckQualityLevel, Quality_Preview, Quality_Production);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/AdaptiveVolumetricLightmap.cpp:135
Scope (from outer to inner):
file
namespace Lightmass
function bool FStaticLightingSystem::DoesVoxelIntersectSceneGeometry
Source code excerpt:
const FBox3f ExpandedCellBoundsVolumeGeometry = CellBounds.ExpandBy(CellBounds.GetSize() * VolumetricLightmapSettings.VoxelizationCellExpansionForVolumeGeometry);
if (Scene.GeneralSettings.bUseFastVoxelization)
{
const FStaticLightingMesh* Mesh = nullptr;
Mesh = VoxelizationSurfaceAggregateMesh->IntersectBox(ExpandedCellBoundsSurfaceGeometry);
if (Mesh != nullptr)
{
OutIntersectingLevelGuid = Mesh->LevelGuid;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/AdaptiveVolumetricLightmap.cpp:349
Scope (from outer to inner):
file
namespace Lightmass
function bool FStaticLightingSystem::ShouldRefineVoxel
Source code excerpt:
&& VolumetricLightmapSettings.bCullBricksBelowLandscape)
{
if (Scene.GeneralSettings.bUseFastVoxelization)
{
FBox3f StretchedCellBounds(CellBounds.Min, FVector3f(CellBounds.Max.X, CellBounds.Max.Y, LandscapeCullingVoxelizationAggregateMesh->GetBounds().Max.Z));
if (LandscapeCullingVoxelizationAggregateMesh->IntersectBox(StretchedCellBounds) && !LandscapeCullingVoxelizationAggregateMesh->IntersectBox(CellBounds))
{
return false;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:365
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::FStaticLightingSystem
Source code excerpt:
AggregateMesh->ReserveMemory(NumMeshes, NumVertices, NumTriangles);
if (Scene.GeneralSettings.bUseFastVoxelization)
{
VoxelizationSurfaceAggregateMesh = new FDefaultAggregateMesh(Scene);
VoxelizationVolumeAggregateMesh = new FDefaultAggregateMesh(Scene);
LandscapeCullingVoxelizationAggregateMesh = new FDefaultAggregateMesh(Scene);
}
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:377
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::FStaticLightingSystem
Source code excerpt:
AggregateMesh->AddMesh(Mapping->Mesh, Mapping);
if (Scene.GeneralSettings.bUseFastVoxelization)
{
if (Mapping->GetVolumeMapping() == nullptr)
{
VoxelizationSurfaceAggregateMesh->AddMeshForVoxelization(Mapping->Mesh, Mapping);
}
else
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:394
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::FStaticLightingSystem
Source code excerpt:
AggregateMesh->AddMesh(Mapping->Mesh, Mapping);
if (Scene.GeneralSettings.bUseFastVoxelization)
{
if (Mapping->GetVolumeMapping() == nullptr)
{
VoxelizationSurfaceAggregateMesh->AddMeshForVoxelization(Mapping->Mesh, Mapping);
}
else
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:413
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::FStaticLightingSystem
Source code excerpt:
AggregateMesh->AddMesh(BSPMapping, &BSPMapping->Mapping);
if (Scene.GeneralSettings.bUseFastVoxelization)
{
if (BSPMapping->Mapping.GetVolumeMapping() == nullptr)
{
VoxelizationSurfaceAggregateMesh->AddMeshForVoxelization(BSPMapping, &BSPMapping->Mapping);
}
else
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:430
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::FStaticLightingSystem
Source code excerpt:
AggregateMesh->AddMesh(MeshInstance, MeshInstance->Mapping);
if (Scene.GeneralSettings.bUseFastVoxelization)
{
if (MeshInstance->GetInstanceableStaticMesh() != nullptr)
{
if (MeshInstance->StaticMesh->VoxelizationMesh == nullptr)
{
if (MeshInstance->LightingFlags & GI_INSTANCE_CASTSHADOW && MeshInstance->DoesMeshBelongToLOD0())
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:552
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::FStaticLightingSystem
Source code excerpt:
AggregateMesh->DumpStats();
if (Scene.GeneralSettings.bUseFastVoxelization)
{
VoxelizationSurfaceAggregateMesh->PrepareForRaytracing();
VoxelizationVolumeAggregateMesh->PrepareForRaytracing();
LandscapeCullingVoxelizationAggregateMesh->PrepareForRaytracing();
}
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:575
Scope (from outer to inner):
file
namespace Lightmass
function FStaticLightingSystem::~FStaticLightingSystem
Source code excerpt:
AggregateMesh = NULL;
if (Scene.GeneralSettings.bUseFastVoxelization)
{
delete VoxelizationSurfaceAggregateMesh;
VoxelizationSurfaceAggregateMesh = NULL;
delete VoxelizationVolumeAggregateMesh;
VoxelizationVolumeAggregateMesh = NULL;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:73
Scope (from outer to inner):
file
namespace Lightmass
class class FStaticLightingSettings
Source code excerpt:
/** Whether to use kDOP trees to accelerate volumetric lightmap voxelization. Useful in scenes like large forest. */
bool bUseFastVoxelization;
/** Whether to use static mesh instancing to reduce memory consumption in scenes like large forest. Might slow down small scenes. */
bool bUseEmbreeInstancing;
/**
* Direct lighting, skylight radiosity and irradiance photons are cached on mapping surfaces to accelerate final gathering.