Class DWriteFontFace

The interface that represents an absolute reference to a font face. It contains font face type, appropriate file references and face identification data. Various font data such as metrics, names and glyph outlines is obtained from IDWriteFontFace.

Inheritance

object

DWriteFontFace

Implements

IDisposable

IDWriteReleasable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: JeremyAnsel.DirectX.DWrite

Assembly: JeremyAnsel.DirectX.DWrite.dll

Syntax

public sealed class DWriteFontFace : IDisposable, IDWriteReleasable

Properties

FaceType

Gets the file format type of a font face.

Declaration

public DWriteFontFaceType FaceType { get; }

Property Value

Type	Description
DWriteFontFaceType

GlyphCount

Gets the number of glyphs in the font face.

Declaration

public ushort GlyphCount { get; }

Property Value

Type	Description
ushort

Handle

Gets an handle representing the DWrite object interface.

Declaration

public object Handle { get; }

Property Value

Type	Description
object

Index

Gets the zero-based index of the font face in its font file or files. If the font files contain a single face, the return value is zero.

Declaration

public uint Index { get; }

Property Value

Type	Description
uint

IsSymbolFont

Gets a value indicating whether the font is a symbol font.

Declaration

public bool IsSymbolFont { get; }

Property Value

Type	Description
bool

Simulations

Gets the algorithmic style simulation flags of a font face.

Declaration

public DWriteFontSimulations Simulations { get; }

Property Value

Type	Description
DWriteFontSimulations

Methods

Dispose()

Immediately releases the unmanaged resources used by the DWrite object.

Declaration

public void Dispose()

GetDesignGlyphMetrics(ushort[], bool)

Obtains ideal glyph metrics in font design units. Design glyphs metrics are used for glyph positioning.

Declaration

public DWriteGlyphMetrics[] GetDesignGlyphMetrics(ushort[] glyphIndices, bool isSideways)

Parameters

Type	Name	Description
ushort[]	glyphIndices	An array of glyph indices to compute the metrics for.
bool	isSideways	Indicates whether the font is being used in a sideways run. This can affect the glyph metrics if the font has oblique simulation because sideways oblique simulation differs from non-sideways oblique simulation.

Returns

Type	Description
DWriteGlyphMetrics[]	Array of DWriteGlyphMetrics structures filled by this function.

Remarks

The metrics returned by this function are in font design units.

GetFiles()

Obtains the font files representing a font face.

Declaration

public DWriteFontFile[] GetFiles()

Returns

Type	Description
DWriteFontFile[]	DWriteFontFile

GetGdiCompatibleGlyphMetrics(float, float, DWriteMatrix?, bool, ushort[], bool)

Obtains glyph metrics in font design units with the return values compatible with what GDI would produce. Glyphs metrics are used for positioning of individual glyphs.

Declaration

public DWriteGlyphMetrics[] GetGdiCompatibleGlyphMetrics(float size, float pixelsPerDip, DWriteMatrix? transform, bool useGdiNatural, ushort[] glyphIndices, bool isSideways)

Parameters

Type	Name	Description
float	size	Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
float	pixelsPerDip	Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
DWriteMatrix?	transform	Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
bool	useGdiNatural	When set to FALSE, the metrics are the same as the metrics of GDI aliased text. When set to TRUE, the metrics are the same as the metrics of text measured by GDI using a font created with CLEARTYPE_NATURAL_QUALITY.
ushort[]	glyphIndices	An array of glyph indices to compute the metrics for.
bool	isSideways	Indicates whether the font is being used in a sideways run. This can affect the glyph metrics if the font has oblique simulation because sideways oblique simulation differs from non-sideways oblique simulation.

Returns

Type	Description
DWriteGlyphMetrics[]	Array of DWRITE_GLYPH_METRICS structures filled by this function.

Remarks

If any of the input glyph indices are outside of the valid glyph index range for the current font face, E_INVALIDARG will be returned. The metrics returned by this function are in font design units.

GetGdiCompatibleMetrics(float, float, DWriteMatrix?)

Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.

Declaration

public DWriteFontMetrics GetGdiCompatibleMetrics(float size, float pixelsPerDip, DWriteMatrix? transform)

Parameters

Type	Name	Description
float	size	Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
float	pixelsPerDip	Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
DWriteMatrix?	transform	Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.

Returns

Type	Description
DWriteFontMetrics	A DWriteFontMetrics structure.

Remarks

The metrics returned by this function are in font design units.

GetGlyphIndices(uint[])

Returns the nominal mapping of UTF-32 Unicode code points to glyph indices as defined by the font 'cmap' table. Note that this mapping is primarily provided for line layout engines built on top of the physical font API. Because of OpenType glyph substitution and line layout character substitution, the nominal conversion does not always correspond to how a Unicode string will map to glyph indices when rendering using a particular font face. Also, note that Unicode Variation Selectors provide for alternate mappings for character to glyph. This call will always return the default variant.

Declaration

public ushort[] GetGlyphIndices(uint[] codePoints)

Parameters

Type	Name	Description
uint[]	codePoints	An array of UTF-32 code points to obtain nominal glyph indices from.

Returns

Type	Description
ushort[]	Array of nominal glyph indices filled by this function.

GetGlyphRunOutline(float, ushort[], float[], DWriteGlyphOffset[], bool, bool, object)

Computes the outline of a run of glyphs by calling back to the outline sink interface.

Declaration

public void GetGlyphRunOutline(float size, ushort[] glyphIndices, float[] glyphAdvances, DWriteGlyphOffset[] glyphOffsets, bool isSideways, bool isRightToLeft, object geometrySink)

Parameters

Type	Name	Description
float	size	Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
ushort[]	glyphIndices	Array of glyph indices.
float[]	glyphAdvances	Optional array of glyph advances in DIPs.
DWriteGlyphOffset[]	glyphOffsets	Optional array of glyph offsets.
bool	isSideways	If true, specifies that glyphs are rotated 90 degrees to the left and vertical metrics are used. A client can render a vertical run by specifying isSideways = true and rotating the resulting geometry 90 degrees to the right using a transform.
bool	isRightToLeft	If true, specifies that the advance direction is right to left. By default, the advance direction is left to right.
object	geometrySink	Interface the function calls back to draw each element of the geometry.

GetMetrics()

Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.

Declaration

public DWriteFontMetrics GetMetrics()

Returns

Type	Description
DWriteFontMetrics	DWriteFontMetrics

Remarks

The metrics returned by this function are in font design units.

GetRecommendedRenderingMode(float, float, DWriteMeasuringMode, DWriteRenderingParams)

Determines the recommended rendering mode for the font given the specified size and rendering parameters.

Declaration

public DWriteRenderingMode GetRecommendedRenderingMode(float size, float pixelsPerDip, DWriteMeasuringMode measuringMode, DWriteRenderingParams renderingParams)

Parameters

Type	Name	Description
float	size	Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
float	pixelsPerDip	Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
DWriteMeasuringMode	measuringMode	Specifies measuring mode that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for given measuring modes, but best results are seen when the corresponding modes match: DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL for DWRITE_MEASURING_MODE_NATURAL DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC for DWRITE_MEASURING_MODE_GDI_CLASSIC DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL for DWRITE_MEASURING_MODE_GDI_NATURAL
DWriteRenderingParams	renderingParams	Rendering parameters object. This parameter is necessary in case the rendering parameters object overrides the rendering mode.

Returns

Type	Description
DWriteRenderingMode	DWriteRenderingMode

Release()

Releases the managed reference to the COM DWrite interface.

Declaration

public void Release()

ReleaseFontTable(nint)

Releases the table obtained earlier from TryGetFontTable.

Declaration

public void ReleaseFontTable(nint tableContext)

Parameters

Type	Name	Description
nint	tableContext	Opaque context from TryGetFontTable(uint, out nint, out uint, out nint).

ToBoolean()

Gets a boolean indicating if the handle is not null.

Declaration

public bool ToBoolean()

Returns

Type	Description
bool	A boolean

TryGetFontTable(uint, out nint, out uint, out nint)

Finds the specified OpenType font table if it exists and returns a pointer to it. The function accesses the underlying font data via the IDWriteFontFileStream interface implemented by the font file loader.

Declaration

public bool TryGetFontTable(uint openTypeTableTag, out nint tableData, out uint tableSize, out nint tableContext)

Parameters

Type	Name	Description
uint	openTypeTableTag	Four character tag of table to find. Use the DWRITE_MAKE_OPENTYPE_TAG() macro to create it. Unlike GDI, it does not support the special TTCF and null tags to access the whole font.
nint	tableData	Pointer to base of table in memory. The pointer is only valid so long as the FontFace used to get the font table still exists (not any other FontFace, even if it actually refers to the same physical font).
uint	tableSize	Byte size of table.
nint	tableContext	Opaque context which must be freed by calling ReleaseFontTable. The context actually comes from the lower level IDWriteFontFileStream, which may be implemented by the application or DWrite itself. It is possible for a NULL tableContext to be returned, especially if the implementation directly memory maps the whole file. Nevertheless, always release it later, and do not use it as a test for function success. The same table can be queried multiple times, but each returned context can be different, so release each separately.

Returns

Type	Description
bool	True if table exists.

Remarks

If a table can not be found, the function will not return an error, but the size will be 0, table NULL, and exists = FALSE. The context does not need to be freed if the table was not found. The context for the same tag may be different for each call, so each one must be held and released separately.

Operators

implicit operator bool(DWriteFontFace)

Gets a boolean indicating if the handle is not null.

Declaration

public static implicit operator bool(DWriteFontFace value)

Parameters

Type	Name	Description
DWriteFontFace	value	A DWrite object.

Returns

Type	Description
bool	A boolean

Implements

IDisposable

IDWriteReleasable