r.SceneDepthHZBAsyncCompute

r.SceneDepthHZBAsyncCompute

#Overview

name: r.SceneDepthHZBAsyncCompute

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.SceneDepthHZBAsyncCompute is to control the use of async compute for building the Hierarchical Z-Buffer (HZB) for the scene depth buffer in Unreal Engine’s rendering system.

This setting variable is primarily used in the renderer subsystem of Unreal Engine, specifically within the deferred shading renderer module. It’s referenced in the DeferredShadingRenderer.cpp file, which is a core part of the engine’s rendering pipeline.

The value of this variable is set through a console variable (CVarSceneDepthHZBAsyncCompute) with three possible options: 0: Don’t use async compute (default) 1: Use async compute, start as soon as possible 2: Use async compute, start after ComputeLightGrid.CompactLinks pass

This variable interacts closely with the async compute system and the HZB building process. It’s associated with the C++ variable CVarSceneDepthHZBAsyncCompute, which is used to access the value in the code.

Developers must be aware that changing this setting can impact rendering performance and potentially introduce synchronization issues if not handled correctly. The async compute mode can affect the timing and resource utilization of the GPU.

Best practices when using this variable include:

  1. Testing thoroughly with different values to ensure stability and performance gains.
  2. Considering the target hardware capabilities, as async compute may not be beneficial on all GPU architectures.
  3. Monitoring for potential visual artifacts or inconsistencies when enabling async compute.
  4. Adjusting other related rendering settings to optimize for the chosen async compute mode.

Regarding the associated variable CVarSceneDepthHZBAsyncCompute:

This is the actual C++ variable that represents the console variable in the engine’s code. It’s used to retrieve the current value of the setting in the render thread (GetValueOnRenderThread()).

The variable is defined as a static TAutoConsoleVariable, which means it’s a global variable accessible throughout the renderer code. It’s used to determine the async compute mode in the Render function of FDeferredShadingSceneRenderer.

Developers should be aware that changes to this variable will take effect on the render thread, which may not be immediate. They should also ensure that any code relying on this variable is properly synchronized with the render thread to avoid race conditions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:206

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSceneDepthHZBAsyncCompute(
	TEXT("r.SceneDepthHZBAsyncCompute"), 0,
	TEXT("Selects whether HZB for scene depth buffer should be built with async compute.\n")
	TEXT(" 0: Don't use async compute (default)\n")
	TEXT(" 1: Use async compute, start as soon as possible\n")
	TEXT(" 2: Use async compute, start after ComputeLightGrid.CompactLinks pass"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:205

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarSceneDepthHZBAsyncCompute(
	TEXT("r.SceneDepthHZBAsyncCompute"), 0,
	TEXT("Selects whether HZB for scene depth buffer should be built with async compute.\n")
	TEXT(" 0: Don't use async compute (default)\n")
	TEXT(" 1: Use async compute, start as soon as possible\n")
	TEXT(" 2: Use async compute, start after ComputeLightGrid.CompactLinks pass"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp:2162

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::Render
lambda-function

Source code excerpt:

	const auto RenderOcclusionLambda = [&]()
	{
		const int32 AsyncComputeMode = CVarSceneDepthHZBAsyncCompute.GetValueOnRenderThread();
		bool bAsyncCompute = AsyncComputeMode != 0;

		FBuildHZBAsyncComputeParams AsyncComputeParams = {};
		if (AsyncComputeMode == 2)
		{
			AsyncComputeParams.Prerequisite = ComputeLightGridOutput.CompactLinksPass;