r.Lumen.Reflections.HardwareRayTracing.BucketMaterials

r.Lumen.Reflections.HardwareRayTracing.BucketMaterials

#Overview

name: r.Lumen.Reflections.HardwareRayTracing.BucketMaterials

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

• type: Var
• help: Determines whether a secondary traces will be bucketed for coherent material access (default = 1

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Reflections.HardwareRayTracing.BucketMaterials is to control whether secondary traces in Lumen reflections will be bucketed for coherent material access in hardware ray tracing.

This setting variable is primarily used in the Lumen reflection system, specifically for hardware ray tracing within Unreal Engine’s rendering subsystem.

The value of this variable is set through a console variable (CVar) named CVarLumenReflectionsHardwareRayTracingBucketMaterials. It is defined with a default value of 1, meaning the feature is enabled by default.

This variable interacts with the Lumen reflection tracing system, particularly in the context of hit lighting and material access optimization.

Developers should be aware that:

1. This variable affects performance and coherency of material access during ray tracing.
2. It is part of the scalability options and can be adjusted at runtime.
3. It is only relevant when using hardware ray tracing for Lumen reflections.

Best practices when using this variable:

1. Keep it enabled (value 1) for better performance in most scenarios, as it improves coherency of material access.
2. If experiencing issues specific to material access in reflections, developers can try disabling it (value 0) to diagnose the problem.
3. Consider the impact on different hardware configurations, as the performance benefit may vary.

Regarding the associated variable CVarLumenReflectionsHardwareRayTracingBucketMaterials:

• It is the actual console variable that controls the feature.
• It is defined with the same properties as the r.Lumen.Reflections.HardwareRayTracing.BucketMaterials setting.
• It is used directly in the code to determine whether to sort traces by material during hit lighting compaction.
• Developers can modify this variable through console commands or configuration files to adjust the behavior at runtime or startup.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionHardwareRayTracing.cpp:27

Scope: file

Source code excerpt:

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

static TAutoConsoleVariable<int32> CVarLumenReflectionsHardwareRayTracingRetraceHitLighting(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionHardwareRayTracing.cpp:26

Scope: file

Source code excerpt:

);

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionHardwareRayTracing.cpp:558

Scope (from outer to inner):

file
function     void RenderLumenHardwareRayTracingReflections

Source code excerpt:

			ComputePassFlags,
			LumenReflections::ETraceCompactionMode::HitLighting,
			/*bSortByMaterial*/ CVarLumenReflectionsHardwareRayTracingBucketMaterials.GetValueOnRenderThread() != 0);

		// Trace with hit-lighting
		{
			bool bApplySkyLight = true;
			bool bUseInline = false;