Skip to main content
Version: 15.x (API 15) [Current]

Interface IFontAtlas

Wrapper for Dalamud.Bindings.ImGui.ImFontAtlasPtr.

Not intended for plugins to implement.

Assembly: Dalamud.dll​
Declaration
public interface IFontAtlas : IDisposable

Properties​

Name​

Gets the name of the atlas. For logging and debugging purposes.

Declaration
string Name { get; }

AutoRebuildMode​

Gets a value how the atlas should be rebuilt when the relevant Dalamud Configuration changes.

Declaration
FontAtlasAutoRebuildMode AutoRebuildMode { get; }

ImAtlas​

Gets the font atlas. Might be empty.

Declaration
ImFontAtlasPtr ImAtlas { get; }

BuildTask​

Gets the task that represents the current font rebuild state.

Declaration
Task BuildTask { get; }

HasBuiltAtlas​

Gets a value indicating whether there exists any built atlas, regardless of Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildTask.

Declaration
bool HasBuiltAtlas { get; }

IsGlobalScaled​

Gets a value indicating whether this font atlas is under the effect of global scale.

Declaration
bool IsGlobalScaled { get; }

Methods​

SuppressAutoRebuild()​

Suppresses automatically rebuilding fonts for the scope.

Declaration
IDisposable SuppressAutoRebuild()
Returns​

System.IDisposable: An instance of System.IDisposable that will release the suppression.

Remarks​

Use when you will be creating multiple new handles, and want rebuild to trigger only when you're done doing so. This function will effectively do nothing, if Dalamud.Interface.ManagedFontAtlas.IFontAtlas.AutoRebuildMode is set to Dalamud.Interface.ManagedFontAtlas.FontAtlasAutoRebuildMode.Disable.

Examples​
using (atlas.SuppressBuild()) {
    this.font1 = atlas.NewGameFontHandle(...);
    this.font2 = atlas.NewDelegateFontHandle(...);
}

NewGameFontHandle(GameFontStyle)​

Creates a new Dalamud.Interface.ManagedFontAtlas.IFontHandle from game's built-in fonts.

Declaration
IFontHandle NewGameFontHandle(GameFontStyle style)
Returns​

Dalamud.Interface.ManagedFontAtlas.IFontHandle: Handle to a font that may or may not be ready yet.

Parameters​
TypeNameDescription
Dalamud.Interface.GameFonts.GameFontStylestyleFont to use.
Exceptions​

System.InvalidOperationException
When called during Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildStepChange and alike. Move the font handle creating code outside those handlers, and only initialize them once. Call System.IDisposable.Dispose on a previous font handle if you're replacing one.

Remarks​

This function does not throw. Dalamud.Interface.ManagedFontAtlas.IFontHandle.LoadException will be populated instead, if the build procedure has failed. Dalamud.Interface.ManagedFontAtlas.IFontHandle.Push() can be used regardless of the state of the font handle.

NewDelegateFontHandle(FontAtlasBuildStepDelegate)​

Creates a new IFontHandle using your own callbacks.

Declaration
IFontHandle NewDelegateFontHandle(FontAtlasBuildStepDelegate buildStepDelegate)
Returns​

Dalamud.Interface.ManagedFontAtlas.IFontHandle: Handle to a font that may or may not be ready yet.

Parameters​
TypeNameDescription
Dalamud.Interface.ManagedFontAtlas.FontAtlasBuildStepDelegatebuildStepDelegateCallback for Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildStepChange.
Exceptions​

System.InvalidOperationException
When called during Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildStepChange and alike. Move the font handle creating code outside those handlers, and only initialize them once. Call System.IDisposable.Dispose on a previous font handle if you're replacing one.

Remarks​

Consider calling Dalamud.Interface.ManagedFontAtlas.IFontAtlasBuildToolkitPreBuild.AttachExtraGlyphsForDalamudLanguage(Dalamud.Interface.ManagedFontAtlas.SafeFontConfig@) to support glyphs that are not supplied by the game by default; this mostly affects Chinese and Korean language users.

Examples​

On initialization:

this.fontHandle = atlas.NewDelegateFontHandle(e => e.OnPreBuild(tk => {
    var config = new SafeFontConfig { SizePx = UiBuilder.DefaultFontSizePx };
    config.MergeFont = tk.AddFontFromFile(@"C:\Windows\Fonts\comic.ttf", config);
    tk.AddGameSymbol(config);
    tk.AddExtraGlyphsForDalamudLanguage(config);
    // optionally do the following if you have to add more than one font here,
    // to specify which font added during this delegate is the final font to use.
    tk.Font = config.MergeFont;
}));
// or
this.fontHandle = atlas.NewDelegateFontHandle(e => e.OnPreBuild(tk => tk.AddDalamudDefaultFont(36)));

On use:

using (this.fontHandle.Push())
    ImGui.Text("Example"u8);

BuildFontsOnNextFrame()​

Queues rebuilding fonts, on the main thread.

Note that Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildTask would not necessarily get changed from calling this function.

Declaration
void BuildFontsOnNextFrame()
Exceptions​

System.InvalidOperationException
If Dalamud.Interface.ManagedFontAtlas.IFontAtlas.AutoRebuildMode is Dalamud.Interface.ManagedFontAtlas.FontAtlasAutoRebuildMode.Async.

Remarks​

Using this method will block the main thread on rebuilding fonts, effectively calling Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildFontsImmediately() from the main thread. Consider migrating to Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildFontsAsync().

BuildFontsImmediately()​

Rebuilds fonts immediately, on the current thread.

Declaration
void BuildFontsImmediately()
Exceptions​

System.InvalidOperationException
If Dalamud.Interface.ManagedFontAtlas.IFontAtlas.AutoRebuildMode is Dalamud.Interface.ManagedFontAtlas.FontAtlasAutoRebuildMode.Async.

BuildFontsAsync()​

Rebuilds fonts asynchronously, on any thread.

Declaration
Task BuildFontsAsync()
Returns​

System.Threading.Tasks.Task: The task.

Exceptions​

System.InvalidOperationException
If Dalamud.Interface.ManagedFontAtlas.IFontAtlas.AutoRebuildMode is Dalamud.Interface.ManagedFontAtlas.FontAtlasAutoRebuildMode.OnNewFrame.

Events​

BuildStepChange​

Event to be called on build step changes.

Dalamud.Interface.ManagedFontAtlas.IFontAtlasBuildToolkit.Font is meaningless for this event.

Declaration
event FontAtlasBuildStepDelegate? BuildStepChange
Event Type​

Dalamud.Interface.ManagedFontAtlas.FontAtlasBuildStepDelegate

RebuildRecommend​

Event fired when a font rebuild operation is recommended.

This event will be invoked from the main thread.

Reasons for the event include changes in Dalamud.Interface.Utility.ImGuiHelpers.GlobalScale and initialization of new associated font handles.

Declaration
event Action? RebuildRecommend
Event Type​

System.Action

Remarks​

You should call Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildFontsAsync() or Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildFontsOnNextFrame() if Dalamud.Interface.ManagedFontAtlas.IFontAtlas.AutoRebuildMode is not set to true.

Avoid calling Dalamud.Interface.ManagedFontAtlas.IFontAtlas.BuildFontsImmediately() here; it will block the main thread.