ShowFlag.DistanceCulledPrimitives

ShowFlag.DistanceCulledPrimitives

#Overview

name: ShowFlag.DistanceCulledPrimitives

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.DistanceCulledPrimitives is to control the visibility of objects that would normally be culled due to distance in Unreal Engine’s rendering system. This setting is part of the engine’s rendering and optimization features.

This setting variable is primarily used in the rendering system, specifically in the scene visibility and culling subsystems. It’s referenced in the Engine and Renderer modules of Unreal Engine.

The value of this variable is set through the engine’s show flags system, which allows for runtime toggling of various rendering features. It’s defined as SHOWFLAG_ALWAYS_ACCESSIBLE, meaning it’s available in all build configurations, including shipping builds.

The DistanceCulledPrimitives variable interacts with several other systems:

  1. It affects the culling of skeletal mesh overlays, as seen in the SkeletalMesh.cpp file.
  2. It influences the distance culling logic in the SceneVisibility.cpp file, where it can override normal distance culling behavior.
  3. It impacts the relevance computation for static meshes, particularly for overlay materials.

Developers should be aware that:

  1. This flag, when enabled, will show objects that would normally be culled due to distance, which can impact performance.
  2. It doesn’t affect detail meshes (IsDetailMesh()), maintaining their culling behavior.
  3. It’s exposed in SceneCapture, indicating its importance for debugging and visualization purposes.

Best practices when using this variable include:

  1. Use it primarily for debugging and visualization purposes, not in shipping builds.
  2. Be aware of the performance implications when enabling this flag, especially in scenes with many distant objects.
  3. Consider the interaction with other culling and LOD systems when using this flag.

Regarding the associated variable DistanceCulledPrimitives:

This is the actual boolean flag used in the engine code to control the behavior. It’s accessed through the EngineShowFlags structure of the view family (Family->EngineShowFlags.DistanceCulledPrimitives).

Its purpose is the same as the ShowFlag.DistanceCulledPrimitives - to control the visibility of distance-culled primitives. It’s used directly in conditional statements to determine whether distance culling should be applied or overridden.

This variable is set based on the corresponding show flag and is used in various parts of the rendering pipeline to make decisions about object visibility. Developers should be aware that changing this flag at runtime will immediately affect the rendering of distant objects, which can be useful for debugging but may have performance implications.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(StereoRendering, SFG_Hidden, NSLOCTEXT("UnrealEd", "StereoRenderingSF", "Stereoscopic Rendering"))
/** Show objects even if they should be distance culled, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DistanceCulledPrimitives, SFG_Hidden, NSLOCTEXT("UnrealEd", "DistanceCulledPrimitivesSF", "Distance Culled Primitives"))
/** To visualize the culling in Tile Based Deferred Lighting, later for non tiled as well */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeLightCulling, SFG_Hidden, NSLOCTEXT("UnrealEd", "VisualizeLightCullingSF", "Light Culling"))
/** To disable precomputed visibility */
SHOWFLAG_FIXED_IN_SHIPPING(1, PrecomputedVisibility, SFG_Advanced, NSLOCTEXT("UnrealEd", "PrecomputedVisibilitySF", "Precomputed Visibility"))
/** Contribution from sky light, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(SkyLighting, SFG_LightTypes, NSLOCTEXT("UnrealEd", "SkyLightingSF", "Sky Lighting"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SkeletalMesh.cpp:6867

Scope (from outer to inner):

file
function     void FSkeletalMeshSceneProxy::GetDynamicElementsSection

Source code excerpt:

					OverlayMaterialMaxDrawDistance > 0.f && 
					OverlayMaterialMaxDrawDistance != FLT_MAX && 
					!ViewFamily.EngineShowFlags.DistanceCulledPrimitives;
				
				bool bAddOverlay = true;
				if (bHasOverlayCullDistance)
				{
					// this is already combined with ViewDistanceScale
					float MaxDrawDistanceScale = GetCachedScalabilityCVars().SkeletalMeshOverlayDistanceScale;

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

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(StereoRendering, SFG_Hidden, NSLOCTEXT("UnrealEd", "StereoRenderingSF", "Stereoscopic Rendering"))
/** Show objects even if they should be distance culled, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DistanceCulledPrimitives, SFG_Hidden, NSLOCTEXT("UnrealEd", "DistanceCulledPrimitivesSF", "Distance Culled Primitives"))
/** To visualize the culling in Tile Based Deferred Lighting, later for non tiled as well */
SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeLightCulling, SFG_Hidden, NSLOCTEXT("UnrealEd", "VisualizeLightCullingSF", "Light Culling"))
/** To disable precomputed visibility */
SHOWFLAG_FIXED_IN_SHIPPING(1, PrecomputedVisibility, SFG_Advanced, NSLOCTEXT("UnrealEd", "PrecomputedVisibilitySF", "Precomputed Visibility"))
/** Contribution from sky light, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(SkyLighting, SFG_LightTypes, NSLOCTEXT("UnrealEd", "SkyLightingSF", "Sky Lighting"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:420

Scope (from outer to inner):

file
function     bool FViewInfo::IsDistanceCulled_AnyThread

Source code excerpt:


	// If cull distance is disabled, always show (except foliage)
	if (Family->EngineShowFlags.DistanceCulledPrimitives && !PrimitiveSceneInfo->Proxy->IsDetailMesh())
	{
		return false;
	}

	// The primitive is always culled if it exceeds the max fade distance.
	if ((bHasMaxDrawDistance && DistanceSquared > FMath::Square(MaxDrawDistance + FadeRadius)) || (bHasMinDrawDistance && DistanceSquared < FMath::Square(MinDrawDistance)))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:798

Scope (from outer to inner):

file
function     static int32 FrustumCull

Source code excerpt:

				{
					// If cull distance is disabled, always show the primitive (except foliage)
					if (View.Family->EngineShowFlags.DistanceCulledPrimitives
						&& !Scene.PrimitiveSceneProxies[Index]->IsDetailMesh()) // Proxy call is intentionally behind the DistancedCulledPrimitives check to prevent an expensive memory read
					{
						bShouldDistanceCull = false;
					}
				}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:1428

Scope (from outer to inner):

file
function     void FRelevancePacket::ComputeRelevance

Source code excerpt:

				const FStaticMeshBatch& StaticMesh = PrimitiveSceneInfo->StaticMeshes[MeshIndex];

				if (StaticMeshRelevance.bOverlayMaterial && !View.Family->EngineShowFlags.DistanceCulledPrimitives)
				{
					// Overlay mesh can have its own cull distance that is shorter than primitive cull distance
					float OverlayMaterialMaxDrawDistance = StaticMeshRelevance.ScreenSize;
					if (OverlayMaterialMaxDrawDistance > 0.f && OverlayMaterialMaxDrawDistance != FLT_MAX)
					{
						if (DistanceSquared > FMath::Square(OverlayMaterialMaxDrawDistance * MaxDrawDistanceScale))