bCullBricksBelowLandscape

bCullBricksBelowLandscape

#Overview

name: bCullBricksBelowLandscape

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 bCullBricksBelowLandscape is to optimize the volumetric lightmap generation process by culling (removing) bricks that are entirely below the landscape in a scene. This setting is part of the lighting and rendering system in Unreal Engine 5, specifically for volumetric lightmaps.

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

The value of this variable is set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.VolumetricLightmaps” section. It’s read using the GConfig system in the FLightmassExporter::SetVolumetricLightmapSettings function.

This variable interacts with other volumetric lightmap settings, such as MinBrickError, SurfaceLightmapMinTexelsPerVoxelAxis, and LightBrightnessSubdivideThreshold. It’s also used in conjunction with the LandscapeMappings array and the Scene.GeneralSettings.bUseFastVoxelization flag.

Developers must be aware that while this optimization can improve performance, it may lead to incorrect lighting in scenes where there are holes or caves passing under the landscape. The comment in the code explicitly mentions this limitation.

Best practices when using this variable include:

  1. Carefully consider the scene geometry before enabling this option. If your scene has any underground structures or caves, it’s best to leave this disabled.
  2. Test the lighting results thoroughly with this option both enabled and disabled to ensure no lighting artifacts are introduced.
  3. Use this in combination with other volumetric lightmap settings to achieve the best balance between performance and quality.
  4. Be aware that this setting may need to be adjusted when making significant changes to landscape geometry in the scene.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::SetVolumetricLightmapSettings

Source code excerpt:

	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);
	OutSettings.WindowingTargetLaplacian = 1.0f / Smoothing;

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

Scope (from outer to inner):

file
namespace    Lightmass
function     bool FStaticLightingSystem::ShouldRefineVoxel

Source code excerpt:

	if (bVoxelIntersectsScene 
		&& LandscapeMappings.Num() > 0
		&& 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))

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FVolumetricLightmapSettings

Source code excerpt:


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

	/** Maximum desired curvature in the lighting stored in Volumetric Lightmaps, used to reduce Spherical Harmonic ringing via a windowing filter. */
	float WindowingTargetLaplacian;