r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias

r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias

#Overview

name: r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias

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.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias is to apply a projection bias for occlusion rays in Lumen’s hardware ray tracing system for direct lighting. This setting is specifically related to the ray-tracing heightfield representation.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine 5’s rendering module. It’s specifically utilized in the hardware ray tracing component of Lumen’s direct lighting system.

The value of this variable is set through a console variable (CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBias) in the Unreal Engine’s rendering system. It’s defined with a default value of 0 and can be modified at runtime.

This variable interacts closely with FLumenDirectLightingHardwareRayTracingBatchedRGS::FEnableHeightfieldProjectionBias, which is set based on whether this console variable is non-zero.

Developers should be aware that enabling this feature (by setting the value to non-zero) will change how occlusion rays are processed in the ray-tracing system. This could potentially impact performance and visual results, particularly in scenes with complex heightfield representations.

Best practices when using this variable include:

  1. Testing thoroughly with and without the bias enabled to understand its impact on your specific scene.
  2. Considering performance implications, especially in scenes with complex geometry.
  3. Using in conjunction with other Lumen settings for optimal results.

Regarding the associated variable CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBias:

This is the actual console variable that controls the r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias setting. It’s defined as an integer, suggesting it’s likely used as a boolean flag (0 for off, non-zero for on).

The purpose of this variable is the same as r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias - to control the application of projection bias for occlusion rays in Lumen’s hardware ray tracing system.

It’s used in the same Lumen subsystem and is checked in several places to determine whether to enable the heightfield projection bias feature.

The value is set when the engine initializes the console variables, but can be changed at runtime through console commands.

Developers should be aware that this variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, meaning it can be safely changed at runtime and may be automatically adjusted based on scalability settings.

Best practices include using this variable in conjunction with other Lumen and ray tracing settings for optimal performance and visual quality, and thoroughly testing its impact on your specific scenes and use cases.

#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:24

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int> CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBias(
	TEXT("r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias"),
	0,
	TEXT("Applies a projection bias such that an occlusion ray starts on the ray-tracing heightfield representation.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBiasSearchRadius(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int> CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBias(
	TEXT("r.LumenScene.DirectLighting.HardwareRayTracing.HeightfieldProjectionBias"),
	0,
	TEXT("Applies a projection bias such that an occlusion ray starts on the ray-tracing heightfield representation.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::PrepareLumenHardwareRayTracingDirectLightingLumenMaterial

Source code excerpt:

		FLumenDirectLightingHardwareRayTracingBatchedRGS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FLumenDirectLightingHardwareRayTracingBatchedRGS::FEnableFarFieldTracing>(Lumen::UseFarField(*View.Family));
		PermutationVector.Set<FLumenDirectLightingHardwareRayTracingBatchedRGS::FEnableHeightfieldProjectionBias>(CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBias.GetValueOnRenderThread() != 0);
		TShaderRef<FLumenDirectLightingHardwareRayTracingBatchedRGS> RayGenerationShader = View.ShaderMap->GetShader<FLumenDirectLightingHardwareRayTracingBatchedRGS>(PermutationVector);
		OutRayGenShaders.Add(RayGenerationShader.GetRayTracingShader());
	}
}

void SetLumenHardwareRayTracedDirectLightingShadowsParameters(

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

Scope (from outer to inner):

file
function     void TraceLumenHardwareRayTracedDirectLightingShadows

Source code excerpt:

	FLumenDirectLightingHardwareRayTracingBatchedRGS::FPermutationDomain PermutationVector;
	PermutationVector.Set<FLumenDirectLightingHardwareRayTracingBatchedRGS::FEnableFarFieldTracing>(Lumen::UseFarField(*View.Family));
	PermutationVector.Set<FLumenDirectLightingHardwareRayTracingBatchedRGS::FEnableHeightfieldProjectionBias>(CVarLumenSceneDirectLightingHardwareRayTracingHeightfieldProjectionBias.GetValueOnRenderThread() != 0);

	if (bInlineRayTracing)
	{
		FLumenDirectLightingHardwareRayTracingBatchedCS::AddLumenRayTracingDispatchIndirect(
			GraphBuilder, 
			RDG_EVENT_NAME("LumenDirectLightingHardwareRayTracingCS"),