Class GorgonFontFactory

A factory used to create, read, and cache font data.

Inheritance

object

GorgonFontFactory

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Namespace: Gorgon.Graphics.Fonts

Assembly: Gorgon.Graphics.Fonts.dll

Syntax

public sealed class GorgonFontFactory : IDisposable

Remarks

This factory will create new bitmap fonts for applications to use when rendering text data. Fonts generated by the factory are cached for the lifetime of the factory and will be reused if font information (e.g. name, information, etc...) is the same.

Applications can also use this factory to load fonts from the file system, and have them cached as well.

The factory will also built a default font for quick use in applications.

Applications should only create a single instance of object for the lifetime of the application, any more than that may be wasteful.

Because this object can contain a large amount of data, and implements IDisposable, it is required for applications to call the Dispose() method when shutting down the factory.

Constructors

GorgonFontFactory(GorgonGraphics)

Initializes a new instance of the GorgonFontFactory class.

Declaration

public GorgonFontFactory(GorgonGraphics graphics)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface used to create the font data.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the graphics parameter is null.

Properties

DefaultFont

Property to return the default font.

Declaration

public GorgonFont DefaultFont { get; }

Property Value

Type	Description
GorgonFont

Remarks

This will return a default font used in applications for quick testing.

The font will be based on Segoe UI, have a size of 12 points, and will be bolded and antialiased.

Graphics

Property to return the graphics interface used to generate the fonts.

Declaration

public GorgonGraphics Graphics { get; }

Property Value

Type	Description
GorgonGraphics

Methods

Dispose()

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

Declaration

public void Dispose()

GetFont(IGorgonFontInfo)

Function to return or create a new GorgonFont.

Declaration

public GorgonFont GetFont(IGorgonFontInfo fontInfo)

Parameters

Type	Name	Description
IGorgonFontInfo	fontInfo	The information used to create the font.

Returns

Type	Description
GorgonFont	A new or existing GorgonFont.

Remarks

This method creates an object that contains a group of textures with font glyphs. These textures can be used by another application to display text (or symbols) on the screen. Kerning information (the proper spacing for a glyph), advances, etc... are all included for the glyphs with font.

The Name value on the fontInfo parameter is used in caching, and is user defined. It is not necessary to have it share the same name as the font family name in the fontInfo parameter, however it is best practice to indicate the font family name in the name for ease of use. By default, this parameter is set to the font family, height and unit of measure.

If a font with the same name was previously created by this factory, then that font will be returned if the fontInfo is the same as the cached version. If the font was not found by its name, then a new font will be created. Otherwise, if a cached font with the same name exists, but its IGorgonFontInfo is different from the fontInfo passed in, then an exception will be thrown.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the fontInfo parameter is null.
ArgumentException	Thrown when the TextureWidth or TextureHeight parameters exceed the MaxTextureWidth or MaxTextureHeight available for the current FeatureSet. -or- Thrown if the Characters list does not contain the DefaultCharacter character. -or- A font with the same name was already created by the factory, but does not have the same parameters.

GetFontAsync(IGorgonFontInfo)

Function to asynchronously return or create a new GorgonFont.

Declaration

public Task<GorgonFont> GetFontAsync(IGorgonFontInfo fontInfo)

Parameters

Type	Name	Description
IGorgonFontInfo	fontInfo	The information used to create the font.

Returns

Type	Description
Task<GorgonFont>	A new or existing GorgonFont.

Remarks

This method creates an object that contains a group of textures with font glyphs. These textures can be used by another application to display text (or symbols) on the screen. Kerning information (the proper spacing for a glyph), advances, etc... are all included for the glyphs with font.

The Name value on the fontInfo parameter is used in caching, and is user defined. It is not necessary to have it share the same name as the font family name in the fontInfo parameter, however it is best practice to indicate the font family name in the name for ease of use. By default, this parameter is set to the font family, height and unit of measure.

If a font with the same name was previously created by this factory, then that font will be returned if the fontInfo is the same as the cached version. If the font was not found by its name, then a new font will be created. Otherwise, if a cached font with the same name exists, but its IGorgonFontInfo is different from the fontInfo passed in, then an exception will be thrown.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the fontInfo parameter is null.
ArgumentException	Thrown when the TextureWidth or TextureHeight parameters exceed the MaxTextureWidth or MaxTextureHeight available for the current FeatureSet. -or- Thrown if the Characters list does not contain the DefaultCharacter character. -or- A font with the same name was already created by the factory, but does not have the same parameters.

HasFont(IGorgonFontInfo)

Function to determine if the font cache contains a font with the specified name, and the specified font information.

Declaration

public bool HasFont(IGorgonFontInfo fontInfo)

Parameters

Type	Name	Description
IGorgonFontInfo	fontInfo	The information about the font to find.

Returns

Type	Description
bool	true if found, false if not.

Remarks

The Name value on the fontInfo parameter is used in caching, and is user defined. It is not necessary to have it share the same name as the font family name in the fontInfo parameter, however it is best practice to indicate the font family name in the name for ease of use. By default, this parameter is set to the font family, height and unit of measure.

If a font with the same name was previously created by this factory, then this method will return true if the fontInfo is the same as the cached version. If no font with the same name or the fontInfo is different, then this method will return false.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the fontInfo parameter is null.

InvalidateCache()

Function to invalidate the cached fonts for this factory.

Declaration

public void InvalidateCache()

LoadTrueTypeFontFamily(Stream, int?)

Function to load a try type font into the font factory for rasterization.

Declaration

public FontFamily LoadTrueTypeFontFamily(Stream stream, int? size = null)

Parameters

Type	Name	Description
Stream	stream	The stream containing the true type font data.
int?	size	[Optional] The size of the font data, in bytes.

Returns

Type	Description
FontFamily	The font family for the loaded font.

Remarks

Use this to load a true type from the disk into the factory. The factory will use this to build a GorgonFont based on your font.

If the size parameter is not specified, then the entire length of the stream will be used.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.
ArgumentOutOfRangeException	Thrown when the size parameter is less than 1.
IOException	Thrown when the stream is write only.
EndOfStreamException	Thrown when no more data can be read from the stream.

LoadTrueTypeFontFamily(string)

Function to load a try type font into the font factory for rasterization.

Declaration

public FontFamily LoadTrueTypeFontFamily(string path)

Parameters

Type	Name	Description
string	path	The path to the font on the file system.

Returns

Type	Description
FontFamily	The font family for loaded font.

Remarks

Use this to load a true type from the disk into the factory. The factory will use this to build a GorgonFont based on your font.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the path parameter is null.
ArgumentEmptyException	Thrown when the path parameter is empty.

Implements

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)