r.Mobile.EnableOcclusionExtraFrame

r.Mobile.EnableOcclusionExtraFrame

#Overview

name: r.Mobile.EnableOcclusionExtraFrame

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Mobile.EnableOcclusionExtraFrame is to control whether an extra frame is allowed for occlusion culling in mobile rendering scenarios. This setting is primarily used in the rendering system, specifically for optimizing occlusion culling on mobile platforms.

This setting variable is relied upon by the Unreal Engine’s Renderer module, particularly in the SceneOcclusion subsystem. It’s used within the FOcclusionQueryHelpers class to determine the number of buffered frames for occlusion queries.

The value of this variable is set using a TAutoConsoleVariable, which means it can be changed at runtime through console commands. By default, it is set to true.

The associated variable CVarMobileEnableOcclusionExtraFrame interacts directly with r.Mobile.EnableOcclusionExtraFrame. They share the same value and purpose.

Developers must be aware that this variable is specifically targeted at mobile platforms or Vulkan-based mobile SM5 platforms. It’s used to add extra frames for occlusion culling, which can be crucial for performance on these platforms due to their unique rendering characteristics.

Best practices when using this variable include:

  1. Leaving it enabled (default) for most mobile scenarios, as it’s designed to improve performance.
  2. Testing the impact of disabling it on your specific mobile game or application, as the performance impact may vary depending on your scene complexity and rendering needs.
  3. Being aware that it may affect the responsiveness of occlusion culling, as it introduces additional frame(s) of latency.

Regarding the associated variable CVarMobileEnableOcclusionExtraFrame:

The purpose of CVarMobileEnableOcclusionExtraFrame is identical to r.Mobile.EnableOcclusionExtraFrame. It’s a console variable that controls whether an extra frame is allowed for occlusion culling in mobile rendering scenarios.

This variable is used directly in the Renderer module, specifically in the SceneOcclusion.cpp file. It’s checked in the GetNumBufferedFrames function of the FOcclusionQueryHelpers class to determine if additional frames should be added for mobile platforms.

The value of CVarMobileEnableOcclusionExtraFrame is set when the TAutoConsoleVariable is initialized, but can be changed at runtime through console commands.

As it’s directly associated with r.Mobile.EnableOcclusionExtraFrame, it interacts with the same systems and has the same implications for occlusion culling on mobile platforms.

Developers should be aware that this variable is checked on the rendering thread, as indicated by the ECVF_RenderThreadSafe flag. Changes to this variable will affect the rendering pipeline’s behavior regarding occlusion culling.

Best practices for using CVarMobileEnableOcclusionExtraFrame are the same as those for r.Mobile.EnableOcclusionExtraFrame, as they are effectively the same setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:62

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarMobileEnableOcclusionExtraFrame(
	TEXT("r.Mobile.EnableOcclusionExtraFrame"),
	true,
	TEXT("Whether to allow extra frame for occlusion culling (enabled by default)"),
	ECVF_RenderThreadSafe
	);

int32 GEnableComputeBuildHZB = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:61

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<bool> CVarMobileEnableOcclusionExtraFrame(
	TEXT("r.Mobile.EnableOcclusionExtraFrame"),
	true,
	TEXT("Whether to allow extra frame for occlusion culling (enabled by default)"),
	ECVF_RenderThreadSafe
	);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneOcclusion.cpp:116

Scope (from outer to inner):

file
function     int32 FOcclusionQueryHelpers::GetNumBufferedFrames

Source code excerpt:


	int32 NumExtraMobileFrames = 0;
	if ((FeatureLevel <= ERHIFeatureLevel::ES3_1 || IsVulkanMobileSM5Platform(ShaderPlatform)) && CVarMobileEnableOcclusionExtraFrame.GetValueOnAnyThread())
	{
		NumExtraMobileFrames++; // the mobile renderer just doesn't do much after the basepass, and hence it will be asking for the query results almost immediately; the results can't possibly be ready in 1 frame.
		
		bool bNeedsAnotherExtraMobileFrame = IsVulkanPlatform(ShaderPlatform) || IsOpenGLPlatform(ShaderPlatform);
		bNeedsAnotherExtraMobileFrame = bNeedsAnotherExtraMobileFrame || IsVulkanMobileSM5Platform(ShaderPlatform);
		bNeedsAnotherExtraMobileFrame = bNeedsAnotherExtraMobileFrame || FDataDrivenShaderPlatformInfo::GetNeedsExtraMobileFrames(ShaderPlatform);