r.Lumen.HardwareRayTracing.LightingMode

r.Lumen.HardwareRayTracing.LightingMode

#Overview

name: r.Lumen.HardwareRayTracing.LightingMode

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

It is referenced in 10 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.HardwareRayTracing.LightingMode is to control how Lumen Reflection rays are lit when Lumen is using Hardware Ray Tracing in Unreal Engine 5. This setting variable is primarily used for the rendering system, specifically for the Lumen global illumination and reflection system.

This setting variable is primarily utilized by the Lumen subsystem within the Renderer module of Unreal Engine 5. It’s specifically used in the hardware ray tracing component of Lumen.

The value of this variable is set in the URendererSettings class, which is part of the Engine module. It can be modified through the project settings or via console commands.

The r.Lumen.HardwareRayTracing.LightingMode variable interacts closely with the LumenRayLightingMode variable. They share the same value and are used interchangeably in different parts of the code.

Developers must be aware that this variable only takes effect when hardware ray tracing is enabled for Lumen. It offers different lighting modes, ranging from using the surface cache for lighting (fastest) to evaluating materials and direct lighting at hit points (highest quality but more performance-intensive).

Best practices when using this variable include:

  1. Consider the performance implications of higher quality settings.
  2. Ensure that hardware ray tracing is supported and enabled before adjusting this setting.
  3. Test different modes to find the best balance between visual quality and performance for your specific project.

Regarding the associated variable LumenRayLightingMode:

The purpose of LumenRayLightingMode is the same as r.Lumen.HardwareRayTracing.LightingMode, controlling the lighting mode for Lumen reflections when using hardware ray tracing.

It’s used in the Engine and Renderer modules, particularly in post-processing and scene view calculations.

The value is set in the URendererSettings class and can be overridden in post-process volumes.

This variable interacts directly with r.Lumen.HardwareRayTracing.LightingMode and is used to determine the actual lighting mode in the renderer.

Developers should be aware that this variable can be overridden on a per-view basis, allowing for more fine-grained control of the lighting mode in different parts of a scene.

Best practices include considering the impact on performance when changing this setting, especially in performance-critical areas of your game or application.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:505

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:

	UPROPERTY(config, EditAnywhere, Category=Lumen, meta=(
		EditCondition = "bEnableRayTracing && bUseHardwareRayTracingForLumen",
		ConsoleVariable="r.Lumen.HardwareRayTracing.LightingMode", DisplayName = "Ray Lighting Mode",
		ToolTip="Controls how Lumen Reflection rays are lit when Lumen is using Hardware Ray Tracing.  By default, Lumen uses the Surface Cache for best performance, but can be set to 'Hit Lighting' for higher quality."))
	ELumenRayLightingMode LumenRayLightingMode;

	UPROPERTY(config, EditAnywhere, Category = Lumen, meta = (
		ConsoleVariable = "r.Lumen.TranslucencyReflections.FrontLayer.EnableForProject", DisplayName = "High Quality Translucency Reflections",
		ToolTip = "Whether to use high quality mirror reflections on the front layer of translucent surfaces.  Other layers will use the lower quality Radiance Cache method that can only produce glossy reflections.  Increases GPU cost when enabled."))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:27

Scope: file

Source code excerpt:

// Note: Driven by URendererSettings and must match the enum exposed there
static TAutoConsoleVariable<int32> CVarLumenHardwareRayTracingLightingMode(
	TEXT("r.Lumen.HardwareRayTracing.LightingMode"),
	0,
	TEXT("Determines the lighting mode (Default = 0)\n")
	TEXT("0: interpolate final lighting from the surface cache\n")
	TEXT("1: evaluate material, and interpolate irradiance and indirect irradiance from the surface cache\n")
	TEXT("2: evaluate material and direct lighting, and interpolate indirect irradiance from the surface cache\n")
	TEXT("3: evaluate material, direct lighting, and unshadowed skylighting at the hit point"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:507

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:

		ConsoleVariable="r.Lumen.HardwareRayTracing.LightingMode", DisplayName = "Ray Lighting Mode",
		ToolTip="Controls how Lumen Reflection rays are lit when Lumen is using Hardware Ray Tracing.  By default, Lumen uses the Surface Cache for best performance, but can be set to 'Hit Lighting' for higher quality."))
	ELumenRayLightingMode LumenRayLightingMode;

	UPROPERTY(config, EditAnywhere, Category = Lumen, meta = (
		ConsoleVariable = "r.Lumen.TranslucencyReflections.FrontLayer.EnableForProject", DisplayName = "High Quality Translucency Reflections",
		ToolTip = "Whether to use high quality mirror reflections on the front layer of translucent surfaces.  Other layers will use the lower quality Radiance Cache method that can only produce glossy reflections.  Increases GPU cost when enabled."))
	uint32 LumenFrontLayerTranslucencyReflections : 1;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1677

Scope: file

Source code excerpt:

	/** Controls how Lumen rays are lit when Lumen is using Hardware Ray Tracing.  By default, Lumen uses the Surface Cache for best performance, but can be set to 'Hit Lighting' for higher quality. */
	UPROPERTY(interp, EditAnywhere, BlueprintReadWrite, Category = "Reflections|Lumen Reflections", meta = (editcondition = "bOverride_LumenRayLightingMode", DisplayName = "Ray Lighting Mode"))
	ELumenRayLightingModeOverride LumenRayLightingMode;

	/** Whether to use screen space traces for Lumen Reflections. Screen space traces bypass Lumen Scene and instead sample Scene Depth and Color. This improves quality, but at the same time prevents from Lumen Scene only changes like adding emissive objects, which are visible only in Reflections. */
	UPROPERTY(interp, EditAnywhere, BlueprintReadWrite, Category = "Reflections|Lumen Reflections", meta = (editcondition = "bOverride_LumenReflectionsScreenTraces", DisplayName = "Screen Traces"))
	uint8 LumenReflectionsScreenTraces : 1;

	/** Whether to use high quality mirror reflections on the front layer of translucent surfaces.  Other layers will use the lower quality Radiance Cache method that can only produce glossy reflections.  Increases GPU cost when enabled. */

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PostProcessVolume.cpp:207

Scope (from outer to inner):

file
function     bool APostProcessVolume::CanEditChange

Source code excerpt:

			}
			
			if (PropertyName == GET_MEMBER_NAME_STRING_CHECKED(FPostProcessSettings, LumenRayLightingMode))
			{
				static IConsoleVariable* RayTracingCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.RayTracing"));
				if (RayTracingCVar->GetInt() == 0)
				{
					return false;
				}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Scene.cpp:611

Scope (from outer to inner):

file
function     FPostProcessSettings::FPostProcessSettings

Source code excerpt:

	ReflectionMethod = EReflectionMethod::Lumen;
	LumenReflectionQuality = 1;
	LumenRayLightingMode = ELumenRayLightingModeOverride::Default;
	LumenReflectionsScreenTraces = 1;
	LumenFrontLayerTranslucencyReflections = false;
	LumenMaxRoughnessToTraceReflections = 0.4f;
	LumenMaxReflectionBounces = 1;

	LumenMaxRefractionBounces = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:1758

Scope (from outer to inner):

file
function     void FSceneView::OverridePostProcessSettings

Source code excerpt:

		LERP_PP(LumenFullSkylightLeakingDistance);

		SET_PP(LumenRayLightingMode);
		SET_PP(LumenReflectionsScreenTraces);
		SET_PP(LumenFrontLayerTranslucencyReflections);
		SET_PP(LumenMaxRoughnessToTraceReflections);
		SET_PP(LumenMaxReflectionBounces);
		SET_PP(LumenMaxRefractionBounces);
		SET_PP(ReflectionMethod);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:136

Scope (from outer to inner):

file
function     Lumen::EHardwareRayTracingLightingMode Lumen::GetHardwareRayTracingLightingMode

Source code excerpt:


	// Without ray tracing shaders (RayGen) support we can only use Surface Cache mode.
	if (View.FinalPostProcessSettings.LumenRayLightingMode == ELumenRayLightingModeOverride::SurfaceCache || !LumenHardwareRayTracing::IsRayGenSupported())
	{
		LightingModeInt = static_cast<int32>(Lumen::EHardwareRayTracingLightingMode::LightingFromSurfaceCache);
	}
	else if (View.FinalPostProcessSettings.LumenRayLightingMode == ELumenRayLightingModeOverride::HitLighting)
	{
		LightingModeInt = static_cast<int32>(Lumen::EHardwareRayTracingLightingMode::EvaluateMaterialAndDirectLighting);
	}

	LightingModeInt = FMath::Clamp<int32>(LightingModeInt, 0, (int32)Lumen::EHardwareRayTracingLightingMode::MAX - 1);
	return static_cast<Lumen::EHardwareRayTracingLightingMode>(LightingModeInt);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:26

Scope: file

Source code excerpt:


// Note: Driven by URendererSettings and must match the enum exposed there
static TAutoConsoleVariable<int32> CVarLumenHardwareRayTracingLightingMode(
	TEXT("r.Lumen.HardwareRayTracing.LightingMode"),
	0,
	TEXT("Determines the lighting mode (Default = 0)\n")
	TEXT("0: interpolate final lighting from the surface cache\n")
	TEXT("1: evaluate material, and interpolate irradiance and indirect irradiance from the surface cache\n")
	TEXT("2: evaluate material and direct lighting, and interpolate indirect irradiance from the surface cache\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:133

Scope (from outer to inner):

file
function     Lumen::EHardwareRayTracingLightingMode Lumen::GetHardwareRayTracingLightingMode

Source code excerpt:

	}

	int32 LightingModeInt = CVarLumenHardwareRayTracingLightingMode.GetValueOnAnyThread();

	// Without ray tracing shaders (RayGen) support we can only use Surface Cache mode.
	if (View.FinalPostProcessSettings.LumenRayLightingMode == ELumenRayLightingModeOverride::SurfaceCache || !LumenHardwareRayTracing::IsRayGenSupported())
	{
		LightingModeInt = static_cast<int32>(Lumen::EHardwareRayTracingLightingMode::LightingFromSurfaceCache);
	}