r.RayTracing.AsyncBuild

r.RayTracing.AsyncBuild

#Overview

name: r.RayTracing.AsyncBuild

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

• type: Var
• help: Whether to build ray tracing acceleration structures on async compute queue.\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RayTracing.AsyncBuild is to control whether ray tracing acceleration structures are built on the async compute queue in Unreal Engine 5.

This setting variable is primarily used in the rendering system, specifically for ray tracing functionality. Based on the callsites, it’s part of the Renderer module in Unreal Engine 5.

The value of this variable is set through a console variable (CVar) named CVarRayTracingAsyncBuild. It’s initialized with a default value of 0, meaning async building is disabled by default.

The main variable that interacts with r.RayTracing.AsyncBuild is GRHISupportsRayTracingAsyncBuildAccelerationStructure. The async build is only enabled if both r.RayTracing.AsyncBuild is non-zero and GRHISupportsRayTracingAsyncBuildAccelerationStructure is true.

Developers should be aware that enabling this feature may affect performance and should be tested thoroughly. It’s also important to note that not all hardware supports async building of ray tracing acceleration structures.

Best practices when using this variable include:

1. Only enable it if your target hardware supports async building of ray tracing acceleration structures.
2. Profile your application with and without this feature enabled to ensure it provides a performance benefit.
3. Be cautious when changing this setting at runtime, as it may cause temporary performance fluctuations.

Regarding the associated variable CVarRayTracingAsyncBuild:

The purpose of CVarRayTracingAsyncBuild is to provide a console-accessible way to control the r.RayTracing.AsyncBuild setting.

It’s part of the rendering system, specifically the ray tracing subsystem within the Renderer module.

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

It directly controls the behavior of r.RayTracing.AsyncBuild, determining whether async building of ray tracing acceleration structures is enabled.

Developers should be aware that this is a render thread safe variable, meaning it can be safely accessed and modified from the render thread.

Best practices for using CVarRayTracingAsyncBuild include:

1. Use it for debugging and profiling purposes to quickly toggle async building on and off.
2. When shipping a game, consider exposing this as a graphics option if async building provides significant benefits on some hardware configurations but not others.
3. Always check the return value of GetValueOnRenderThread() before using it to determine the current state of async building.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarRayTracingAsyncBuild(
	TEXT("r.RayTracing.AsyncBuild"),
	0,
	TEXT("Whether to build ray tracing acceleration structures on async compute queue.\n"),
	ECVF_RenderThreadSafe
);

static int32 GRayTracingMultiGpuTLASMask = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRayTracingAsyncBuild(
	TEXT("r.RayTracing.AsyncBuild"),
	0,
	TEXT("Whether to build ray tracing acceleration structures on async compute queue.\n"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     bool FDeferredShadingSceneRenderer::DispatchRayTracingWorldUpdates

Source code excerpt:

	}

	const bool bRayTracingAsyncBuild = CVarRayTracingAsyncBuild.GetValueOnRenderThread() != 0 && GRHISupportsRayTracingAsyncBuildAccelerationStructure;
	const ERDGPassFlags ComputePassFlags = bRayTracingAsyncBuild ? ERDGPassFlags::AsyncCompute : ERDGPassFlags::Compute;

	{
		RDG_GPU_STAT_SCOPE(GraphBuilder, RayTracingUpdate);

		{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumesHardwareRayTracing.cpp:244

Scope: file

Source code excerpt:

	PassParamsTLAS->RayTracingSceneBuffer = RayTracingScene.GetBufferChecked();

	const bool bRayTracingAsyncBuild = false;//CVarRayTracingAsyncBuild.GetValueOnRenderThread() != 0 && GRHISupportsRayTracingAsyncBuildAccelerationStructure;
	const ERDGPassFlags ComputePassFlags = bRayTracingAsyncBuild ? ERDGPassFlags::AsyncCompute : ERDGPassFlags::Compute;
	GraphBuilder.AddPass(
		RDG_EVENT_NAME("RayTracingScene"),
		PassParamsTLAS,
		ComputePassFlags | ERDGPassFlags::NeverCull | ERDGPassFlags::NeverParallel,
		[