bVisualizeCachedApproximateDirectLighting
bVisualizeCachedApproximateDirectLighting
#Overview
name: bVisualizeCachedApproximateDirectLighting
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 10
C++ source files.
#Summary
#Usage in the C++ source code
The purpose of bVisualizeCachedApproximateDirectLighting is to enable visualization of cached approximate direct lighting in Unreal Engine’s Lightmass system. This setting is primarily used for debugging and development purposes within the global illumination and photon mapping subsystems.
This setting variable is primarily used in the Lightmass module, which is responsible for global illumination calculations in Unreal Engine. It is specifically utilized in the photon mapping and static lighting systems.
The value of this variable is set in the Lightmass configuration file (GLightmassIni) under the “DevOptions.PhotonMapping” section. It is read and applied in the FLightmassExporter::WriteSceneSettings function.
This variable interacts with several other photon mapping and lighting settings, such as:
- bUsePhotonDirectLightingInFinalGather
- bUseIrradiancePhotons
- bUseFinalGathering
- NumIndirectLightingBounces
Developers should be aware that:
- This setting is primarily for debugging and should not be enabled in production builds.
- Enabling this option may impact performance, as it requires additional calculations and visualization steps.
- It affects how direct lighting is calculated and visualized, particularly in the context of final gathering and irradiance photons.
Best practices when using this variable include:
- Only enable it when actively debugging lighting issues or developing lighting-related features.
- Use it in conjunction with other debugging tools and settings to get a comprehensive view of the lighting calculations.
- Disable it before finalizing lighting builds for production to ensure optimal performance.
- Be aware of its interactions with other lighting settings to avoid unexpected results in the visualization.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:169, section: [DevOptions.PhotonMapping]
- INI Section:
DevOptions.PhotonMapping
- Raw value:
False
- 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:2351
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bUsePhotonDirectLightingInFinalGather"), bConfigBool, GLightmassIni));
Scene.PhotonMappingSettings.bUsePhotonDirectLightingInFinalGather = bConfigBool;
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bVisualizeCachedApproximateDirectLighting"), bConfigBool, GLightmassIni));
Scene.PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting = bConfigBool;
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.PhotonMapping"), TEXT("bUseIrradiancePhotons"), bConfigBool, GLightmassIni));
Scene.PhotonMappingSettings.bUseIrradiancePhotons = bConfigBool;
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;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:38
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::InitializePhotonSettings
Source code excerpt:
Stats.NumFirstPassPhotonsRequested = 0;
// Only emit direct photons if they will be used for lighting
if (GeneralSettings.NumIndirectLightingBounces > 0 || PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting)
{
for (int32 LightIndex = 0; LightIndex < Lights.Num(); LightIndex++)
{
Stats.NumFirstPassPhotonsRequested += Lights[LightIndex]->GetNumDirectPhotons(PhotonMappingSettings.DirectPhotonDensity);
}
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:346
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::EmitDirectPhotons
Source code excerpt:
{
if (GeneralSettings.ViewSingleBounceNumber < 0
|| PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting && GeneralSettings.ViewSingleBounceNumber == 0
|| PhotonMappingSettings.bUseFinalGathering && GeneralSettings.ViewSingleBounceNumber == 1)
{
if (PhotonMappingSettings.bUseIrradiancePhotons)
{
int32 NumDirectIrradiancePhotons = 0;
for (int32 ArrayIndex = 0; ArrayIndex < IrradiancePhotons.Num(); ArrayIndex++)
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1332
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::MarkIrradiancePhotonsWorkRange
Source code excerpt:
if ((PhotonMappingSettings.bUseFinalGathering && GeneralSettings.NumIndirectLightingBounces > 0)
// Or if photon mapping is being used for direct lighting.
|| PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting)
{
// Find a nearby direct photon
const bool bHasDirectContribution = FindAnyNearbyPhoton(DirectPhotonMap, CurrentIrradiancePhoton.GetPosition(), PhotonMappingSettings.DirectPhotonSearchDistance, false);
if (bHasDirectContribution)
{
// Mark the irradiance photon has having direct contribution, which will be used to reduce the search radius for this irradiance photon,
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1515
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::CalculateIrradiancePhotonsWorkRange
Source code excerpt:
if (((PhotonMappingSettings.bUseFinalGathering && GeneralSettings.NumIndirectLightingBounces > 0)
// Or if photon mapping is being used for direct lighting.
|| PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting)
&& PhotonMappingSettings.bUsePhotonDirectLightingInFinalGather)
{
const FLinearColor DirectPhotonIrradiance = CalculatePhotonIrradiance(
DirectPhotonMap,
NumPhotonsEmittedDirect,
PhotonMappingSettings.NumIrradianceCalculationPhotons,
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PhotonMapping.cpp:1534
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::CalculateIrradiancePhotonsWorkRange
Source code excerpt:
|| (PhotonMappingSettings.bUseFinalGathering && GeneralSettings.ViewSingleBounceNumber == 1)
|| (!PhotonMappingSettings.bUseFinalGathering && GeneralSettings.ViewSingleBounceNumber == 0)
|| (PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting && GeneralSettings.ViewSingleBounceNumber == 0))
{
AccumulatedIrradiance = DirectPhotonIrradiance;
}
}
// If we are final gathering, first bounce photons are actually the second lighting bounce since the final gather is the first bounce
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:669
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::FinalizeSurfaceCacheTextureMapping
Source code excerpt:
VertexOffsets.Add(FVector3f(0, 0, 0));
CalculateApproximateDirectLighting(CurrentVertex, TexelToVertex.TexelRadius, VertexOffsets, .1f, true, true, bDebugThisTexel && PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting, MappingContext, DirectLighting, Unused2);
FinalIncidentLighting += DirectLighting.IncidentLighting;
}
const bool bTranslucent = TextureMapping->Mesh->IsTranslucent(TexelToVertex.ElementIndex);
const FLinearColor Reflectance = (bTranslucent ? FLinearColor::Black : TextureMapping->Mesh->EvaluateTotalReflectance(CurrentVertex, TexelToVertex.ElementIndex)) * (float)INV_PI;
// Combine all the lighting and surface reflectance so the final gather ray only needs one memory fetch
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:775
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::ProcessTextureMapping
Source code excerpt:
{
const double DirectLightingStartTime = FPlatformTime::Seconds();
const bool bCalculateDirectLightingFromPhotons = PhotonMappingSettings.bUsePhotonMapping && PhotonMappingSettings.bVisualizeCachedApproximateDirectLighting;
// Only continue if photon mapping will not be used for direct lighting
if (!bCalculateDirectLightingFromPhotons)
{
// Iterate over each light that is relevant to the direct lighting of the mesh
for (int32 LightIndex = 0; LightIndex < TextureMapping->Mesh->RelevantLights.Num(); LightIndex++)
{
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:2779
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::CalculateDirectLightingTextureMappingPhotonMap
Source code excerpt:
{
// Trace a ray into the current texel to get a good representation of what the final gather will see.
// Speed does not matter here since bVisualizeCachedApproximateDirectLighting is only used for debugging.
const FLightRay TexelRay(
CurrentVertex.WorldPosition + CurrentVertex.WorldTangentZ * TexelToVertex.TexelRadius,
CurrentVertex.WorldPosition - CurrentVertex.WorldTangentZ * TexelToVertex.TexelRadius,
TextureMapping,
NULL
);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:583
Scope (from outer to inner):
file
namespace Lightmass
class class FPhotonMappingSettings
Source code excerpt:
* This is mainly useful for debugging what the final gather rays see.
*/
bool bVisualizeCachedApproximateDirectLighting;
/** Debugging - whether to use the optimization of caching irradiance calculations in deposited photons (called Irradiance photons). */
bool bUseIrradiancePhotons;
/**
* Debugging - whether to cache the result of the search for the nearest irradiance photon on surfaces.