r.DistanceFields

r.DistanceFields

#Overview

name: r.DistanceFields

The value of this variable can be defined or overridden in .ini config files. 4 .ini config files referencing this setting variable.

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DistanceFields is to enable or disable distance fields rendering in Unreal Engine 5. Distance fields are a spatial representation of geometry used for various rendering techniques, including ambient occlusion, soft shadows, and global illumination.

The r.DistanceFields variable is primarily used by the rendering system in Unreal Engine. It is referenced in the RenderCore module and is utilized by various target platform implementations, including Android and iOS.

The value of this variable is set through a console variable (CVar) system. It is initialized in the RenderUtils.cpp file with a default value of 1 (enabled). The value can be changed at runtime through console commands or configuration files.

This variable interacts with other rendering-related variables and systems. For example, it is used in conjunction with ray tracing settings and affects the behavior of selective base pass outputs.

Developers should be aware that enabling distance fields can have performance implications, especially on mobile platforms. It’s important to consider the target hardware capabilities when deciding whether to use distance fields.

Best practices when using this variable include:

  1. Evaluating the performance impact on your target platforms before enabling distance fields.
  2. Using it in combination with other rendering features to achieve the desired visual quality and performance balance.
  3. Testing thoroughly on all target platforms to ensure consistent behavior and performance.
  4. Considering providing user options to toggle distance fields on/off for performance reasons, especially on lower-end devices.

By understanding and properly utilizing the r.DistanceFields setting, developers can leverage advanced rendering techniques while maintaining optimal performance across various platforms.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:805, section: [Android DeviceProfile]

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:912, section: [Android_Vulkan_SM5 DeviceProfile]

Location: <Workspace>/Engine/Config/Android/AndroidEngine.ini:94, section: [/Script/Engine.RendererSettings]

Location: <Workspace>/Engine/Config/IOS/BaseIOSEngine.ini:12, section: [/Script/Engine.RendererSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:693

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarDistanceFields(
	TEXT("r.DistanceFields"),
	1,
	TEXT("Enables distance fields rendering.\n") \
	TEXT(" 0: Disabled.\n") \
	TEXT(" 1: Enabled."),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
	);

#Loc: <Workspace>/Engine/Source/Developer/Android/AndroidTargetPlatformSettings/Private/AndroidTargetPlatformSettings.cpp:17

Scope (from outer to inner):

file
function     FAndroidTargetPlatformSettings::FAndroidTargetPlatformSettings

Source code excerpt:

	TextureLODSettings = nullptr; // These are registered by the device profile system.
	StaticMeshLODSettings.Initialize(this);
	GetConfigSystem()->GetBool(TEXT("/Script/Engine.RendererSettings"), TEXT("r.DistanceFields"), bDistanceField, GEngineIni);
	GetConfigSystem()->GetInt(TEXT("/Script/Engine.RendererSettings"), TEXT("r.Mobile.ShadingPath"), MobileShadingPath, GEngineIni);
	GetConfigSystem()->GetBool(TEXT("/Script/Engine.RendererSettings"), TEXT("r.Mobile.Forward.EnableClusteredReflections"), bMobileForwardEnableClusteredReflections, GEngineIni);
	GetConfigSystem()->GetBool(TEXT("/Script/Engine.RendererSettings"), TEXT("r.Mobile.VirtualTextures"), bMobileVirtualTextures, GEngineIni);
#endif
}

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSTargetPlatform/Private/IOSTargetPlatform.cpp:41

Scope (from outer to inner):

file
function     FIOSTargetPlatform::FIOSTargetPlatform

Source code excerpt:

	TextureLODSettings = nullptr; // TextureLODSettings are registered by the device profile.
	StaticMeshLODSettings.Initialize(this);
	GetConfigSystem()->GetBool(TEXT("/Script/Engine.RendererSettings"), TEXT("r.DistanceFields"), bDistanceField, GEngineIni);
	GetConfigSystem()->GetInt(TEXT("/Script/Engine.RendererSettings"), TEXT("r.Mobile.ShadingPath"), MobileShadingPath, GEngineIni);
	GetConfigSystem()->GetBool(TEXT("/Script/Engine.RendererSettings"), TEXT("r.Mobile.Forward.EnableClusteredReflections"), bMobileForwardEnableClusteredReflections, GEngineIni);
	GetConfigSystem()->GetBool(TEXT("/Script/Engine.RendererSettings"), TEXT("r.Mobile.VirtualTextures"), bMobileVirtualTextures, GEngineIni);
#endif // #if WITH_ENGINE

	// initialize the connected device detector

#Loc: <Workspace>/Engine/Source/Developer/TargetPlatform/Private/TargetPlatformBase.cpp:46

Scope (from outer to inner):

file
function     bool FTargetPlatformBase::UsesDistanceFields

Source code excerpt:

bool FTargetPlatformBase::UsesDistanceFields() const
{
	static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DistanceFields"));
	return CVar ? (CVar->GetInt() != 0) : false;
}

bool FTargetPlatformBase::UsesRayTracing() const
{
	static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.RayTracing"));

#Loc: <Workspace>/Engine/Source/Developer/TargetPlatform/Private/TargetPlatformSettingsBase.cpp:35

Scope (from outer to inner):

file
function     bool FTargetPlatformSettingsBase::UsesDistanceFields

Source code excerpt:

bool FTargetPlatformSettingsBase::UsesDistanceFields() const
{
	static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DistanceFields"));
	return CVar ? (CVar->GetInt() != 0) : false;
}

bool FTargetPlatformSettingsBase::UsesRayTracing() const
{
	static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.RayTracing"));

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:752

Scope (from outer to inner):

file
function     void RenderUtilsInit

Source code excerpt:

	GSelectiveBasePassOutputsPlatformMask.Init(SelectiveBasePassOutputsCVar && SelectiveBasePassOutputsCVar->GetInt(), EShaderPlatform::SP_NumPlatforms);

	static IConsoleVariable* DistanceFieldsCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DistanceFields")); 
	GDistanceFieldsPlatformMask.Init(DistanceFieldsCVar && DistanceFieldsCVar->GetInt(), EShaderPlatform::SP_NumPlatforms);

	static IConsoleVariable* RayTracingCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.RayTracing"));

	GSimpleSkyDiffusePlatformMask.Init(false, EShaderPlatform::SP_NumPlatforms);
	GVelocityEncodeDepthPlatformMask.Init(false, EShaderPlatform::SP_NumPlatforms);