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

Type	Name	Description
Dalamud.Interface.GameFonts.GameFontStyle	style	Font 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

Type	Name	Description
Dalamud.Interface.ManagedFontAtlas.FontAtlasBuildStepDelegate	buildStepDelegate	Callback 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.