SurfaceLightmapMinTexelsPerVoxelAxis

SurfaceLightmapMinTexelsPerVoxelAxis

#Overview

name: SurfaceLightmapMinTexelsPerVoxelAxis

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

#Summary

#Usage in the C++ source code

The purpose of SurfaceLightmapMinTexelsPerVoxelAxis is to control the refinement of the volumetric lightmap based on the surface lightmap resolution. It is used in the lighting system, specifically for volumetric lightmap generation in Unreal Engine 5.

This setting variable is primarily used by the Lightmass subsystem, which is responsible for global illumination and lightmap generation in Unreal Engine. It is utilized in both the editor (UnrealEd) and the standalone Lightmass program.

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It is read from the “DevOptions.VolumetricLightmaps” section of the config file using the GConfig system.

SurfaceLightmapMinTexelsPerVoxelAxis interacts with other volumetric lightmap settings, such as BrickSize and VoxelizationCellExpansionForSurfaceGeometry. It is used to calculate a threshold for surface lightmap density, which in turn affects the voxelization process.

Developers must be aware that this variable directly impacts the detail level of volumetric lightmaps. A higher value will result in more refined lightmaps but may increase memory usage and baking time. Conversely, a lower value might lead to less accurate lighting but faster baking times.

Best practices when using this variable include:

  1. Balancing it with other lightmap settings to achieve the desired quality and performance.
  2. Adjusting it based on the scale and detail of your scene.
  3. Testing different values to find the optimal setting for your specific project.
  4. Considering the target platform’s capabilities when setting this value, as higher values may impact runtime performance on less powerful devices.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	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;

	float Smoothing = FMath::Clamp(WorldInfoSettings.VolumetricLightmapSphericalHarmonicSmoothing, SMALL_NUMBER, 1000.0f);

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

Scope (from outer to inner):

file
namespace    Lightmass
function     bool FStaticLightingSystem::DoesVoxelIntersectSceneGeometry

Source code excerpt:

{
	const float Child2dTriangleArea = .5f * CellBounds.GetSize().X * CellBounds.GetSize().Y / (VolumetricLightmapSettings.BrickSize * VolumetricLightmapSettings.BrickSize);
	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)
	{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumetricLightmapSettings

Source code excerpt:


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

	/** Whether to cull bricks entirely below landscape.  This can be an invalid optimization if the landscape has holes and caves that pass under landscape. */
	bool bCullBricksBelowLandscape;

	/** Subdivide bricks when a static point or spot light affects some part of the brick with brightness higher than this. */
	float LightBrightnessSubdivideThreshold;