MinBrickError

MinBrickError

#Overview

name: MinBrickError

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 MinBrickError is to control the culling of volumetric lightmap bricks in Unreal Engine 5’s lighting system. It is used as a threshold to determine which bricks should be removed from the lightmap based on their Root Mean Square Error (RMSE) value.

This setting variable is primarily used in the Unreal Engine’s lightmass system, specifically in the volumetric lightmap processing module. It is part of the FVolumetricLightmapSettings struct, which suggests it’s an important parameter for the volumetric lighting calculations.

The value of this variable is set in the Lightmass.ini configuration file, under the [DevOptions.VolumetricLightmaps] section. It is read and assigned to the OutSettings.MinBrickError in the FLightmassExporter::SetVolumetricLightmapSettings function.

MinBrickError interacts with other variables in the volumetric lightmap calculation process, particularly with the RMSE calculation of each brick. It’s used in a comparison to determine if a brick should be culled or kept.

Developers must be aware that this variable directly affects the quality and performance of volumetric lightmaps. A lower value will result in higher quality lightmaps but increased memory usage and processing time, while a higher value will reduce quality but improve performance.

Best practices when using this variable include:

  1. Carefully balancing quality and performance by adjusting the value based on the specific needs of the project.
  2. Testing different values to find the optimal setting that provides acceptable visual results without excessive memory usage.
  3. Considering the target hardware when setting this value, as it can significantly impact memory consumption.
  4. Using it in conjunction with other volumetric lightmap settings for best results.
  5. Documenting the chosen value and its effects for future reference and optimization.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseLightmass.ini:99, 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/ImportVolumetricLightmap.cpp:851

Scope (from outer to inner):

file
function     int32 TrimBricksByInterpolationError

Source code excerpt:


			const double RMSE = FMath::Sqrt((ErrorSquared * InvTotalBrickSize).GetMax());
			const bool bCullBrick = RMSE < VolumetricLightmapSettings.MinBrickError;

			if (bCullBrick)
			{
				HighestDensityBricks.RemoveAt(BrickIndex);
				BrickIndex--;
				NumBricksRemoved++;

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

Scope (from outer to inner):

file
function     void FLightmassProcessor::ImportVolumetricLightmap

Source code excerpt:

			TrimmedString += FString::Printf(TEXT(" (trimmed %.1fMb due to %f MinBrickError)"),
				NumBottomLevelBricksTrimmedByInterpolationError * ActualBrickSizeBytes / 1024.0f / 1024.0f,
				VolumetricLightmapSettings.MinBrickError);
		}

		if (NumBottomLevelBricksTrimmedForMemoryLimit > 0)
		{
			TrimmedString += FString::Printf(TEXT(" (trimmed %.1fMb due to %.1fMb MaximumBrickMemoryMb)"),
				NumBottomLevelBricksTrimmedForMemoryLimit * ActualBrickSizeBytes / 1024.0f / 1024.0f,

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	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/Programs/UnrealLightmass/Public/SceneExport.h:361

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumetricLightmapSettings

Source code excerpt:


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

	/** 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;