r.Lumen.Visualize.HardwareRayTracing.BucketMaterials

r.Lumen.Visualize.HardwareRayTracing.BucketMaterials

#Overview

name: r.Lumen.Visualize.HardwareRayTracing.BucketMaterials

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.Lumen.Visualize.HardwareRayTracing.BucketMaterials is to control whether secondary traces in Lumen’s hardware ray tracing visualization will be bucketed for coherent material access. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically its hardware ray tracing visualization feature.

This setting variable is primarily used in the Renderer module, specifically within the Lumen subsystem. It’s referenced in the LumenVisualizeHardwareRayTracing.cpp file, which suggests it’s part of the visualization tools for Lumen’s hardware ray tracing implementation.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning the bucketing is enabled by default.

The associated variable CVarLumenVisualizeHardwareRayTracingBucketMaterials directly interacts with this setting. It’s used to retrieve the current value of the setting on the render thread.

Developers should be aware that this setting affects the performance and coherence of material access during secondary ray traces in the visualization process. When enabled (set to 1), it may improve performance by increasing cache coherence for material access.

Best practices for using this variable include:

  1. Leave it at the default value (1) unless there’s a specific reason to disable it.
  2. If experiencing performance issues with Lumen hardware ray tracing visualization, experimenting with this setting might help.
  3. Be aware that changing this setting may affect the performance characteristics of the visualization, but not the actual rendering output.

Regarding the associated variable CVarLumenVisualizeHardwareRayTracingBucketMaterials:

This is the actual console variable object that represents the r.Lumen.Visualize.HardwareRayTracing.BucketMaterials setting in the code. It’s used to access the current value of the setting, particularly on the render thread.

The purpose of this variable is to provide a thread-safe way to access the setting’s value during rendering operations. It’s used in conditional statements to determine whether to perform the material bucketing operation.

This variable is part of the render thread’s state and should only be accessed in render thread contexts. The GetValueOnRenderThread() method is used to safely retrieve its value.

Developers should be aware that changes to this CVar will take effect immediately on the render thread, which could cause frame-to-frame changes in visualization performance if modified during runtime.

Best practices for using this variable include:

  1. Only access it on the render thread using GetValueOnRenderThread().
  2. Avoid frequently changing its value during runtime unless necessary for debugging or profiling purposes.
  3. If creating similar visualization tools, follow this pattern of using CVars for render thread safe configuration.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:81

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingBucketMaterials(
	TEXT("r.Lumen.Visualize.HardwareRayTracing.BucketMaterials"),
	1,
	TEXT("Determines whether a secondary traces will be bucketed for coherent material access (default = 1"),
	ECVF_RenderThreadSafe
);

namespace Lumen

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:80

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenVisualizeHardwareRayTracingBucketMaterials(
	TEXT("r.Lumen.Visualize.HardwareRayTracing.BucketMaterials"),
	1,
	TEXT("Determines whether a secondary traces will be bucketed for coherent material access (default = 1"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeHardwareRayTracing.cpp:763

Scope: file

Source code excerpt:


		// Bucket rays which hit objects, but do not have a surface-cache id by their material id
		if (CVarLumenVisualizeHardwareRayTracingBucketMaterials.GetValueOnRenderThread())
		{
			FRDGBufferRef BucketRaysByMaterialIdIndirectArgsBuffer = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateIndirectDesc<FRHIDispatchIndirectParameters>(1), TEXT("Lumen.Visualize.BucketRaysByMaterialIdIndirectArgsBuffer"));
			{
				FLumenVisualizeBucketRaysByMaterialIdIndirectArgsCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FLumenVisualizeBucketRaysByMaterialIdIndirectArgsCS::FParameters>();
				{
					PassParameters->RayAllocator = GraphBuilder.CreateSRV(RayAllocatorBuffer, PF_R32_UINT);