r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance

r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance

#Overview

name: r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance

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.HardwareRayTracing.SkipTwoSidedHitDistance is to control the distance within which the first two-sided material hit will be skipped during hardware ray tracing in the Lumen global illumination system. This setting is specifically designed to address self-intersection issues with Nanite fallback meshes on foliage, where the SkipBackFaceHitDistance setting is ineffective for two-sided materials.

This setting variable is primarily used by the Lumen subsystem within Unreal Engine’s rendering module. It’s specifically related to the hardware ray tracing functionality of Lumen.

The value of this variable is set through a console variable (CVarLumenHardwareRayTracingSkipTwoSidedHitDistance) with a default value of 1.0f. It can be adjusted at runtime or through configuration files.

This variable interacts closely with SkipBackFaceHitDistance, as mentioned in its description. It’s used in conjunction with other Lumen hardware ray tracing parameters in the FLumenHardwareRayTracingUniformBufferParameters struct.

Developers should be aware that this variable is specific to two-sided materials and is intended as a workaround for situations where SkipBackFaceHitDistance is not effective. It’s particularly relevant for scenes with foliage using Nanite fallback meshes.

Best practices for using this variable include:

  1. Only adjust it if you’re experiencing self-intersection artifacts with two-sided materials, particularly foliage.
  2. Start with small adjustments from the default value and observe the results.
  3. Consider the performance impact of skipping hits, as it may affect the accuracy of lighting calculations.

Regarding the associated variable CVarLumenHardwareRayTracingSkipTwoSidedHitDistance:

This is the actual console variable that stores and manages the value of r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance. It’s defined using TAutoConsoleVariable, which allows it to be adjusted at runtime.

The variable is used in the SetupLumenHardwareRayTracingUniformBuffer function to populate the FLumenHardwareRayTracingUniformBufferParameters struct. This suggests that the value is passed to the GPU for use in shader code related to Lumen’s hardware ray tracing.

Developers should note that this variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating that it can be used for performance scaling and is safe to modify on the render thread.

When working with this variable, developers should ensure that any modifications are made in a thread-safe manner, preferably using the appropriate Unreal Engine functions for modifying console variables.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingMaterials.cpp:25

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarLumenHardwareRayTracingSkipTwoSidedHitDistance(
	TEXT("r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance"),
	1.0f,
	TEXT("When the SkipBackFaceHitDistance is enabled, the first two-sided material hit within this distance will be skipped. This is useful for avoiding self-intersections with the Nanite fallback mesh on foliage, as SkipBackFaceHitDistance doesn't work on two sided materials."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

namespace LumenHardwareRayTracing

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingMaterials.cpp:24

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarLumenHardwareRayTracingSkipTwoSidedHitDistance(
	TEXT("r.Lumen.HardwareRayTracing.SkipTwoSidedHitDistance"),
	1.0f,
	TEXT("When the SkipBackFaceHitDistance is enabled, the first two-sided material hit within this distance will be skipped. This is useful for avoiding self-intersections with the Nanite fallback mesh on foliage, as SkipBackFaceHitDistance doesn't work on two sided materials."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingMaterials.cpp:117

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::SetupLumenHardwareRayTracingUniformBuffer

Source code excerpt:

	FLumenHardwareRayTracingUniformBufferParameters* LumenHardwareRayTracingUniformBufferParameters = GraphBuilder.AllocParameters<FLumenHardwareRayTracingUniformBufferParameters>();
	LumenHardwareRayTracingUniformBufferParameters->SkipBackFaceHitDistance = CVarLumenHardwareRayTracingSkipBackFaceHitDistance.GetValueOnRenderThread();
	LumenHardwareRayTracingUniformBufferParameters->SkipTwoSidedHitDistance = CVarLumenHardwareRayTracingSkipTwoSidedHitDistance.GetValueOnRenderThread();
	LumenHardwareRayTracingUniformBufferParameters->SkipTranslucent         = LumenReflections::UseTranslucentRayTracing(View) ? 0.0f : 1.0f;
	View.LumenHardwareRayTracingUniformBuffer = GraphBuilder.CreateUniformBuffer(LumenHardwareRayTracingUniformBufferParameters);
}

uint32 CalculateLumenHardwareRayTracingUserData(const FRayTracingMeshCommand& MeshCommand)
{