Class FontSystem

Namespace

Icy.Rendering.Fonts

Assembly

IcyUI.dll

Manages font loading and resolution.

public class FontSystem : IDisposable

Inheritance

object

FontSystem

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

PropertyReferencesExtensions.ContainsProperty(object, IPropertyReference)

Constructors

FontSystem(IcyConfiguration)

Initializes a new instance of the FontSystem class.

public FontSystem(IcyConfiguration config)

Parameters

config IcyConfiguration

The asset configuration to use for loading font data.

Properties

AreSystemFontsEnabled

Gets a value indicating whether fonts installed on the system can be found by family name.

public bool AreSystemFontsEnabled { get; }

Property Value

bool

Remarks

The system fonts folder is indexed on the first lookup that needs it, not when this turns on.

AtlasPageLimit

Gets or sets the maximal number of texture pages to use in atlas of a single dynamic font family.

public uint AtlasPageLimit { get; set; }

Property Value

uint

Remarks

When imported, dynamic fonts get an expandable texture atlas for rasterized glyphs. Each font family in a single font system has its own atlas instance shared across style and size variations of this font. Dynamic font atlas has support for multiple pages in case of large font sizes or inefficient glyphs placement. By default the number of pages is equal to 4.

It is recommended to have at least 4 pages limit because an atlas groups glyphs by size. Each glyph size category should have its own atlas page for efficient search and placement.

DefaultFontFamily

Gets or sets the font family used by text elements that don't name one of their own.

public string DefaultFontFamily { get; set; }

Property Value

string

Remarks

A TextBlock with an empty FontFamily resolves this family instead, at its own size and style. This is what lets markup declare bare text - <Button>Click Me</Button> creates a TextBlock that never had a family assigned - without silently rendering nothing.

Leave empty to skip straight to FallbackFont. Setting a family that can't be loaded is harmless: GetOrLoad(FontInfo) falls back the same way any other miss does.

FallbackFont

Gets or sets a font to be used when an instance of the requested font couldn't be found or created.

public IFont? FallbackFont { get; set; }

Property Value

IFont

Remarks

The last resort, below DefaultFontFamily: returned by GetOrLoad(FontInfo) whenever the requested font can't be resolved, at whatever size and style it was itself loaded with.

FontResolver

Gets or sets an instance of the IFallbackFontResolver to get fonts that should be used as fallback ones if characters are not supported.

public IFallbackFontResolver FontResolver { get; set; }

Property Value

IFallbackFontResolver

Remarks

If any font can't find a character to write, it asks FontResolver to provide an instance of the font that can write it.

Methods

Clear()

Clears all font caches.

public void Clear()

DisableSystemFonts()

Stops looking up fonts installed on the system by family name: a family that isn't imported resolves to FallbackFont, or draws nothing.

public void DisableSystemFonts()

Remarks

Turn system fonts off when the game ships all its fonts, so text looks the same on every machine and a missing import shows up in development (as a logged warning) instead of being covered by an installed font. Then set DefaultFontFamily to an imported family: the engine default, Segoe UI, is a system font.

System fonts already found stay loaded. On a configuration builder, use UseSystemFonts(IFontConfigurationBuilder, bool) with false.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

EnableSystemFonts()

Enables support for importing system installed fonts by their family names and styles.

public void EnableSystemFonts()

Remarks

Cheap: the system fonts folder is indexed on the first font lookup that misses, once (typically 200-400 ms on Windows). A game whose fonts are all imported never pays for it.

On Windows this is the Windows fonts folder. On Linux and macOS, .NET maps it to the user's font folder (~/.fonts, ~/Library/Fonts), so ship fonts with the game and import them there instead.

GetOrLoad(FontInfo)

Gets or loads a font with the specified information.

public IFont? GetOrLoad(FontInfo info)

Parameters

info FontInfo

Information about the font to get or load.

Returns

IFont

The font instance.

ImportFont<TContext>(TContext, string)

Imports a font from a file.

public IFont ImportFont<TContext>(TContext assetContext, string filePath) where TContext : IAssetContext

Parameters

assetContext TContext

The asset context to load from.

filePath string

Path to the font file.

Returns

IFont

An instance of the IFont loaded from the specified path.

Type Parameters

TContext

Type of the context used to load font assets.

ImportSystemFont(FontInfo)

Imports a new instance of the font with the specified family, style and size from the system fonts storage.

public IFont ImportSystemFont(FontInfo info)

Parameters

info FontInfo

Font info to get an instance of the IFont for.

Returns

IFont

An instance of the IFont with the specified family, size and style.