r.HZB.BuildUseCompute

r.HZB.BuildUseCompute

#Overview

name: r.HZB.BuildUseCompute

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

• type: Var
• help: Selects whether HZB should be built with compute.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HZB.BuildUseCompute is to control whether the Hierarchical Z-Buffer (HZB) should be built using compute shaders in Unreal Engine’s rendering system. This setting variable is part of the rendering subsystem and specifically affects the HZB generation process.

The Unreal Engine renderer module relies on this setting variable, as evidenced by its usage in the SceneTextureReductions.cpp file within the Runtime/Renderer/Private directory.

The value of this variable is set through a console variable (CVarHZBBuildUseCompute) with a default value of 1, indicating that compute shaders are used for HZB building by default. This console variable is defined as render thread safe, allowing it to be modified during runtime without causing threading issues.

The associated variable CVarHZBBuildUseCompute directly interacts with r.HZB.BuildUseCompute. They share the same value and purpose, with CVarHZBBuildUseCompute being the actual C++ variable used in the code to access the setting.

Developers must be aware that changing this variable will affect the method used to build the Hierarchical Z-Buffer. When set to 1, compute shaders will be used, which may provide better performance on certain hardware. When set to 0, an alternative method (likely using pixel shaders) will be used instead.

Best practices when using this variable include:

1. Profiling performance with both settings (0 and 1) to determine which method works best for your specific hardware targets.
2. Considering the impact on different platforms, as compute shader performance can vary between GPUs.
3. Potentially exposing this setting to end-users in graphics options if there’s a significant performance difference between the two methods.

Regarding the associated variable CVarHZBBuildUseCompute:

The purpose of CVarHZBBuildUseCompute is to provide programmatic access to the r.HZB.BuildUseCompute setting within the C++ code of the renderer.

This variable is used directly in the renderer module to determine whether to use compute shaders for HZB building. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to the current value.

The value of CVarHZBBuildUseCompute is set when the console variable is initialized, but can be changed at runtime through console commands or other means of modifying console variables.

CVarHZBBuildUseCompute interacts directly with the r.HZB.BuildUseCompute setting, effectively serving as its in-code representation.

Developers should be aware that this variable is intended for render thread usage, as indicated by the GetValueOnRenderThread() method.

Best practices for using CVarHZBBuildUseCompute include:

1. Always accessing its value using GetValueOnRenderThread() when in render thread code.
2. Avoiding direct modification of this variable; instead, use the appropriate console variable modification methods if changes are needed at runtime.
3. Considering caching the value if it’s accessed frequently in performance-critical code sections, to avoid repeated calls to GetValueOnRenderThread().

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneTextureReductions.cpp:14

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarHZBBuildUseCompute(
	TEXT("r.HZB.BuildUseCompute"), 1,
	TEXT("Selects whether HZB should be built with compute."),
	ECVF_RenderThreadSafe);



BEGIN_SHADER_PARAMETER_STRUCT(FSharedHZBParameters, )

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneTextureReductions.cpp:13

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarHZBBuildUseCompute(
	TEXT("r.HZB.BuildUseCompute"), 1,
	TEXT("Selects whether HZB should be built with compute."),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneTextureReductions.cpp:99

Scope: file

Source code excerpt:

	else
	{
		return CVarHZBBuildUseCompute.GetValueOnRenderThread() == 1;
	}
}

void BuildHZB(
	FRDGBuilder& GraphBuilder,
	FRDGTextureRef SceneDepth,