ShowFlag.PrecomputedVisibilityCells

ShowFlag.PrecomputedVisibilityCells

#Overview

name: ShowFlag.PrecomputedVisibilityCells

This variable is created as a Console Variable (cvar).

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.PrecomputedVisibilityCells is to visualize precomputed visibility cells in the Unreal Engine rendering system. This setting is primarily used for debugging and visualization purposes in the editor and development builds.

This setting variable is primarily used in the Unreal Engine’s rendering system, specifically in the visibility and occlusion subsystems. It is also utilized by the Lightmass system for precomputed lighting and visibility calculations.

The value of this variable is set through the engine’s show flags system, which allows developers to toggle various visualization and debugging options. It is defined in the ShowFlagsValues.inl file and is marked as SHOWFLAG_FIXED_IN_SHIPPING, indicating that it is not available in shipping builds.

The associated variable PrecomputedVisibilityCells interacts closely with ShowFlag.PrecomputedVisibilityCells. It represents the actual data structure containing the precomputed visibility cells used for occlusion and rendering optimizations.

Developers should be aware that:

  1. This flag is for visualization purposes only and should not be relied upon for gameplay or production-critical features.
  2. Enabling this flag may have performance implications, especially in complex scenes with many visibility cells.
  3. The visualization is only available in non-shipping builds.

Best practices when using this variable include:

  1. Use it primarily for debugging visibility issues or understanding the precomputed visibility system.
  2. Disable it when not actively debugging to avoid unnecessary performance overhead.
  3. Combine it with other visualization tools and profiling methods for a comprehensive understanding of the visibility system.

Regarding the associated variable PrecomputedVisibilityCells: This variable represents the actual data structure containing precomputed visibility information for the scene. It is used in the Lightmass system for calculating and storing visibility data, and in the runtime engine for applying precomputed visibility optimizations.

The PrecomputedVisibilityCells variable is crucial for the engine’s occlusion and rendering optimizations. It contains information about which objects are potentially visible from different locations in the scene, allowing the engine to cull invisible objects efficiently.

Developers should be aware that:

  1. The precomputed visibility data is generated during the lightmap build process.
  2. Modifying the scene geometry or lighting setup may require rebuilding the precomputed visibility data.
  3. The effectiveness of precomputed visibility depends on the scene’s static nature and the quality of the precomputed data.

Best practices for working with PrecomputedVisibilityCells include:

  1. Ensure that precomputed visibility is rebuilt after significant changes to static geometry in the scene.
  2. Use the visualization tools (including ShowFlag.PrecomputedVisibilityCells) to verify the correctness of the precomputed visibility data.
  3. Consider the trade-offs between precomputed visibility quality and build times when configuring lightmass settings.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:325

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, PreviewShadowsIndicator, SFG_Visualize, NSLOCTEXT("UnrealEd", "PreviewShadowIndicatorSF", "Preview Shadows Indicator"))
/** Visualize precomputed visibility cells */
SHOWFLAG_FIXED_IN_SHIPPING(0, PrecomputedVisibilityCells, SFG_Visualize, NSLOCTEXT("UnrealEd", "PrecomputedVisibilityCellsSF", "Precomputed Visibility Cells"))
/** Visualize volumetric lightmap used for GI on dynamic objects */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeVolumetricLightmap, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeVolumetricLightmapSF", "Volumetric Lightmap"))
/** Visualize volume lighting samples used for GI on dynamic objects */
SHOWFLAG_FIXED_IN_SHIPPING(0, VolumeLightingSamples, SFG_Visualize, NSLOCTEXT("UnrealEd", "VolumeLightingSamplesSF", "Volume Lighting Samples"))
/** Render Paper2D sprites, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(Paper2DSprites, SFG_Advanced, NSLOCTEXT("UnrealEd", "Paper2DSpritesSF", "Paper 2D Sprites"))

#Associated Variable and Callsites

This variable is associated with another variable named PrecomputedVisibilityCells. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/ImportExport/Exporter.cpp:464

Scope (from outer to inner):

file
namespace    Lightmass
function     void FLightmassSolverExporter::ExportResults

Source code excerpt:

		if( ErrorCode >= 0 )
		{
			const int32 NumCells = TaskData.PrecomputedVisibilityCells.Num();
			Swarm->Write(&NumCells, sizeof(NumCells));
			for (int32 CellIndex = 0; CellIndex < NumCells; CellIndex++)
			{
				Swarm->Write(&TaskData.PrecomputedVisibilityCells[CellIndex].Bounds, sizeof(TaskData.PrecomputedVisibilityCells[CellIndex].Bounds));
				WriteArray(TaskData.PrecomputedVisibilityCells[CellIndex].VisibilityData);
			}
			WriteArray(TaskData.DebugVisibilityRays);
			Swarm->CloseCurrentChannel();
		}
		else
		{

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.h:1335

Scope (from outer to inner):

file
namespace    Lightmass

Source code excerpt:

{
	FGuid Guid;
	TArray<FPrecomputedVisibilityCell> PrecomputedVisibilityCells;
	TArray<FDebugStaticLightingRay> DebugVisibilityRays;
};

struct FIrradianceBrickData
{
	FGuid IntersectingLevelGuid;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PrecomputedVisibility.cpp:1048

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculatePrecomputedVisibility

Source code excerpt:

		(BucketIndex + 1) * AllPrecomputedVisibilityCells.Num() / PrecomputedVisibilitySettings.NumCellDistributionBuckets;

	DataLink->Element.PrecomputedVisibilityCells.Empty(MaxCellIndex - StartCellIndex);
	
	FStaticLightingMappingContext MappingContext(NULL, *this);

	// These are re-used across operations on the same thread to reduce reallocations
	TArray<int32> VisibleCellFaces;
	TArray<float> VisibleCellFacePDFs;

#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/PrecomputedVisibility.cpp:1072

Scope (from outer to inner):

file
namespace    Lightmass
function     void FStaticLightingSystem::CalculatePrecomputedVisibility

Source code excerpt:

		MappingContext.RayCache.Clear();

		DataLink->Element.PrecomputedVisibilityCells.Add(AllPrecomputedVisibilityCells[CellIndex]);
		FPrecomputedVisibilityCell& CurrentCell = DataLink->Element.PrecomputedVisibilityCells.Last();

		const bool bDebugThisCell = CurrentCell.Bounds.IsInside(Scene.DebugInput.CameraPosition) && PrecomputedVisibilitySettings.bVisualizePrecomputedVisibility;

		AffectingOverrideVolumes.Reset();
		for (int32 VolumeIndex = 0; VolumeIndex < Scene.PrecomputedVisibilityOverrideVolumes.Num(); VolumeIndex++)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:325

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, PreviewShadowsIndicator, SFG_Visualize, NSLOCTEXT("UnrealEd", "PreviewShadowIndicatorSF", "Preview Shadows Indicator"))
/** Visualize precomputed visibility cells */
SHOWFLAG_FIXED_IN_SHIPPING(0, PrecomputedVisibilityCells, SFG_Visualize, NSLOCTEXT("UnrealEd", "PrecomputedVisibilityCellsSF", "Precomputed Visibility Cells"))
/** Visualize volumetric lightmap used for GI on dynamic objects */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeVolumetricLightmap, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeVolumetricLightmapSF", "Volumetric Lightmap"))
/** Visualize volume lighting samples used for GI on dynamic objects */
SHOWFLAG_FIXED_IN_SHIPPING(0, VolumeLightingSamples, SFG_Visualize, NSLOCTEXT("UnrealEd", "VolumeLightingSamplesSF", "Volume Lighting Samples"))
/** Render Paper2D sprites, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(Paper2DSprites, SFG_Advanced, NSLOCTEXT("UnrealEd", "Paper2DSpritesSF", "Paper 2D Sprites"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:159

Scope (from outer to inner):

file
function     const uint8* FSceneViewState::GetPrecomputedVisibilityData

Source code excerpt:


		// Draw visibility cell bounds for debugging if enabled
		if ((GShowPrecomputedVisibilityCells || View.Family->EngineShowFlags.PrecomputedVisibilityCells) && !GShowRelevantPrecomputedVisibilityCells)
		{
			for (int32 BucketIndex = 0; BucketIndex < Handler.PrecomputedVisibilityCellBuckets.Num(); BucketIndex++)
			{
				for (int32 CellIndex = 0; CellIndex < Handler.PrecomputedVisibilityCellBuckets[BucketIndex].Cells.Num(); CellIndex++)
				{
					const FPrecomputedVisibilityCell& CurrentCell = Handler.PrecomputedVisibilityCellBuckets[BucketIndex].Cells[CellIndex];