ShowFlag.VisualizeGlobalDistanceField

ShowFlag.VisualizeGlobalDistanceField

#Overview

name: ShowFlag.VisualizeGlobalDistanceField

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

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.VisualizeGlobalDistanceField is to enable the visualization of the global distance field in Unreal Engine 5. This is primarily used for debugging and development purposes within the rendering system.

This setting variable is mainly relied upon by the Renderer module of Unreal Engine. It’s used in various parts of the rendering pipeline, including deferred shading, distance field ambient occlusion, and mesh distance field visualization.

The value of this variable is set through the engine’s show flags system, which allows for runtime toggling of various debug visualization features. It’s typically controlled via the engine’s debug menu or console commands.

This variable interacts closely with other distance field-related variables, such as VisualizeMeshDistanceFields and VisualizeDistanceFieldAO. It’s often used in conjunction with these to provide comprehensive distance field debugging capabilities.

Developers should be aware that:

  1. This visualization is intended for development and debugging, not for shipping builds.
  2. Enabling this flag may have performance implications, as it requires additional rendering passes.
  3. It’s mutually exclusive with some other visualization modes, such as VisualizeMeshDistanceFields.

Best practices when using this variable include:

  1. Only enable it when actively debugging distance field-related issues.
  2. Disable it in performance-critical scenarios or when profiling other aspects of the renderer.
  3. Use it in conjunction with other distance field visualizations to get a complete picture of the distance field system.

Regarding the associated variable VisualizeGlobalDistanceField:

This is actually the same variable as ShowFlag.VisualizeGlobalDistanceField. In Unreal Engine, show flags are often accessed through both the ShowFlag structure and directly by name. The purpose and usage are identical to what was described above.

The main difference is in how it’s accessed in different parts of the code. When you see VisualizeGlobalDistanceField being used directly, it’s typically in contexts where the full ShowFlag structure isn’t necessary or available. This includes places like the DeferredShadingRenderer, DistanceFieldAmbientOcclusion, and MobileShadingRenderer where direct access to this specific flag is needed.

The considerations and best practices for using VisualizeGlobalDistanceField are the same as those for ShowFlag.VisualizeGlobalDistanceField. Developers should treat these as two ways of accessing the same underlying visualization toggle.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, PhysicsField, SFG_Visualize, NSLOCTEXT("UnrealEd", "PhysicsField", "Physics Field"))
/** Global Distance field */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeGlobalDistanceField, SFG_Visualize, NSLOCTEXT("UnrealEd", "GlobalDistanceFieldSF", "Global DistanceField"))
/** Enable the debug visualization of diffuse/specular lighting (direct and indirect) using probes */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeLightingOnProbes, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeLightingOnProbesSF", "Visualize Lighting on Probes"))
/** Screen space AO, for now SHOWFLAG_ALWAYS_ACCESSIBLE because r.GBuffer need that */
SHOWFLAG_ALWAYS_ACCESSIBLE(ScreenSpaceAO, SFG_LightingFeatures, NSLOCTEXT("UnrealEd", "ScreenSpaceAOSF", "Screen Space Ambient Occlusion"))
/** Distance field AO, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DistanceFieldAO, SFG_LightingFeatures, NSLOCTEXT("UnrealEd", "DistanceFieldAOSF", "Distance Field Ambient Occlusion"))

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, PhysicsField, SFG_Visualize, NSLOCTEXT("UnrealEd", "PhysicsField", "Physics Field"))
/** Global Distance field */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeGlobalDistanceField, SFG_Visualize, NSLOCTEXT("UnrealEd", "GlobalDistanceFieldSF", "Global DistanceField"))
/** Enable the debug visualization of diffuse/specular lighting (direct and indirect) using probes */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeLightingOnProbes, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeLightingOnProbesSF", "Visualize Lighting on Probes"))
/** Screen space AO, for now SHOWFLAG_ALWAYS_ACCESSIBLE because r.GBuffer need that */
SHOWFLAG_ALWAYS_ACCESSIBLE(ScreenSpaceAO, SFG_LightingFeatures, NSLOCTEXT("UnrealEd", "ScreenSpaceAOSF", "Screen Space Ambient Occlusion"))
/** Distance field AO, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DistanceFieldAO, SFG_LightingFeatures, NSLOCTEXT("UnrealEd", "DistanceFieldAOSF", "Distance Field Ambient Occlusion"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:3233

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::Render

Source code excerpt:


		// Draw visualizations just before use to avoid target contamination
		if (ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields || ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField)
		{
			RenderMeshDistanceFieldVisualization(GraphBuilder, SceneTextures);
		}

		if (bRenderDeferredLighting)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:748

Scope (from outer to inner):

file
function     bool FSceneRenderer::ShouldPrepareDistanceFieldScene

Source code excerpt:

		|| ShouldPrepareForDistanceFieldShadows() 
		|| bShouldPrepareForDFInsetIndirectShadow 
		|| ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField
		|| ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields;
}

bool FSceneRenderer::ShouldPrepareGlobalDistanceField() const
{
	if (!ensure(Scene != nullptr))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:782

Scope (from outer to inner):

file
function     bool FSceneRenderer::ShouldPrepareGlobalDistanceField

Source code excerpt:

	const bool bShouldPrepareForManyLights = ManyLights::IsUsingGlobalSDF();

	const bool bShouldPrepareForVisualization = ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField;

	return (bShouldPrepareForAO || bShouldPrepareForLumen || bShouldPrepareForManyLights || bShouldPrepareForVisualization);
}

void FDeferredShadingSceneRenderer::RenderDFAOAsIndirectShadowing(
	FRDGBuilder& GraphBuilder,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldAmbientOcclusion.cpp:935

Scope (from outer to inner):

file
function     bool FSceneRenderer::ShouldRenderDistanceFieldAO

Source code excerpt:

		&& !ViewFamily.EngineShowFlags.VisualizeDistanceFieldAO
		&& !ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields
		&& !ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField
		&& !ViewFamily.EngineShowFlags.PathTracing;
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldVisualization.cpp:95

Scope (from outer to inner):

file
function     void FSceneRenderer::RenderMeshDistanceFieldVisualization

Source code excerpt:

void FSceneRenderer::RenderMeshDistanceFieldVisualization(FRDGBuilder& GraphBuilder, const FMinimalSceneTextures& SceneTextures)
{
	const bool bVisualizeGlobalDistanceField = ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField;
	const bool bVisualizeMeshDistanceFields = ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields
		&& (Scene->DistanceFieldSceneData.NumObjectsInBuffer > 0)
		&& !bVisualizeGlobalDistanceField; // only one visualization enabled at a time

	if (!DoesPlatformSupportDistanceFields(ShaderPlatform)
		|| !IsUsingDistanceFields(ShaderPlatform)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MobileShadingRenderer.cpp:1355

Scope (from outer to inner):

file
function     void FMobileSceneRenderer::Render

Source code excerpt:

		}

		if (ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields || ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField)
		{
			RenderMeshDistanceFieldVisualization(GraphBuilder, SceneTextures);
		}
	
		if (ViewFamily.EngineShowFlags.VisualizeInstanceOcclusionQueries
			&& Scene->InstanceCullingOcclusionQueryRenderer)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:3712

Scope (from outer to inner):

file
function     void FSceneRenderer::OnRenderFinish

Source code excerpt:

		extern bool UseDistanceFieldAO();
		const bool bShowDFAODisabledWarning = !UseDistanceFieldAO() && (ViewFamily.EngineShowFlags.VisualizeDistanceFieldAO);
		const bool bShowDFDisabledWarning = !bMeshDistanceFieldEnabled && (ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields || ViewFamily.EngineShowFlags.VisualizeGlobalDistanceField || ViewFamily.EngineShowFlags.VisualizeDistanceFieldAO);

		const bool bShowNoSkyAtmosphereComponentWarning = !Scene->HasSkyAtmosphere() && ViewFamily.EngineShowFlags.VisualizeSkyAtmosphere;

		const bool bStationarySkylight = Scene->SkyLight && Scene->SkyLight->bWantsStaticShadowing;
		const bool bShowSkylightWarning = bStationarySkylight && !FReadOnlyCVARCache::EnableStationarySkylight();
		const bool bRealTimeSkyCaptureButNothingToCapture = Scene->SkyLight && Scene->SkyLight->bRealTimeCaptureEnabled && (!Scene->HasSkyAtmosphere() && !Scene->HasVolumetricCloud() && (Views.Num() > 0 && !Views[0].bSceneHasSkyMaterial));