bUseZeroAreaLightmapSpaceFilteredLights

bUseZeroAreaLightmapSpaceFilteredLights

#Overview

name: bUseZeroAreaLightmapSpaceFilteredLights

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 bUseZeroAreaLightmapSpaceFilteredLights is to control the shadow calculation method in Unreal Engine’s lightmapping system. It is specifically used for static shadows in the lighting and rendering subsystem.

This setting variable is primarily used by the Lightmass module, which is responsible for global illumination and static lighting calculations in Unreal Engine. It’s referenced in both the UnrealEd module (for exporting scene settings) and the UnrealLightmass program (for actual lightmap generation).

The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the [DevOptions.StaticShadows] section of this INI file.

This variable interacts with other shadow-related settings such as NumShadowRays, NumPenumbraShadowRays, and NumBounceShadowRays. It’s part of the FStaticShadowSettings struct, which encapsulates various shadow calculation parameters.

Developers must be aware that when this variable is set to true, it changes the shadow calculation method. Instead of calculating area shadows, it computes direct lighting from lights as if they have no area and then applies filtering in texture space to create approximate penumbras. This can be faster but may result in less accurate shadows.

Best practices when using this variable include:

  1. Use it primarily for performance optimization in scenes with many lights or complex geometry.
  2. Test the visual quality difference between enabled and disabled states to ensure the approximation is acceptable for your project.
  3. Consider disabling it for final quality renders or in areas where shadow accuracy is crucial.
  4. Remember that this is a global setting affecting all static shadows in the scene.
  5. Always balance between performance gain and visual quality when adjusting this setting.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

	}
	{
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bUseZeroAreaLightmapSpaceFilteredLights"), bConfigBool, GLightmassIni));
		Scene.ShadowSettings.bUseZeroAreaLightmapSpaceFilteredLights = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumShadowRays"), Scene.ShadowSettings.NumShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumPenumbraShadowRays"), Scene.ShadowSettings.NumPenumbraShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticShadows"), TEXT("NumBounceShadowRays"), Scene.ShadowSettings.NumBounceShadowRays, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticShadows"), TEXT("bFilterShadowFactor"), bConfigBool, GLightmassIni));
		Scene.ShadowSettings.bFilterShadowFactor = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticShadows"), TEXT("ShadowFactorGradientTolerance"), Scene.ShadowSettings.ShadowFactorGradientTolerance, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:795

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::ProcessTextureMapping

Source code excerpt:

				}

				if ( ShadowSettings.bUseZeroAreaLightmapSpaceFilteredLights)
				{
					// Calculate direct lighting from lights as if they have no area, and then filter in texture space to create approximate penumbras.
					CalculateDirectLightingTextureMappingFiltered(TextureMapping, MappingContext, LightMapData, ShadowMaps, TexelToVertexMap, bDebugThisMapping, Light);
				}
				else 
				{

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FStaticShadowSettings

Source code excerpt:

public:
	/** Debugging - Whether to filter a single shadow sample per texel in texture space instead of calculating area shadows. */
	bool bUseZeroAreaLightmapSpaceFilteredLights;

	/** Number of shadow rays to trace to each area light for each texel. */
	int32 NumShadowRays;

	/** Number of shadow rays to trace to each area light once a texel has been determined to lie in a shadow penumbra. */
	int32 NumPenumbraShadowRays;