ShowFlag.VisualizeInstanceUpdates

ShowFlag.VisualizeInstanceUpdates

#Overview

name: ShowFlag.VisualizeInstanceUpdates

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.VisualizeInstanceUpdates is to allow developers to visualize where each instance is in each Instanced Static Mesh (ISM) Component. This setting variable is primarily used for debugging and visualization purposes in the rendering system.

This variable is utilized by several Unreal Engine subsystems and modules, including:

  1. The Cable Component plugin
  2. The Instanced Static Mesh rendering system
  3. The Nanite rendering system
  4. The Static Mesh rendering system

The value of this variable is set through the engine’s show flags system, which is typically controlled via the editor UI or programmatically.

The associated variable VisualizeInstanceUpdates interacts directly with ShowFlag.VisualizeInstanceUpdates, as they share the same value. This variable is used in various scene proxies to determine whether to draw debug information for instance updates.

Developers should be aware of the following when using this variable:

  1. It is only available in non-shipping builds (development and debug).
  2. Enabling this flag may impact performance, as it adds additional debug drawing.
  3. It’s primarily useful for debugging issues related to instanced static meshes and their updates.

Best practices for using this variable include:

  1. Use it temporarily during development and debugging, and ensure it’s disabled for performance testing and final builds.
  2. Combine it with other debugging tools and show flags to get a comprehensive view of the rendering process.
  3. Be aware that it may not capture all instance-related issues, so use it in conjunction with other debugging methods.

Regarding the associated variable VisualizeInstanceUpdates:

The purpose of VisualizeInstanceUpdates is to serve as the actual flag used in the rendering code to determine whether to visualize instance updates. It directly corresponds to the ShowFlag.VisualizeInstanceUpdates value.

This variable is used in various scene proxy implementations, such as FCableSceneProxy, FInstancedStaticMeshSceneProxy, Nanite::FSceneProxy, and FStaticMeshSceneProxy. These proxies use the variable to decide whether to draw debug information for instance updates.

The value of this variable is typically set based on the corresponding show flag (ShowFlag.VisualizeInstanceUpdates).

Developers should be aware that this variable is checked in performance-sensitive areas of the rendering code, so enabling it may have a performance impact.

Best practices for using VisualizeInstanceUpdates include:

  1. Use it judiciously and only when necessary for debugging instance-related issues.
  2. Disable it in release builds to avoid any potential performance overhead.
  3. When enabled, be prepared to interpret the additional debug visualization to diagnose instance update problems effectively.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, HISMCClusterTree, SFG_Advanced, NSLOCTEXT("UnrealEd", "HISMClusterTreeSF", "HISM/Foliage Cluster Tree"))
/** Allow to see where each instance is in each ISM Component */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeInstanceUpdates, SFG_Advanced, NSLOCTEXT("UnrealEd", "VisualizeInstanceUpdatesSF", "Visualize Instance Updates"))
/** Draws instanced grass, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(InstancedGrass, SFG_Advanced, NSLOCTEXT("UnrealEd", "InstancedGrassSF", "Grass"))
/** non baked shadows, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DynamicShadows, SFG_LightingComponents, NSLOCTEXT("UnrealEd", "DynamicShadowsSF", "Dynamic Shadows"))
/** Particles, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(Particles, SFG_Normal, NSLOCTEXT("UnrealEd", "ParticlesSF", "Particle Sprites"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/CableComponent/Source/CableComponent/Private/CableComponent.cpp:422

Scope (from outer to inner):

file
function     class FCableSceneProxy final : public FPrimitiveSceneProxy { public: SIZE_T GetTypeHash
class        class FCableSceneProxy final : public FPrimitiveSceneProxy
function     virtual FPrimitiveViewRelevance GetViewRelevance

Source code excerpt:

			View->Family->EngineShowFlags.Collision ||
			View->Family->EngineShowFlags.Bounds ||
			View->Family->EngineShowFlags.VisualizeInstanceUpdates ||
#endif
#if WITH_EDITOR
			(IsSelected() && View->Family->EngineShowFlags.VertexColors) ||
			(IsSelected() && View->Family->EngineShowFlags.PhysicalMaterialMasks) ||
#endif
			// Force down dynamic rendering path if invalid lightmap settings, so we can apply an error material in DrawRichMesh

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:1116

Scope (from outer to inner):

file
function     void FInstancedStaticMeshSceneProxy::GetDynamicMeshElements

Source code excerpt:


#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
			if (View->Family->EngineShowFlags.VisualizeInstanceUpdates && InstanceDataSceneProxy)
			{
				InstanceDataSceneProxy->DebugDrawInstanceChanges(Collector.GetPDI(ViewIndex), ViewFamily.EngineShowFlags.Game ? SDPG_World : SDPG_Foreground);
			}
#endif

#if ENABLE_DRAW_DEBUG

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:1059

Scope (from outer to inner):

file
namespace    Nanite
function     FPrimitiveViewRelevance FSceneProxy::GetViewRelevance

Source code excerpt:

			bInCollisionView ||
			View->Family->EngineShowFlags.Bounds ||
			View->Family->EngineShowFlags.VisualizeInstanceUpdates
		);
	#endif
	#if WITH_EDITOR
		// Nanite doesn't render debug vertex colors.
		//bSetDynamicRelevance |= (IsSelected() && View->Family->EngineShowFlags.VertexColors);
	#endif

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:1541

Scope (from outer to inner):

file
namespace    Nanite
function     void FSceneProxy::GetDynamicMeshElements

Source code excerpt:

			}
#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
			if (EngineShowFlags.VisualizeInstanceUpdates && InstanceDataSceneProxy)
			{
				InstanceDataSceneProxy->DebugDrawInstanceChanges(Collector.GetPDI(ViewIndex), EngineShowFlags.Game ? SDPG_World : SDPG_Foreground);
			}
#endif
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:1470

Scope (from outer to inner):

file
function     void FStaticMeshSceneProxy::GetDynamicMeshElements

Source code excerpt:

#endif
		|| EngineShowFlags.Bounds
		|| EngineShowFlags.VisualizeInstanceUpdates
		|| bProxyIsSelected 
		|| IsHovered()
		|| bIsLightmapSettingError);

	// Draw polygon mesh if we are either not in a collision view, or are drawing it as collision.
	if (EngineShowFlags.StaticMeshes && bDrawMesh)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:2078

Scope (from outer to inner):

file
function     FPrimitiveViewRelevance FStaticMeshSceneProxy::GetViewRelevance

Source code excerpt:

		bInCollisionView ||
		View->Family->EngineShowFlags.Bounds ||
		View->Family->EngineShowFlags.VisualizeInstanceUpdates ||
#endif
#if WITH_EDITOR
		(IsSelected() && View->Family->EngineShowFlags.VertexColors) ||
		(IsSelected() && View->Family->EngineShowFlags.PhysicalMaterialMasks) ||
#endif
#if STATICMESH_ENABLE_DEBUG_RENDERING

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, HISMCClusterTree, SFG_Advanced, NSLOCTEXT("UnrealEd", "HISMClusterTreeSF", "HISM/Foliage Cluster Tree"))
/** Allow to see where each instance is in each ISM Component */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeInstanceUpdates, SFG_Advanced, NSLOCTEXT("UnrealEd", "VisualizeInstanceUpdatesSF", "Visualize Instance Updates"))
/** Draws instanced grass, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(InstancedGrass, SFG_Advanced, NSLOCTEXT("UnrealEd", "InstancedGrassSF", "Grass"))
/** non baked shadows, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DynamicShadows, SFG_LightingComponents, NSLOCTEXT("UnrealEd", "DynamicShadowsSF", "Dynamic Shadows"))
/** Particles, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(Particles, SFG_Normal, NSLOCTEXT("UnrealEd", "ParticlesSF", "Particle Sprites"))