ShowFlag.DisableOcclusionQueries

ShowFlag.DisableOcclusionQueries

#Overview

name: ShowFlag.DisableOcclusionQueries

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.DisableOcclusionQueries is to control hardware occlusion queries in the rendering system of Unreal Engine 5. It allows developers to disable occlusion queries for a specific scene, similar to setting r.AllowOcclusionQueries=0.

This setting variable is primarily used by the rendering subsystem of Unreal Engine 5. It’s referenced in the Engine and Renderer modules, specifically in the SceneVisibility component.

The value of this variable is set through the ShowFlags system, which is typically controlled via the engine’s configuration or runtime settings. It’s defined as a SHOWFLAG_FIXED_IN_SHIPPING flag, meaning it’s not available in shipping builds of the game.

The DisableOcclusionQueries variable interacts directly with ShowFlag.DisableOcclusionQueries, as they share the same value. This variable is used in the FSceneRenderer class to determine whether occlusion queries should be performed.

Developers must be aware that disabling occlusion queries can have significant performance implications. Occlusion queries are used to determine which objects are visible in a scene, and disabling them may result in unnecessary rendering of occluded objects.

Best practices when using this variable include:

  1. Only disable occlusion queries when absolutely necessary, such as for debugging purposes.
  2. Be aware of the performance impact when disabling occlusion queries.
  3. Remember that this setting is not available in shipping builds, so any logic depending on it should have fallbacks.

Regarding the associated variable DisableOcclusionQueries:

The purpose of DisableOcclusionQueries is the same as ShowFlag.DisableOcclusionQueries - to control hardware occlusion queries in the rendering system.

It’s used in the FSceneRenderer class within the Renderer module. Specifically, it’s checked in the DoOcclusionQueries() and PrepareViewStateForVisibility() functions.

The value of this variable is set through the ViewFamily.EngineShowFlags structure.

It interacts with the global variable GOcclusionCullEnabled in determining whether to perform occlusion queries.

Developers should be aware that this variable affects the entire ViewFamily, potentially impacting multiple views.

Best practices for using DisableOcclusionQueries include:

  1. Use it in conjunction with other visibility and culling settings for comprehensive control over the rendering process.
  2. Consider the impact on performance and visual quality when disabling occlusion queries.
  3. Use it for debugging or specific scenarios where occlusion queries are causing issues, but avoid leaving it disabled in production code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeInstanceOcclusionQueries, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeInstanceOcclusionQueriesSF", "Visualize Instance Culling Occlusion Queries"))
/** Disable hardware occlusion queries, similar to setting r.AllowOcclusionQueries=0, but just for this scene. */
SHOWFLAG_FIXED_IN_SHIPPING(0, DisableOcclusionQueries, SFG_Developer, NSLOCTEXT("UnrealEd", "DisableOcclusionQueries", "Disable Hardware Occlusion Queries"))

// RHI_RAYTRACING begin
SHOWFLAG_ALWAYS_ACCESSIBLE(PathTracing, SFG_Hidden, NSLOCTEXT("UnrealEd", "PathTracing", "Path tracing"))
SHOWFLAG_FIXED_IN_SHIPPING(0, RayTracingDebug, SFG_Hidden, NSLOCTEXT("UnrealEd", "RayTracingDebug", "Ray tracing debug"))
// RHI_RAYTRACING end

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, VisualizeInstanceOcclusionQueries, SFG_Visualize, NSLOCTEXT("UnrealEd", "VisualizeInstanceOcclusionQueriesSF", "Visualize Instance Culling Occlusion Queries"))
/** Disable hardware occlusion queries, similar to setting r.AllowOcclusionQueries=0, but just for this scene. */
SHOWFLAG_FIXED_IN_SHIPPING(0, DisableOcclusionQueries, SFG_Developer, NSLOCTEXT("UnrealEd", "DisableOcclusionQueries", "Disable Hardware Occlusion Queries"))

// RHI_RAYTRACING begin
SHOWFLAG_ALWAYS_ACCESSIBLE(PathTracing, SFG_Hidden, NSLOCTEXT("UnrealEd", "PathTracing", "Path tracing"))
SHOWFLAG_FIXED_IN_SHIPPING(0, RayTracingDebug, SFG_Hidden, NSLOCTEXT("UnrealEd", "RayTracingDebug", "Ray tracing debug"))
// RHI_RAYTRACING end

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

Scope (from outer to inner):

file
function     bool FSceneRenderer::DoOcclusionQueries

Source code excerpt:

bool FSceneRenderer::DoOcclusionQueries() const
{
	return GOcclusionCullEnabled && !ViewFamily.EngineShowFlags.DisableOcclusionQueries;
}

static int32 GRelevanceNumPrimitivesPerPacket = 0;
static FAutoConsoleVariableRef CVarRelevanceNumPrimitivesPerPacket(
	TEXT("r.Visibility.Relevance.NumPrimitivesPerPacket"),
	GRelevanceNumPrimitivesPerPacket,

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

Scope (from outer to inner):

file
function     void FSceneRenderer::PrepareViewStateForVisibility

Source code excerpt:

		// Don't test occlusion queries in collision viewmode as they can be bigger then the rendering bounds.
		const bool bCollisionView = ViewFamily.EngineShowFlags.CollisionVisibility || ViewFamily.EngineShowFlags.CollisionPawn;
		if (GIsHighResScreenshot || !DoOcclusionQueries() || bIsHitTesting || bCollisionView || ViewFamily.EngineShowFlags.DisableOcclusionQueries)
		{
			View.bDisableQuerySubmissions = true;
			View.bIgnoreExistingQueries = true;
		}

		// set up the screen area for occlusion