Slate.Font.AsyncLazyLoad

Slate.Font.AsyncLazyLoad

#Overview

name: Slate.Font.AsyncLazyLoad

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 Slate.Font.AsyncLazyLoad is to control the asynchronous loading of font faces in the Slate UI system of Unreal Engine 5. It is specifically designed for the font rendering and management subsystem within Slate.

This setting variable is primarily used by the SlateCore module, which is responsible for the core functionality of Unreal Engine’s Slate UI framework. It directly affects the font loading behavior in the FontCacheCompositeFont.cpp file.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files.

The associated variable GAsyncFontLazyLoad interacts directly with Slate.Font.AsyncLazyLoad. They share the same boolean value, with GAsyncFontLazyLoad being the actual variable used in the code logic.

Developers must be aware that when this variable is set to true, unloaded font faces that are lazily loaded will be loaded asynchronously. This means that until the loading is complete, the font won’t measure correctly, which can affect UI layout and appearance. Once the loading is complete, the UI will invalidate and update.

Best practices when using this variable include:

  1. Consider the trade-offs between immediate correct font measurements and potentially faster initial UI loading times.
  2. Be prepared to handle UI invalidation and potential layout shifts when font loading completes.
  3. Use this feature in conjunction with proper UI design that can accommodate temporary inaccuracies in font measurements.
  4. Monitor performance impacts, especially on lower-end devices, as asynchronous loading might affect overall system responsiveness.

Regarding the associated variable GAsyncFontLazyLoad:

The purpose of GAsyncFontLazyLoad is to serve as the actual boolean flag that controls the asynchronous lazy loading behavior of fonts in the Slate system.

It is used directly in the font loading logic within the GetFontFace function of the FCompositeFontCache class. When GAsyncFontLazyLoad is true, the function initiates an asynchronous task (FAsyncLoadFontFaceData) to load the font face data.

The value of GAsyncFontLazyLoad is set through the Slate.Font.AsyncLazyLoad console variable.

Developers should be aware that this variable directly affects the behavior of font loading in performance-critical UI code. Enabling it can improve initial UI load times but may lead to temporary visual inconsistencies until font loading is complete.

Best practices for using GAsyncFontLazyLoad include:

  1. Use it in scenarios where faster initial UI presentation is more critical than immediate visual accuracy.
  2. Implement proper error handling and fallback mechanisms in case of font loading failures.
  3. Consider providing visual feedback to users while fonts are being loaded asynchronously.
  4. Test thoroughly on various devices and with different font sets to ensure the asynchronous loading doesn’t negatively impact the user experience.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/SlateCore/Private/Fonts/FontCacheCompositeFont.cpp:15

Scope: file

Source code excerpt:

static bool GAsyncFontLazyLoad = false;
FAutoConsoleVariableRef CVarAsyncLazyLoad(
	TEXT("Slate.Font.AsyncLazyLoad"),
	GAsyncFontLazyLoad,
	TEXT("Causes unloaded font faces that are lazily loaded, to be loaded asynchronusly, until then the font won't measure correctly.  Once complete the UI will invalidate."));

DECLARE_CYCLE_STAT(TEXT("Load Font"), STAT_SlateLoadFont, STATGROUP_Slate);

class FAsyncLoadFontFaceData : public FNonAbandonableTask

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/SlateCore/Private/Fonts/FontCacheCompositeFont.cpp:13

Scope: file

Source code excerpt:

#include "Trace/SlateMemoryTags.h"

static bool GAsyncFontLazyLoad = false;
FAutoConsoleVariableRef CVarAsyncLazyLoad(
	TEXT("Slate.Font.AsyncLazyLoad"),
	GAsyncFontLazyLoad,
	TEXT("Causes unloaded font faces that are lazily loaded, to be loaded asynchronusly, until then the font won't measure correctly.  Once complete the UI will invalidate."));

DECLARE_CYCLE_STAT(TEXT("Load Font"), STAT_SlateLoadFont, STATGROUP_Slate);

class FAsyncLoadFontFaceData : public FNonAbandonableTask
{

#Loc: <Workspace>/Engine/Source/Runtime/SlateCore/Private/Fonts/FontCacheCompositeFont.cpp:412

Scope (from outer to inner):

file
function     TSharedPtr<FFreeTypeFace> FCompositeFontCache::GetFontFace

Source code excerpt:

			case EFontLoadingPolicy::LazyLoad:
				{
					if (GAsyncFontLazyLoad)
					{
						FAsyncTask<FAsyncLoadFontFaceData>* AsyncFontLoadTaskPtr = new FAsyncTask<FAsyncLoadFontFaceData>(InFontData);
						LoadFontFaceTasks.Add(AsyncFontLoadTaskPtr);
						AsyncFontLoadTaskPtr->StartBackgroundTask();

						FaceAndMemory = MakeShared<FFreeTypeFace>(InFontData.GetLayoutMethod());