Class GorgonFont

A font used to render text data.

Inheritance

object

GorgonNamedObject

GorgonFont

Implements

IGorgonFontInfo

IGorgonNamedObject

IDisposable

Inherited Members

GorgonNamedObject.GetHashCode()

GorgonNamedObject.ToString()

GorgonNamedObject.Name

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetType()

Namespace: Gorgon.Graphics.Fonts

Assembly: Gorgon.Graphics.Fonts.dll

Syntax

public sealed class GorgonFont : GorgonNamedObject, IGorgonFontInfo, IGorgonNamedObject, IDisposable

Remarks

This type contains all the necessary information used to render glyphs to represent characters on the screen. Complete kerning information is provided as well (if available on the original font object), and can be customized by the user.

The font also contains a customizable glyph collection that users can modify to provide custom glyph to character mapping (e.g. a special texture used for a single character).

Properties

AntiAliasingMode

Property to return the anti-aliasing mode for the font.

Declaration

public FontAntiAliasMode AntiAliasingMode { get; }

Property Value

Type	Description
FontAntiAliasMode

Remarks

This defines the smoothness of font pixel edges.

important

Gorgon does not support clear type at this time.

The default value is AntiAlias.

Ascent

Property to return the ascent for the font, in pixels.

Declaration

public float Ascent { get; }

Property Value

Type	Description
float

Brush

Property to return a GorgonGlyphBrush to use for special effects on the glyphs for the font.

Declaration

public GorgonGlyphBrush Brush { get; }

Property Value

Type	Description
GorgonGlyphBrush

Remarks

This value can be used to define how a glyph is rendered when the GorgonFont is generated. Applications can use brushes for gradients, textures, etc... to render the glyphs to give them a unique look.

This default value is null.

Characters

Property to return the list of available characters to use as glyphs within the font.

Declaration

public IEnumerable<char> Characters { get; }

Property Value

Type	Description
IEnumerable<char>

Remarks

This will define what characters the font can display when rendering. Any character not defined in this property will use the default character (typically a space).

The default encompasses characters from ASCII character code 32 to 255.

DefaultCharacter

Property to return a default character to use in place of a character that cannot be found in the font.

Declaration

public char DefaultCharacter { get; }

Property Value

Type	Description
char

Remarks

If some characters are unprintable (e.g. have no width/height), or they were not defined in the Characters property. This character will be substituted in those cases.

The default value is a space (' ').

Descent

Property to return the descent for the font, in pixels.

Declaration

public float Descent { get; }

Property Value

Type	Description
float

FontFamilyName

Property to return the font family name to generate the font from.

Declaration

public string FontFamilyName { get; }

Property Value

Type	Description
string

FontHeight

Property to return the font height, in pixels.

Declaration

public float FontHeight { get; }

Property Value

Type	Description
float

Remarks

This is not the same as line height, the line height is a combination of ascent, descent and internal/external leading space.

FontHeightMode

Property to return whether the font height is in pixels or in points.

Declaration

public FontHeightMode FontHeightMode { get; }

Property Value

Type	Description
FontHeightMode

Remarks

When the font uses points for its height, the user must be aware of DPI scaling issues that may arise.

This will affect the Size value in that it will alter the meaning of the units.

The default value is Pixels.

FontStyle

Property to return the style for the font.

Declaration

public FontStyle FontStyle { get; }

Property Value

Type	Description
FontStyle

Remarks

The default value is Regular.

Glyphs

Property to return the glyphs for this font.

Declaration

public GorgonGlyphCollection Glyphs { get; }

Property Value

Type	Description
GorgonGlyphCollection

Remarks

A glyph is a graphical representation of a character. For Gorgon, this means a glyph for a specific character will point to a region of texels on a texture.

Note that the glyph for a character is not required to represent the exact character (for example, the character "A" could map to the "V" character on the texture). This will allow mapping of symbols to a character representation.

Graphics

Property to return the graphics interface used to create this font.

Declaration

public GorgonGraphics Graphics { get; }

Property Value

Type	Description
GorgonGraphics

HasOutline

Property to return whether there is an outline for this font.

Declaration

public bool HasOutline { get; }

Property Value

Type	Description
bool

KerningPairs

Property to return the list of kerning pairs associated with the font.

Declaration

public IDictionary<GorgonKerningPair, int> KerningPairs { get; }

Property Value

Type	Description
IDictionary<GorgonKerningPair, int>

Remarks

Applications may use this list to define custom kerning information when rendering.

LineHeight

Property to return the line height, in pixels, for the font.

Declaration

public float LineHeight { get; }

Property Value

Type	Description
float

OutlineColor1

Property to return the starting color of the outline.

Declaration

public GorgonColor OutlineColor1 { get; }

Property Value

Type	Description
GorgonColor

Remarks

This defines the starting color for an outline around a font glyph. This can be used to give a gradient effect to the outline and allow for things like glowing effects and such.

If the alpha channel is set to 0.0f and the OutlineColor2 alpha channel is set to 0.0f, then outlining will be disabled since it will be invisible. This will also be ignored if the OutlineSize value is not greater than 0.

The default value is Transparent (A=1.0f, R=0.0f, G=0.0f, B=0.0f).

OutlineColor2

Property to return the ending color of the outline.

Declaration

public GorgonColor OutlineColor2 { get; }

Property Value

Type	Description
GorgonColor

Remarks

This defines the ending color for an outline around a font glyph. This can be used to give a gradient effect to the outline and allow for things like glowing effects and such.

If the alpha channel is set to 0.0f and the OutlineColor1 alpha channel is set to 0.0f, then outlining will be disabled since it will be invisible. This will also be ignored if the OutlineSize value is not greater than 3.

The default value is Transparent (A=1.0f, R=0.0f, G=0.0f, B=0.0f).

OutlineSize

Property to return the size of an outline.

Declaration

public int OutlineSize { get; }

Property Value

Type	Description
int

Remarks

This defines the thickness of an outline (in pixels) for each glyph in the font. A value greater than 0 will draw an outline, 0 or less will turn outlining off.

The default value is 0.

PackingSpacing

Property to return the spacing (in pixels) used between font glyphs on the backing texture.

Declaration

public int PackingSpacing { get; }

Property Value

Type	Description
int

Remarks

This defines how much space to put between glyphs. Higher values will waste more space (and thus lead to more textures being created), but may resolve rendering issues.

The valid values are between 0 and 8.

The default value is 1 pixel.

Size

Property to return the font size.

Declaration

public float Size { get; }

Property Value

Type	Description
float

Remarks

This sets the height of the font.

This is affected by the FontHeightMode. If the FontHeightMode is set to Points, then this unit is the height size height for the font. Otherwise, this represents the font height in Pixels.

TextureHeight

Property to return the height of the texture(s) used as the backing store for the bitmap font data.

Declaration

public int TextureHeight { get; }

Property Value

Type	Description
int

Remarks

This value will control the width of the textures created. It can be used to decrease or increase the number of textures used for a font. This is important because if the number of requested glyphs cannot fit onto a single texture, a new texture will be created to store the remaining glyphs. Keeping as few textures as possible for a font is beneficial for performance.

Font textures cannot be smaller than 256x256 and the maximum size is dependent upon FeatureSet for the IGorgonVideoAdapterInfo.

The default height is 256.

TextureWidth

Property to return the width of the texture(s) used as the backing store for the bitmap font data.

Declaration

public int TextureWidth { get; }

Property Value

Type	Description
int

Remarks

This value will control the width of the textures created. It can be used to decrease or increase the number of textures used for a font. This is important because if the number of requested glyphs cannot fit onto a single texture, a new texture will be created to store the remaining glyphs. Keeping as few textures as possible for a font is beneficial for performance.

Font textures cannot be smaller than 256x256 and the maximum size is dependent upon FeatureSet for the IGorgonVideoAdapterInfo.

The default width is 256.

UseKerningPairs

Property to return whether to include kerning pair information in the font.

Declaration

public bool UseKerningPairs { get; }

Property Value

Type	Description
bool

Remarks

Kerning pairs are used to define spacing between 2 characters in a font. When this value is set to true the kerning information of the font is retrieved and added to the GorgonFont for use when rendering. This can be used to resolve rendering issues regarding horizontal font spacing.

note

Some fonts do not employ the use of kerning pairs, and consequently, this setting will be ignored if that is the case.

The default value is true.

UsePremultipliedTextures

Property to return whether premultiplied textures are used when generating the glyphs for the font.

Declaration

public bool UsePremultipliedTextures { get; }

Property Value

Type	Description
bool

Remarks

This defines whether the textures used to store the glyphs of the font will use premultiplied alpha. Premultiplied alpha is used to give a more accurate representation of blending between colors, and is accomplished by multiplying the RGB values by the Alpha component of a pixel.

If this value is true, then applications should use the Premultiplied blending state when rendering text.

The default value is false.

Methods

Dispose()

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

Declaration

public void Dispose()

GetDefaultGlyph()

Function to retrieve the glyph used for the default character assigned to the font DefaultCharacter.

Declaration

public GorgonGlyph GetDefaultGlyph()

Returns

Type	Description
GorgonGlyph	The GorgonGlyph representing the default character.

Remarks

The default character is assigned to the DefaultCharacter property of the IGorgonFontInfo type passed to the constructor of the font.

Exceptions

Type	Condition
KeyNotFoundException	Thrown when no glyph could be located that matches the default character.

See Also

IGorgonFontInfo

TryGetDefaultGlyph(out GorgonGlyph)

Function to retrieve the glyph used for the default character assigned to the font DefaultCharacter.

Declaration

public bool TryGetDefaultGlyph(out GorgonGlyph glyph)

Parameters

Type	Name	Description
GorgonGlyph	glyph	The default glyph, or null if not found.

Returns

Type	Description
bool	true if the glyph was found, or false if not.

Remarks

The default character is assigned to the DefaultCharacter property of the IGorgonFontInfo type passed to the constructor of the font.

See Also

IGorgonFontInfo

GorgonGlyph

Implements

IGorgonFontInfo

IGorgonNamedObject

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)