VoxelizationCellExpansionForLights

VoxelizationCellExpansionForLights

#Overview

name: VoxelizationCellExpansionForLights

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 VoxelizationCellExpansionForLights is to control the expansion of voxel cells specifically for light sources in the volumetric lightmap generation process of Unreal Engine 5. This setting is part of the lighting and rendering system, particularly focused on the volumetric lightmap functionality.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for global illumination calculations in Unreal Engine. It is specifically utilized in the volumetric lightmap generation process.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It is read from the “DevOptions.VolumetricLightmaps” section with the key “VoxelizationCellExpansionForLights”.

VoxelizationCellExpansionForLights interacts with other similar variables such as VoxelizationCellExpansionForSurfaceGeometry and VoxelizationCellExpansionForVolumeGeometry. These variables collectively control how voxels are expanded for different scene elements during the voxelization process.

Developers should be aware that this variable directly affects the precision and performance of light calculations in volumetric lightmaps. A higher value will cause the voxelization process to consider lights over a larger area, potentially increasing accuracy but also increasing computation time and memory usage.

Best practices when using this variable include:

  1. Keeping the value as low as possible while still achieving desired lighting quality to optimize performance.
  2. Balancing it with other voxelization expansion settings for consistent results.
  3. Testing different values to find the optimal balance between lighting quality and performance for your specific scene.
  4. Considering the scale of your scene when setting this value, as larger scenes might require different settings compared to smaller ones.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	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));

	const FLightmassWorldInfoSettings& WorldInfoSettings = World->GetWorldSettings()->LightmassSettings;

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	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(
		FMath::TruncToInt(2 * ImportanceExtent.X / TargetDetailCellSize) + 1,
		FMath::TruncToInt(2 * ImportanceExtent.Y / TargetDetailCellSize) + 1,

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

Scope (from outer to inner):

file
namespace    Lightmass
function     bool FStaticLightingSystem::ShouldRefineVoxel

Source code excerpt:

	if (!bVoxelIntersectsScene)
	{
		const FBox3f ExpandedCellBounds = CellBounds.ExpandBy(CellBounds.GetExtent() * VolumetricLightmapSettings.VoxelizationCellExpansionForLights);
		FBoxSphereBounds3f ExpandedBoxSphereBounds(ExpandedCellBounds);

		for (int32 LightIndex = 0; LightIndex < Lights.Num() && !bVoxelIntersectsScene; LightIndex++)
		{
			const FLight* Light = Lights[LightIndex];

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumetricLightmapSettings

Source code excerpt:

	float VoxelizationCellExpansionForSurfaceGeometry;
	float VoxelizationCellExpansionForVolumeGeometry;
	float VoxelizationCellExpansionForLights;

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

	/** Triangles with fewer lightmap texels than this don't cause refinement. */
	float SurfaceLightmapMinTexelsPerVoxelAxis;