r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias

r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias

#Overview

name: r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias

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

• type: Var
• help: Bias along the shading normal, useful when the Ray Tracing geometry doesn\'t match the GBuffer (Nanite Proxy geometry)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias is to provide a bias along the shading normal during hardware ray tracing in Lumen’s screen probe gathering process. This setting is particularly useful when the ray tracing geometry doesn’t match the GBuffer, which can occur with Nanite Proxy geometry.

This setting variable is primarily used by the Lumen subsystem within Unreal Engine 5’s rendering system. Specifically, it’s utilized in the hardware ray tracing component of Lumen’s screen probe gathering process.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined with a default value of 0.1f, but can be adjusted at runtime or through configuration files.

The variable interacts directly with its associated variable CVarLumenHardwareRayTracingNormalBias. They share the same value and are used interchangeably in the code.

Developers should be aware that this variable affects the accuracy and visual quality of ray-traced reflections and global illumination in scenes where the ray tracing geometry might not perfectly align with the GBuffer data. Adjusting this value can help reduce artifacts in such scenarios.

Best practices when using this variable include:

1. Start with the default value (0.1f) and adjust as needed.
2. Monitor performance impacts when modifying this value, as it can affect ray tracing workload.
3. Test the variable’s effects in scenes with complex geometry, especially those using Nanite.
4. Consider the interaction between this bias and other ray tracing parameters for optimal results.

Regarding the associated variable CVarLumenHardwareRayTracingNormalBias:

The purpose of CVarLumenHardwareRayTracingNormalBias is identical to r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias. It’s the internal representation of the console variable within the C++ code.

This variable is used directly in the Lumen subsystem, specifically in the hardware ray tracing component of the screen probe gathering process.

The value is set when the console variable is initialized and can be accessed on the render thread using the GetValueOnRenderThread() method.

CVarLumenHardwareRayTracingNormalBias interacts directly with r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias, as they represent the same setting.

Developers should be aware that this is the actual variable used in the rendering code, while r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias is the console command to modify it.

Best practices for using CVarLumenHardwareRayTracingNormalBias include:

1. Access the value using GetValueOnRenderThread() when used in render thread operations.
2. Avoid directly modifying this variable; instead, use the console command to ensure thread-safe modifications.
3. Consider caching the value if used frequently in performance-critical sections of code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeHardwareRayTracing.cpp:29

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarLumenHardwareRayTracingNormalBias(
	TEXT("r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias"),
	.1f,
	TEXT("Bias along the shading normal, useful when the Ray Tracing geometry doesn't match the GBuffer (Nanite Proxy geometry)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenScreenProbeGatherHardwareRayTracingRetraceFarField(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeHardwareRayTracing.cpp:28

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarLumenHardwareRayTracingNormalBias(
	TEXT("r.Lumen.ScreenProbeGather.HardwareRayTracing.NormalBias"),
	.1f,
	TEXT("Bias along the shading normal, useful when the Ray Tracing geometry doesn't match the GBuffer (Nanite Proxy geometry)"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeHardwareRayTracing.cpp:290

Scope (from outer to inner):

file
function     void DispatchRayGenOrComputeShader

Source code excerpt:

		Parameters->FarFieldReferencePos = (FVector3f)Lumen::GetFarFieldReferencePos();
		Parameters->PullbackBias = Lumen::GetHardwareRayTracingPullbackBias();
		Parameters->NormalBias = CVarLumenHardwareRayTracingNormalBias.GetValueOnRenderThread();
		Parameters->MaxTraversalIterations = LumenHardwareRayTracing::GetMaxTraversalIterations();
		Parameters->MinTraceDistanceToSampleSurfaceCache = LumenHardwareRayTracing::GetMinTraceDistanceToSampleSurfaceCache();
	}

	const LumenScreenProbeGather::ERayTracingPass RayTracingPass = PermutationVector.Get<FLumenScreenProbeGatherHardwareRayTracing::FRayTracingPass>();
	const FString RayTracingPassName = RayTracingPass == LumenScreenProbeGather::ERayTracingPass::FarField ? TEXT("far-field") : TEXT("default");