bVisualizePhotonImportanceSamples

bVisualizePhotonImportanceSamples

#Overview

name: bVisualizePhotonImportanceSamples

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 bVisualizePhotonImportanceSamples is to enable visualization of photon importance samples in the Unreal Engine’s lighting system, specifically for the photon mapping process in static lighting calculations.

This setting variable is primarily used in the Lightmass subsystem, which is responsible for global illumination and static lighting calculations in Unreal Engine. It is part of the photon mapping settings within the static lighting system.

The value of this variable is set through the Lightmass configuration file (GLightmassIni). It is read from the configuration file in the FLightmassExporter::WriteSceneSettings function in Lightmass.cpp.

This variable interacts with other photon mapping settings, such as bUsePhotonMapping and bVisualizePhotonGathers. It is often used in conjunction with these variables to control the debugging visualization of the photon mapping process.

Developers must be aware that this is primarily a debugging tool. When enabled, it will affect the visualization of the lighting system, but not the actual lighting calculations. It’s useful for understanding how the photon importance sampling is working in the scene.

Best practices for using this variable include:

  1. Only enable it during development and debugging phases, not in production builds.
  2. Use it in conjunction with other visualization tools to get a comprehensive understanding of the photon mapping process.
  3. Be aware that enabling this visualization may impact performance, so it should be used judiciously.
  4. When using this setting, also consider adjusting related settings like bVisualizePhotonGathers for a more complete picture of the photon mapping process.

#Setting Variables

#References In INI files

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

Scope (from outer to inner):

file
function     void FLightmassExporter::WriteSceneSettings

Source code excerpt:

		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;
		VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bEmitPhotonsOutsideImportanceVolume"), bConfigBool, GLightmassIni));
		Scene.PhotonMappingSettings.bEmitPhotonsOutsideImportanceVolume = bConfigBool;
		VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.PhotonMapping"), TEXT("ConeFilterConstant"), Scene.PhotonMappingSettings.ConeFilterConstant, GLightmassIni));
		VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.PhotonMapping"), TEXT("NumIrradianceCalculationPhotons"), Scene.PhotonMappingSettings.NumIrradianceCalculationPhotons, GLightmassIni));

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:437

Scope (from outer to inner):

file
function     FLinearColor FStaticLightingSystem::FinalGatherSample

Source code excerpt:

						GatherClassification,
						MappingContext, 
						bDebugThisTexel && (!PhotonMappingSettings.bUsePhotonMapping || !PhotonMappingSettings.bVisualizePhotonImportanceSamples));

					checkSlow(FLinearColorUtils::AreFloatsValid(PathVertexOutgoingRadiance));
					Lighting += PathVertexOutgoingRadiance;

#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
					if (PathVertexOutgoingRadiance.R > DELTA || PathVertexOutgoingRadiance.G > DELTA || PathVertexOutgoingRadiance.B > DELTA)

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:485

Scope (from outer to inner):

file
namespace    Lightmass
function     FLinearColor FStaticLightingSystem::FinalGatherSample

Source code excerpt:

	if (bDebugThisTexel
		&& GeneralSettings.ViewSingleBounceNumber == BounceNumber
		&& (!PhotonMappingSettings.bUsePhotonMapping || !PhotonMappingSettings.bVisualizePhotonImportanceSamples))
	{
		FDebugStaticLightingRay DebugRay(PathRay.Start, PathRay.End, RayIntersection.bIntersects, bPositiveSample != 0);
		if (RayIntersection.bIntersects)
		{
			DebugRay.End = RayIntersection.IntersectionVertex.WorldPosition;
		}

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:1656

Scope: file

Source code excerpt:

						if (bDebugThisTexel 
							&& GeneralSettings.ViewSingleBounceNumber == BounceNumber
							&& (!PhotonMappingSettings.bUsePhotonMapping || !PhotonMappingSettings.bVisualizePhotonImportanceSamples))
						{
							FDebugStaticLightingRay DebugRay(TexelRay.Start, TexelRay.End, Intersection.bIntersects, false);
							if (Intersection.bIntersects)
							{
								DebugRay.End = Intersection.IntersectionVertex.WorldPosition;
							}

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

Scope (from outer to inner):

file
namespace    Lightmass
class        class FPhotonMappingSettings

Source code excerpt:

	 * Note that when irradiance caching is enabled, rays will only be gathered if the selected texel created an irradiance cache sample.
	 */
	bool bVisualizePhotonImportanceSamples;

	/** 
	 * Debugging - whether to gather and draw photon map octree nodes that get traversed during the irradiance calculation for the irradiance photon nearest to the select position.
	 * Which photon map search the nodes come from depends on ViewSingleBounceNumber.
	 */
	bool bVisualizeIrradiancePhotonCalculation;