r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBiasSearchRadius

r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBiasSearchRadius

#Overview

name: r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBiasSearchRadius

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.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBiasSearchRadius is to control the search radius for heightfield projection bias in Lumen’s hardware ray-traced direct lighting system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically in the context of hardware ray tracing for direct lighting.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the Lumen subsystem for scene direct lighting with hardware ray tracing. It’s defined in the LumenSceneDirectLightingHardwareRayTracing.cpp file, which suggests its relevance to the Lumen raytracing pipeline.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 256, but can be changed via console commands or through engine configuration files.

The associated variable CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBiasSearchRadius directly interacts with this setting. It’s used to retrieve the current value of the setting in the GetHeightfieldProjectionBiasSearchRadius() function.

Developers must be aware that this variable affects the performance-quality tradeoff in Lumen’s hardware ray tracing system. A larger search radius can potentially provide more accurate results but at the cost of increased computational load. The comment in the code explicitly states that “Larger search radius corresponds to increased traversal cost.”

Best practices when using this variable include:

  1. Carefully balancing performance and quality based on the target hardware and scene complexity.
  2. Experimenting with different values to find the optimal setting for specific scenes or use cases.
  3. Considering scalability across different hardware configurations, as indicated by the ECVF_Scalability flag.
  4. Being cautious when modifying this value at runtime, as it’s marked as render thread safe (ECVF_RenderThreadSafe).

Regarding the associated variable CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBiasSearchRadius, it serves as the actual console variable that stores and provides access to the setting’s value. It’s used in the GetHeightfieldProjectionBiasSearchRadius() function to retrieve the current value, ensuring it’s never negative. This function is likely called during the ray tracing process to determine the appropriate search radius for heightfield projection bias.

When working with this associated variable, developers should:

  1. Use the GetValueOnRenderThread() method to safely access its value from the render thread.
  2. Be aware that changes to this CVar will directly affect the behavior of the heightfield projection bias in Lumen’s hardware ray tracing system.
  3. Consider exposing this setting in user-facing graphics options if fine-tuning is necessary for different hardware configurations or scene types.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLightingHardwareRayTracing.cpp:31

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBiasSearchRadius(
	TEXT("r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBiasSearchRadius"),
	256,
	TEXT("Determines the search radius for heightfield projection bias. Larger search radius corresponds to increased traversal cost (default = 256).\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#endif // RHI_RAYTRACING

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLightingHardwareRayTracing.cpp:30

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBiasSearchRadius(
	TEXT("r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBiasSearchRadius"),
	256,
	TEXT("Determines the search radius for heightfield projection bias. Larger search radius corresponds to increased traversal cost (default = 256).\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLightingHardwareRayTracing.cpp:130

Scope (from outer to inner):

file
function     float GetHeightfieldProjectionBiasSearchRadius

Source code excerpt:

float GetHeightfieldProjectionBiasSearchRadius()
{
	return FMath::Max(CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBiasSearchRadius.GetValueOnRenderThread(), 0);
}

void FDeferredShadingSceneRenderer::PrepareLumenHardwareRayTracingDirectLightingLumenMaterial(const FViewInfo& View, TArray<FRHIRayTracingShader*>& OutRayGenShaders)
{
	if (Lumen::UseHardwareRayTracedDirectLighting(*View.Family))
	{