bVisualizePhotonGathers
bVisualizePhotonGathers
#Overview
name: bVisualizePhotonGathers
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 8 C++ source files.
#Summary
#Usage in the C++ source code
The purpose of bVisualizePhotonGathers is to enable visualization of photon gathering during the lightmapping process in Unreal Engine 5. This setting is primarily used for debugging and development purposes in the photon mapping system, which is part of the global illumination and lighting calculations.
This setting variable is primarily used in the Lightmass subsystem, which is responsible for precomputed lighting in Unreal Engine. It is referenced in both the UnrealEd module (for exporting scene settings) and the UnrealLightmass program (for the actual lighting calculations).
The value of this variable is set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.PhotonMapping” section. It is read during the scene export process in the FLightmassExporter::WriteSceneSettings function.
bVisualizePhotonGathers interacts with other debugging variables related to photon mapping, such as bVisualizePhotonPaths, bVisualizePhotonImportanceSamples, and bVisualizeIrradiancePhotonCalculation. These variables collectively control various aspects of photon mapping visualization.
Developers must be aware that this variable is intended for debugging purposes only and should not be enabled in production builds. Enabling this visualization can have a performance impact and may produce additional visual artifacts that are not part of the final lighting solution.
Best practices when using this variable include:
- Only enable it when actively debugging photon mapping issues.
- Use it in conjunction with other photon mapping visualization tools for a comprehensive understanding of the lighting calculations.
- Disable it before finalizing lighting builds for production use.
- Be prepared for potential performance impacts when this visualization is enabled.
- Use this visualization to identify issues with photon distribution, gathering, and importance sampling in complex lighting scenarios.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:173, section: [DevOptions.PhotonMapping]
- INI Section:
DevOptions.PhotonMapping - Raw value:
True - Is Array:
False
#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:2359
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
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;
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bEmitPhotonsOutsideImportanceVolume"), bConfigBool, GLightmassIni));
Scene.PhotonMappingSettings.bEmitPhotonsOutsideImportanceVolume = bConfigBool;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1703
Scope (from outer to inner):
file
namespace Lightmass
function bool FStaticLightingSystem::FindAnyNearbyPhoton
Source code excerpt:
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugThisLookup
&& PhotonMappingSettings.bVisualizePhotonGathers
&& &PhotonMap == &DirectPhotonMap)
{
StartupDebugOutput.bDirectPhotonValid = true;
StartupDebugOutput.GatheredDirectPhoton = FDebugPhoton(PhotonElement.Photon.GetId(), PhotonElement.Photon.GetPosition(), PhotonElement.Photon.GetIncidentDirection(), PhotonElement.Photon.GetSurfaceNormal());
}
#endif
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1863
Scope (from outer to inner):
file
namespace Lightmass
function float FStaticLightingSystem::FindNearbyPhotonsIterative
Source code excerpt:
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugSearchProcess || bDebugSearchResults && PhotonMappingSettings.bVisualizePhotonGathers)
{
// Assuming that only importance photons are debugged and enforce the search number
if (bDebugSearchResults && bEnforceSearchNumber)
{
for (int32 i = 0; i < FoundPhotons.Num(); i++)
{
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1991
Scope (from outer to inner):
file
namespace Lightmass
function float FStaticLightingSystem::FindNearbyPhotonsInVolumeIterative
Source code excerpt:
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugThisLookup && PhotonMappingSettings.bVisualizePhotonGathers)
{
for (int32 i = 0; i < FoundPhotonSegments.Num(); i++)
{
const FPhoton& Photon = *FoundPhotonSegments[i].Photon;
StartupDebugOutput.GatheredImportancePhotons.Add(FDebugPhoton(Photon.GetId(), Photon.GetPosition(), Photon.GetIncidentDirection(), Photon.GetSurfaceNormal()));
}
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:2171
Scope (from outer to inner):
file
namespace Lightmass
function float FStaticLightingSystem::FindNearbyPhotonsSorted
Source code excerpt:
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugSearchProcess || bDebugSearchResults && PhotonMappingSettings.bVisualizePhotonGathers)
{
// Assuming that only importance photons are debugged
if (bDebugSearchResults)
{
for (int32 i = 0; i < FoundPhotons.Num(); i++)
{
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:2315
Scope (from outer to inner):
file
namespace Lightmass
function FIrradiancePhoton* FStaticLightingSystem::FindNearestIrradiancePhoton
Source code excerpt:
MappingContext.Stats.IrradiancePhotonSearchRayTime += MappingContext.RayCache.BooleanRayTraceTime - PreviousShadowTraceTime;
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugThisLookup && PhotonMappingSettings.bVisualizePhotonGathers)
{
FDebugStaticLightingRay DebugRay(VertexToPhotonRay.Start, VertexToPhotonRay.End, Intersection.bIntersects);
if (Intersection.bIntersects)
{
DebugRay.End = Intersection.IntersectionVertex.WorldPosition;
}
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:2335
Scope (from outer to inner):
file
namespace Lightmass
function FIrradiancePhoton* FStaticLightingSystem::FindNearestIrradiancePhoton
Source code excerpt:
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugThisLookup && ClosestPhoton != NULL && PhotonMappingSettings.bVisualizePhotonGathers)
{
StartupDebugOutput.GatheredPhotons.Add(FDebugPhoton(0, ClosestPhoton->GetPosition(), ClosestPhoton->GetSurfaceNormal(), ClosestPhoton->GetSurfaceNormal()));
}
#endif
return ClosestPhoton;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:605
Scope (from outer to inner):
file
namespace Lightmass
class class FPhotonMappingSettings
Source code excerpt:
* This includes importance, irradiance and direct photons.
*/
bool bVisualizePhotonGathers;
/**
* Debugging - whether to draw lines in the editor showing where rays were traced due to importance photons from the selected texel.
* If this is false, lines will be drawn for the rays traced with uniform hemisphere sampling instead.
* Note that when irradiance caching is enabled, rays will only be gathered if the selected texel created an irradiance cache sample.
*/