r.InstanceCulling.OcclusionQueries

r.InstanceCulling.OcclusionQueries

#Overview

name: r.InstanceCulling.OcclusionQueries

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

• type: Var
• help: EXPERIMENTAL: Use per-instance software occlusion queries to perform less conservative visibility test than what\'s possible with HZB alone

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.InstanceCulling.OcclusionQueries is to enable an experimental feature for performing per-instance software occlusion queries in the rendering system. This setting is designed to provide a less conservative visibility test compared to what’s possible with Hierarchical Z-Buffer (HZB) alone.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically in the instance culling subsystem. It’s referenced in the InstanceCullingOcclusionQuery.cpp and InstanceCullingOcclusionQuery.h files, which are part of the instance culling implementation.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0, meaning the feature is disabled by default. Developers can change this value at runtime or through configuration files.

The associated variable CVarInstanceCullingOcclusionQueries directly interacts with r.InstanceCulling.OcclusionQueries. They share the same value and purpose.

Developers must be aware of several things when using this variable:

1. It’s marked as EXPERIMENTAL, indicating that it may not be fully stable or optimized.
2. It’s render thread safe, meaning it can be safely accessed from the render thread.
3. It has the ECVF_Preview flag, suggesting it’s not intended for production use yet.

Best practices when using this variable include:

1. Only enable it for testing or development purposes, not in production builds.
2. Monitor performance impact when enabled, as it may affect rendering performance.
3. Be prepared for potential visual artifacts or inconsistencies, given its experimental nature.

Regarding the associated variable CVarInstanceCullingOcclusionQueries: Its purpose is identical to r.InstanceCulling.OcclusionQueries, serving as the actual console variable that controls the feature. It’s used in the same Renderer module and instance culling subsystem. The value is set through the console variable system, with a default of 0. It directly controls whether the per-instance occlusion query feature is enabled. Developers should treat it with the same caution as r.InstanceCulling.OcclusionQueries, recognizing its experimental nature. Best practices include using it for testing and development only, and carefully monitoring its impact on performance and visual quality.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingOcclusionQuery.cpp:23

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarInstanceCullingOcclusionQueries(
	TEXT("r.InstanceCulling.OcclusionQueries"),
	0,
	TEXT("EXPERIMENTAL: Use per-instance software occlusion queries to perform less conservative visibility test than what's possible with HZB alone"),
	ECVF_RenderThreadSafe | ECVF_Preview);

struct FInstanceCullingOcclusionQueryDeferredContext;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingOcclusionQuery.h:47

Scope (from outer to inner):

file
class        class FInstanceCullingOcclusionQueryRenderer

Source code excerpt:

	/**
	* One uint8 per instance in GPUScene, with 1 bit per view
	* Available when when instance culling is enabled and r.InstanceCulling.OcclusionQueries=1.
	* Contains data for *previous* frame. Assumes that GPUScene instance indices are consistent.
	*/
	TRefCountPtr<FRDGPooledBuffer> InstanceOcclusionQueryBuffer;

	/*
	* Format that should be used to create views for InstanceOcclusionQueryBuffer.
	* May be R8_UINT or R32_UINT, basd on current hardware capability.
	*/
	EPixelFormat InstanceOcclusionQueryBufferFormat = PF_Unknown;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingOcclusionQuery.cpp:22

Scope: file

Source code excerpt:

#include "ProfilingDebugging/CpuProfilerTrace.h"

static TAutoConsoleVariable<int32> CVarInstanceCullingOcclusionQueries(
	TEXT("r.InstanceCulling.OcclusionQueries"),
	0,
	TEXT("EXPERIMENTAL: Use per-instance software occlusion queries to perform less conservative visibility test than what's possible with HZB alone"),
	ECVF_RenderThreadSafe | ECVF_Preview);

struct FInstanceCullingOcclusionQueryDeferredContext;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/InstanceCulling/InstanceCullingOcclusionQuery.cpp:734

Scope (from outer to inner):

file
function     bool FInstanceCullingOcclusionQueryRenderer::IsCompatibleWithView

Source code excerpt:

		&& View.HZB
		&& VisibilityMaskFormat != PF_Unknown
		&& CVarInstanceCullingOcclusionQueries.GetValueOnRenderThread() != 0;
}

// Debugging utilities

class FInstanceCullingOcclusionQueryDebugVS : public FGlobalShader
{