bVisualizePhotonPaths

bVisualizePhotonPaths

#Overview

name: bVisualizePhotonPaths

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

#Summary

#Usage in the C++ source code

The purpose of bVisualizePhotonPaths is to enable visualization of photon paths in Unreal Engine’s lightmass system, which is part of the global illumination and lighting calculation process.

This setting variable is primarily used in the Lightmass subsystem of Unreal Engine, specifically in the photon mapping component of the static lighting system. It’s referenced in both the editor (UnrealEd) and the Lightmass program.

The value of this variable is set from the configuration file (GLightmassIni) in the “DevOptions.PhotonMapping” section. It’s read using the GConfig->GetBool() function and then assigned to the Scene.PhotonMappingSettings.bVisualizePhotonPaths field.

This variable interacts with other debug visualization settings like bVisualizePhotonGathers, bVisualizePhotonImportanceSamples, and bVisualizeIrradiancePhotonCalculation. It’s also used in conjunction with settings like bUseIrradiancePhotons, bUseFinalGathering, and ViewSingleBounceNumber to determine when and how to visualize photon paths.

Developers must be aware that this is a debugging feature and should only be enabled when needed for visualization purposes. It’s likely to have performance implications when enabled, so it should be turned off for final builds or performance-critical scenarios.

Best practices for using this variable include:

  1. Only enable it when debugging lighting issues related to photon paths.
  2. Use it in conjunction with other visualization settings to get a comprehensive view of the lighting system’s behavior.
  3. Be mindful of the performance impact when enabled.
  4. Disable it in production builds to avoid unnecessary overhead.
  5. Use it alongside the Unreal Engine’s built-in visualization tools for a better understanding of the lighting system.

#Setting Variables

#References In INI files

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

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bCacheIrradiancePhotonsOnSurfaces"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bCacheIrradiancePhotonsOnSurfaces = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bVisualizePhotonPaths"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bVisualizePhotonPaths = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bVisualizePhotonGathers"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bVisualizePhotonGathers = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bVisualizePhotonImportanceSamples"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bVisualizePhotonImportanceSamples = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bVisualizeIrradiancePhotonCalculation"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bVisualizeIrradiancePhotonCalculation = bConfigBool;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:343

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitDirectPhotons

Source code excerpt:


#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
	if (PhotonMappingSettings.bVisualizePhotonPaths)
	{
		if (GeneralSettings.ViewSingleBounceNumber < 0
			|| PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting && GeneralSettings.ViewSingleBounceNumber == 0 
			|| PhotonMappingSettings.bUseFinalGathering && GeneralSettings.ViewSingleBounceNumber == 1)
		{
			if (PhotonMappingSettings.bUseIrradiancePhotons)

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:830

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotons

Source code excerpt:


#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
	if (PhotonMappingSettings.bVisualizePhotonPaths
		&& PhotonMappingSettings.bUseIrradiancePhotons 
		&& GeneralSettings.ViewSingleBounceNumber != 0)
	{
		int32 NumIndirectIrradiancePhotons = 0;
		for (int32 RangeIndex = NumPhotonWorkRanges; RangeIndex < IrradiancePhotons.Num(); RangeIndex++)
		{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1069

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::EmitIndirectPhotonsWorkRange

Source code excerpt:


#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
					if (PhotonMappingSettings.bVisualizePhotonPaths
						&& !PhotonMappingSettings.bUseIrradiancePhotons
						&& (GeneralSettings.ViewSingleBounceNumber < 0
						|| PhotonMappingSettings.bUseFinalGathering && GeneralSettings.ViewSingleBounceNumber > 1 
						|| !PhotonMappingSettings.bUseFinalGathering && GeneralSettings.ViewSingleBounceNumber > 0))
					{
						FScopeLock DebugOutputLock(&DebugOutputSync);

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:

	 * They will only be drawn if a texel is selected and ViewSingleBounceNumber is >= 0.
	 */
	bool bVisualizePhotonPaths;

	/** 
	 * Debugging - whether to draw the photons gathered for the selected texel or the photons gathered by final gather rays from the selected texel.
	 * This includes importance, irradiance and direct photons.
	 */
	bool bVisualizePhotonGathers;