r.AllowOcclusionQueries

r.AllowOcclusionQueries

#Overview

name: r.AllowOcclusionQueries

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

• type: Var
• help: Enables hardware occlusion culling.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AllowOcclusionQueries is to enable or disable hardware occlusion culling in the rendering system. This setting variable is crucial for optimizing rendering performance by allowing occluded meshes to be culled and not rendered.

The Unreal Engine subsystems that rely on this setting variable are primarily the Renderer module and the Engine module. It’s also referenced in the Avalanche plugin, which is an experimental feature.

The value of this variable is set in multiple places:

1. In the URendererSettings class, it’s exposed as a configurable property named “bOcclusionCulling”.
2. It’s also set as a console variable, allowing runtime modification.

This variable interacts with other rendering-related variables and systems, particularly those involved in culling and visibility determination.

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

1. Disabling occlusion queries can impact performance, especially in scenes with complex geometry.
2. It can be toggled per-scene, which allows for fine-grained control in different parts of a game.
3. There are visualization tools available for debugging occlusion queries, as indicated by the “VisualizeInstanceOcclusionQueries” show flag.

Best practices when using this variable include:

1. Generally, keep occlusion culling enabled for optimal performance.
2. Use the visualization tools to debug any issues related to occlusion culling.
3. Consider disabling occlusion queries selectively in scenes where they might cause problems or aren’t beneficial.
4. Be cautious when modifying this setting at runtime, as it can have significant performance implications.
5. When optimizing, consider the balance between the cost of performing occlusion queries and the rendering savings they provide.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:350

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:

	UPROPERTY(config, EditAnywhere, Category=Culling, meta=(
		ConsoleVariable="r.AllowOcclusionQueries",DisplayName="Occlusion Culling",
		ToolTip="Allows occluded meshes to be culled and not rendered."))
	uint32 bOcclusionCulling:1;

	UPROPERTY(config, EditAnywhere, Category=Culling, meta=(
		ConsoleVariable="r.MinScreenRadiusForLights",DisplayName="Min Screen Radius for Lights",
		ToolTip="Screen radius at which lights are culled. Larger values can improve performance but causes lights to pop off when they affect a small area of the screen."))

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

Scope: file

Source code excerpt:

static FAutoConsoleVariableRef CVarOcclusionCullEnable(
	// TODO: Move to r.Visibility.OcclusionCull.Enable. Still several explicit references.
	TEXT("r.AllowOcclusionQueries"),
	GOcclusionCullEnabled,
	TEXT("Enables hardware occlusion culling."),
	ECVF_RenderThreadSafe
);

bool FSceneRenderer::DoOcclusionQueries() const

#Loc: <Workspace>/Engine/Plugins/Experimental/Avalanche/Source/Avalanche/Private/Viewport/AvaViewportQualitySettings.cpp:409

Scope: file

Source code excerpt:

	{
		OutNameText = LOCTEXT("DisableOcclusionQueries_Name", "Disable Occlusion Queries");
		OutTooltipText = LOCTEXT("DisableOcclusionQueries_Tooltip", "Disable hardware occlusion queries, similar to setting r.AllowOcclusionQueries=0, but just for this scene.");
	}
	else if (InFeatureName.Equals("LumenScreenTraces", ESearchCase::IgnoreCase))
	{
		OutNameText = LOCTEXT("LumenScreenTraces_Name", "Lumen Screen Traces");
		OutTooltipText = LOCTEXT("LumenScreenTraces_Tooltip", "Use screen space tracing in Lumen.");
	}

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

Scope: file

Source code excerpt:

/** Visualize Occlusion Query bounding meshes */
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