r.SceneCulling.Async.Query

r.SceneCulling.Async.Query

#Overview

name: r.SceneCulling.Async.Query

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.SceneCulling.Async.Query is to control whether async culling scene queries are enabled or disabled in the Unreal Engine 5 rendering system. This setting variable is part of the scene culling optimization mechanism, which helps improve rendering performance by determining which objects should be rendered in a given frame.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the scene culling component. This can be inferred from the file path “Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp” where the variable is defined and used.

The value of this variable is set using a console variable (CVar) system. It is initialized with a default value of 1 (enabled) and can be changed at runtime through console commands or configuration files.

The associated variable CVarSceneCullingAsyncQuery interacts directly with r.SceneCulling.Async.Query. They share the same value and purpose, with CVarSceneCullingAsyncQuery being the C++ representation of the console variable.

Developers must be aware that this variable affects the performance and behavior of scene culling. Enabling async queries (value 1) may improve performance by allowing culling operations to be performed asynchronously, potentially reducing frame time. However, it may also introduce a slight delay in updating visibility information.

Best practices when using this variable include:

  1. Leaving it enabled (default value of 1) for most scenarios, as it’s likely optimized for general use cases.
  2. Testing performance with both enabled and disabled states in specific scenarios where culling performance is critical.
  3. Considering the impact on frame-to-frame consistency when enabling or disabling async queries.
  4. Using profiling tools to measure the impact of this setting on overall rendering performance.

Regarding the associated variable CVarSceneCullingAsyncQuery: The purpose of CVarSceneCullingAsyncQuery is to provide a programmatic interface to the r.SceneCulling.Async.Query setting within the C++ codebase. It allows the engine to read the current state of the async query setting and apply it to the scene culling logic.

This variable is used in the Renderer module, specifically in the SceneCulling component. It’s typically accessed using the GetValueOnRenderThread() method, which ensures thread-safe access to the variable’s value.

The value of CVarSceneCullingAsyncQuery is set indirectly through the r.SceneCulling.Async.Query console variable. Any changes to the console variable will be reflected in CVarSceneCullingAsyncQuery.

Developers should be aware that this variable is used to control the behavior of the scene culling system at runtime. It’s important to access this variable correctly, using the appropriate thread-safe methods provided by the TAutoConsoleVariable class.

Best practices for using CVarSceneCullingAsyncQuery include:

  1. Always access its value using GetValueOnRenderThread() when in render thread code.
  2. Avoid frequently querying the value in performance-critical code paths.
  3. Consider caching the value if it’s used multiple times within the same function or update cycle.
  4. Be cautious when modifying this variable directly, as it could affect the entire rendering pipeline’s behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:128

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSceneCullingAsyncQuery(
	TEXT("r.SceneCulling.Async.Query"), 
	1, 
	TEXT("Enable/Disable async culling scene queries."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarSceneCullingMinCellSize(
	TEXT("r.SceneCulling.MinCellSize"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:127

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSceneCullingAsyncQuery(
	TEXT("r.SceneCulling.Async.Query"), 
	1, 
	TEXT("Enable/Disable async culling scene queries."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarSceneCullingMinCellSize(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCulling.cpp:2673

Scope (from outer to inner):

file
function     FSceneCulling::FUpdater &FSceneCulling::BeginUpdate

Source code excerpt:

	SmallFootprintCellSideThreshold = CVarSmallFootprintSideThreshold.GetValueOnRenderThread();
	bUseAsyncUpdate = CVarSceneCullingAsyncUpdate.GetValueOnRenderThread() != 0;
	bUseAsyncQuery = CVarSceneCullingAsyncQuery.GetValueOnRenderThread() != 0;

	if (bIsEnabled)
	{
		Updater.Implementation = new FSceneCullingBuilder(*this, bAnySceneUpdatesExpected);
	}
	else