VoxelizationCellExpansionForSurfaceGeometry

VoxelizationCellExpansionForSurfaceGeometry

#Overview

name: VoxelizationCellExpansionForSurfaceGeometry

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 VoxelizationCellExpansionForSurfaceGeometry is to control the expansion of voxelization cells around surface geometry in Unreal Engine 5’s volumetric lightmap system. This setting is part of the lighting and rendering subsystem, specifically related to the volumetric lightmap generation process.

This setting variable is primarily used in the Lightmass module, which is responsible for global illumination and lightmap generation in Unreal Engine. It is referenced in both the editor-side code (UnrealEd) and the Lightmass program itself.

The value of this variable is set through the engine’s configuration system. It is read from the “DevOptions.VolumetricLightmaps” section of the Lightmass configuration file (GLightmassIni) using the GConfig->GetFloat function.

VoxelizationCellExpansionForSurfaceGeometry interacts with other related variables such as VoxelizationCellExpansionForVolumeGeometry and VoxelizationCellExpansionForLights. These variables work together to control the voxelization process for different types of geometry and lighting elements.

Developers must be aware that this variable directly affects the resolution and quality of volumetric lightmaps around surface geometry. Increasing this value will add more resolution around geometry, improving lighting gradients but at the cost of increased memory usage.

Best practices when using this variable include:

  1. Balancing quality and performance by adjusting the value carefully.
  2. Testing different values to find the optimal setting for your specific scene.
  3. Considering the interaction with other volumetric lightmap settings for a holistic approach to lighting quality.
  4. Monitoring memory usage when increasing this value, especially for large or complex scenes.
  5. Using the FMath::Max function to ensure the value is never negative, as seen in the code where it’s clamped to a minimum of 0.0f.

By fine-tuning this setting, developers can achieve better lighting quality in their scenes while managing the performance and memory impact of volumetric lightmaps.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.VolumetricLightmaps"), TEXT("BrickSize"), OutSettings.BrickSize, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.VolumetricLightmaps"), TEXT("MaxRefinementLevels"), OutSettings.MaxRefinementLevels, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("VoxelizationCellExpansionForSurfaceGeometry"), OutSettings.VoxelizationCellExpansionForSurfaceGeometry, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("VoxelizationCellExpansionForVolumeGeometry"), OutSettings.VoxelizationCellExpansionForVolumeGeometry, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("VoxelizationCellExpansionForLights"), OutSettings.VoxelizationCellExpansionForLights, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("MinBrickError"), OutSettings.MinBrickError, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("SurfaceLightmapMinTexelsPerVoxelAxis"), OutSettings.SurfaceLightmapMinTexelsPerVoxelAxis, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.VolumetricLightmaps"), TEXT("bCullBricksBelowLandscape"), OutSettings.bCullBricksBelowLandscape, GLightmassIni));
	VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.VolumetricLightmaps"), TEXT("LightBrightnessSubdivideThreshold"), OutSettings.LightBrightnessSubdivideThreshold, GLightmassIni));

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	OutSettings.BrickSize = FMath::RoundUpToPowerOfTwo(OutSettings.BrickSize);
	OutSettings.MaxRefinementLevels = FMath::Clamp(OutSettings.MaxRefinementLevels, 1, 6);
	OutSettings.VoxelizationCellExpansionForSurfaceGeometry = FMath::Max(OutSettings.VoxelizationCellExpansionForSurfaceGeometry, 0.0f);
	OutSettings.VoxelizationCellExpansionForVolumeGeometry = FMath::Max(OutSettings.VoxelizationCellExpansionForVolumeGeometry, 0.0f);
	OutSettings.VoxelizationCellExpansionForLights = FMath::Max(OutSettings.VoxelizationCellExpansionForLights, 0.0f);

	const float TargetDetailCellSize = WorldInfoSettings.VolumetricLightmapDetailCellSize;

	FIntVector FullGridSize(

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/AdaptiveVolumetricLightmap.cpp:132

Scope (from outer to inner):

file
namespace    Lightmass
function     bool FStaticLightingSystem::DoesVoxelIntersectSceneGeometry

Source code excerpt:

	const float SurfaceLightmapDensityThreshold = .5f * VolumetricLightmapSettings.SurfaceLightmapMinTexelsPerVoxelAxis * VolumetricLightmapSettings.SurfaceLightmapMinTexelsPerVoxelAxis / Child2dTriangleArea;

	const FBox3f ExpandedCellBoundsSurfaceGeometry = CellBounds.ExpandBy(CellBounds.GetSize() * VolumetricLightmapSettings.VoxelizationCellExpansionForSurfaceGeometry);
	const FBox3f ExpandedCellBoundsVolumeGeometry = CellBounds.ExpandBy(CellBounds.GetSize() * VolumetricLightmapSettings.VoxelizationCellExpansionForVolumeGeometry);

	if (Scene.GeneralSettings.bUseFastVoxelization)
	{
		const FStaticLightingMesh* Mesh = nullptr;
		Mesh = VoxelizationSurfaceAggregateMesh->IntersectBox(ExpandedCellBoundsSurfaceGeometry);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumetricLightmapSettings

Source code excerpt:

	 * Larger values add more resolution around geometry, improving the lighting gradients but costing more memory.
	 */
	float VoxelizationCellExpansionForSurfaceGeometry;
	float VoxelizationCellExpansionForVolumeGeometry;
	float VoxelizationCellExpansionForLights;

	/** Bricks with RMSE below this value are culled. */
	float MinBrickError;