r.ManyLights.HardwareRayTracing.AvoidSelfIntersections

r.ManyLights.HardwareRayTracing.AvoidSelfIntersections

#Overview

name: r.ManyLights.HardwareRayTracing.AvoidSelfIntersections

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ManyLights.HardwareRayTracing.AvoidSelfIntersections is to control whether self-intersections should be avoided in the hardware ray tracing process for the Many Lights system in Unreal Engine 5. This setting is primarily used in the rendering system, specifically for ray tracing operations.

This setting variable is mainly utilized by the Renderer module, particularly in the Many Lights subsystem. It’s part of the hardware ray tracing functionality for handling multiple light sources efficiently.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of true, indicating that self-intersections should be avoided by default.

The associated variable CVarManyLightsHardwareRayTracingAvoidSelfIntersections directly interacts with r.ManyLights.HardwareRayTracing.AvoidSelfIntersections. They share the same value and purpose.

Developers should be aware that this variable currently shares configuration with the Lumen system, specifically with the following Lumen settings:

This sharing of configuration is noted as a temporary situation, pending support for multiple SBT with the same RayTracingPipeline or Global Uniform Buffers in Ray Tracing.

Best practices when using this variable include:

  1. Consider the performance implications of enabling or disabling self-intersection avoidance.
  2. Be aware of its interaction with Lumen settings and potential impacts on both systems.
  3. Monitor for updates that may separate this configuration from Lumen in future engine versions.
  4. Test thoroughly when modifying this setting, as it can affect the visual quality and performance of ray-traced lighting.

Regarding the associated variable CVarManyLightsHardwareRayTracingAvoidSelfIntersections:

This is the actual console variable that controls the r.ManyLights.HardwareRayTracing.AvoidSelfIntersections setting. It’s used in the same context as the main variable, within the Many Lights ray tracing system.

The value of this variable is retrieved on the render thread and used to set permutation vectors for ray tracing shaders. This affects how the ray tracing pipeline is configured for avoiding self-intersections.

Developers should be aware that modifying this CVar will directly impact the behavior of the Many Lights ray tracing system. It’s used in shader permutations, so changes may require shader recompilation.

Best practices for using this CVar include:

  1. Use the console or configuration files to modify its value rather than hard-coding changes.
  2. Consider the performance and visual impact when enabling or disabling this feature.
  3. Test thoroughly in various lighting scenarios to ensure desired results.
  4. Be prepared for potential changes in future engine versions as the Many Lights system evolves.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:78

Scope: file

Source code excerpt:

// #ml_todo: Separate config cvars from Lumen once we support multiple SBT with same RayTracingPipeline or Global Uniform Buffers in Ray Tracing
static TAutoConsoleVariable<bool> CVarManyLightsHardwareRayTracingAvoidSelfIntersections(
	TEXT("r.ManyLights.HardwareRayTracing.AvoidSelfIntersections"),
	true,
	TEXT("Whether to avoid self-intersections.\n")
	TEXT("Currently shares config with Lumen:\n")
	TEXT("- r.Lumen.HardwareRayTracing.SkipBackFaceHitDistance\n")
	TEXT("- r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:77

Scope: file

Source code excerpt:


// #ml_todo: Separate config cvars from Lumen once we support multiple SBT with same RayTracingPipeline or Global Uniform Buffers in Ray Tracing
static TAutoConsoleVariable<bool> CVarManyLightsHardwareRayTracingAvoidSelfIntersections(
	TEXT("r.ManyLights.HardwareRayTracing.AvoidSelfIntersections"),
	true,
	TEXT("Whether to avoid self-intersections.\n")
	TEXT("Currently shares config with Lumen:\n")
	TEXT("- r.Lumen.HardwareRayTracing.SkipBackFaceHitDistance\n")
	TEXT("- r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:377

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::PrepareManyLightsLumenMaterial

Source code excerpt:

		{
			FHardwareRayTraceLightSamplesRGS::FPermutationDomain PermutationVector;
			PermutationVector.Set<FHardwareRayTraceLightSamplesRGS::FAvoidSelfIntersections>(CVarManyLightsHardwareRayTracingAvoidSelfIntersections.GetValueOnRenderThread());
			PermutationVector.Set<FHardwareRayTraceLightSamplesRGS::FHairVoxelTraces>(HairVoxelTraces != 0);
			PermutationVector.Set<FHardwareRayTraceLightSamplesRGS::FDebugMode>(ManyLights::GetDebugMode() != 0);
			TShaderRef<FHardwareRayTraceLightSamplesRGS> RayGenerationShader = View.ShaderMap->GetShader<FHardwareRayTraceLightSamplesRGS>(PermutationVector);
			OutRayGenShaders.Add(RayGenerationShader.GetRayTracingShader());
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:584

Scope (from outer to inner):

file
function     void ManyLights::RayTraceLightSamples

Source code excerpt:


			FHardwareRayTraceLightSamples::FPermutationDomain PermutationVector;
			PermutationVector.Set<FHardwareRayTraceLightSamples::FAvoidSelfIntersections>(CVarManyLightsHardwareRayTracingAvoidSelfIntersections.GetValueOnRenderThread());
			PermutationVector.Set<FHardwareRayTraceLightSamples::FHairVoxelTraces>(bHairVoxelTraces);
			PermutationVector.Set<FHardwareRayTraceLightSamples::FDebugMode>(bDebug);
			if (ManyLights::UseInlineHardwareRayTracing())
			{
				FHardwareRayTraceLightSamplesCS::AddLumenRayTracingDispatchIndirect(
					GraphBuilder,