r.Lumen.Reflections.HiResSurface

r.Lumen.Reflections.HiResSurface

#Overview

name: r.Lumen.Reflections.HiResSurface

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

• type: Var
• help: Whether reflections should sample highest available surface data or use lowest res always resident pages.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Reflections.HiResSurface is to control whether Lumen reflections should sample the highest available surface data or use the lowest resolution always-resident pages. This setting variable is part of Unreal Engine 5’s Lumen global illumination and reflection system.

This setting variable is primarily used in the Lumen Reflections subsystem, which is part of the Renderer module in Unreal Engine 5. It directly affects the quality and performance of real-time reflections in scenes using Lumen.

The value of this variable is set through a console variable (CVar) system. It’s defined with a default value of 1 (enabled) and can be changed at runtime or through configuration files.

The associated variable CVarLumenReflectionsHiResSurface interacts directly with r.Lumen.Reflections.HiResSurface. They share the same value and purpose.

Developers should be aware that:

1. Enabling this variable (set to 1) will use higher resolution surface data for reflections, potentially increasing visual quality but also increasing performance costs.
2. Disabling it (set to 0) will use lower resolution data, which may be less accurate but more performance-friendly.
3. This setting is marked with ECVF_Scalability, indicating it’s intended to be used as a scalability option to balance between quality and performance.

Best practices when using this variable include:

1. Consider using it as part of a broader scalability settings system, allowing users to adjust reflection quality based on their hardware capabilities.
2. Test the visual and performance impact in various scenarios to determine the best default setting for your project.
3. Be mindful of the performance implications when enabling high-resolution surface sampling, especially on lower-end hardware.

Regarding the associated variable CVarLumenReflectionsHiResSurface:

• It’s a TAutoConsoleVariable that directly controls the r.Lumen.Reflections.HiResSurface setting.
• It’s used in the RenderLumenReflections function to set the UseHighResSurface parameter for reflection tracing.
• Developers can access its value using the GetValueOnRenderThread() method, which is thread-safe for the render thread.
• When modifying this variable, ensure that changes are made in a thread-safe manner, respecting the ECVF_RenderThreadSafe flag it’s created with.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:267

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLumenReflectionsHiResSurface(
	TEXT("r.Lumen.Reflections.HiResSurface"),
	1,
	TEXT("Whether reflections should sample highest available surface data or use lowest res always resident pages."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReflectionsSpecularScale = 1.f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:266

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenReflectionsHiResSurface(
	TEXT("r.Lumen.Reflections.HiResSurface"),
	1,
	TEXT("Whether reflections should sample highest available surface data or use lowest res always resident pages."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:1096

Scope (from outer to inner):

file
function     FRDGTextureRef FDeferredShadingSceneRenderer::RenderLumenReflections

Source code excerpt:

	ReflectionTracingParameters.ReflectionPass = (uint32)ReflectionPass;
	ReflectionTracingParameters.UseJitter = bDenoise && GLumenReflectionTemporalFilter ? 1 : 0;
	ReflectionTracingParameters.UseHighResSurface = CVarLumenReflectionsHiResSurface.GetValueOnRenderThread() != 0 ? 1 : 0;
	ReflectionTracingParameters.MaxReflectionBounces = LumenReflections::GetMaxReflectionBounces(View);
	ReflectionTracingParameters.MaxRefractionBounces = LumenReflections::GetMaxRefractionBounces(View);
	ReflectionTracingParameters.NearFieldMaxTraceDistance = NearFieldMaxTraceDistance;
	ReflectionTracingParameters.FarFieldMaxTraceDistance = bUseFarField ? Lumen::GetFarFieldMaxTraceDistance() : NearFieldMaxTraceDistance;
	ReflectionTracingParameters.NearFieldMaxTraceDistanceDitherScale = Lumen::GetNearFieldMaxTraceDistanceDitherScale(bUseFarField);
	ReflectionTracingParameters.NearFieldSceneRadius = Lumen::GetNearFieldSceneRadius(View, bUseFarField);