Table of Contents

Class FontFace1

Namespace
SharpDX.DirectWrite
Assembly
SharpDX.Direct2D1.dll
[Guid("a71efdb4-9fdb-4838-ad90-cfc3be8c3daf")]
public class FontFace1 : FontFace
Inheritance
FontFace1
Derived
Inherited Members

Constructors

FontFace1(nint) 

public FontFace1(nint nativePtr)

Parameters

nativePtr nint

Properties

CaretMetrics

Gets caret metrics for the font in design units.

public CaretMetrics CaretMetrics { get; }

Property Value

CaretMetrics

Remarks

Caret metrics are used by text editors for drawing the correct caret placement and slant.

IsMonospacedFont

Determines whether the font of a text range is monospaced, that is, the font characters are the same fixed-pitch width.

public RawBool IsMonospacedFont { get; }

Property Value

RawBool

Metrics

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. 

public FontMetrics1 Metrics { get; }

Property Value

FontMetrics1

Methods

GetDesignGlyphAdvances(int, short[], int[], RawBool)

Retrieves the advances in design units for a sequences of glyphs.

public void GetDesignGlyphAdvances(int glyphCount, short[] glyphIndices, int[] glyphAdvances, RawBool isSideways)

Parameters

glyphCount int

The number of glyphs to retrieve advances for.

glyphIndices short[]

An array of glyph id's to retrieve advances for.

glyphAdvances int[]

The returned advances in font design units for each glyph.

isSideways RawBool

Retrieve the glyph's vertical advance height rather than horizontal advance widths.

Remarks

This is equivalent to calling GetGlyphMetrics and using only the advance width and height.

GetGdiCompatibleGlyphAdvances(float, float, RawMatrix3x2?, RawBool, RawBool, int, short[], int[])

Returns the pixel-aligned advances for a sequences of glyphs.

public void GetGdiCompatibleGlyphAdvances(float emSize, float pixelsPerDip, RawMatrix3x2? transform, RawBool useGdiNatural, RawBool isSideways, int glyphCount, short[] glyphIndices, int[] glyphAdvances)

Parameters

emSize float

Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.

pixelsPerDip float

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.

transform RawMatrix3x2?

Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.

useGdiNatural RawBool

When SharpDX.Result.False, the metrics are the same as GDI aliased text (DWRITE_MEASURING_MODE_GDI_CLASSIC). When TRUE, the metrics are the same as those measured by GDI using a font using CLEARTYPE_NATURAL_QUALITY (DWRITE_MEASURING_MODE_GDI_NATURAL).

isSideways RawBool

Retrieve the glyph's vertical advances rather than horizontal advances.

glyphCount int

Total glyphs to retrieve adjustments for.

glyphIndices short[]

An array of glyph id's to retrieve advances.

glyphAdvances int[]

The returned advances in font design units for each glyph.

Remarks

This is equivalent to calling GetGdiCompatibleGlyphMetrics and using only the advance width and height.

Like GetGdiCompatibleGlyphMetrics, these are in design units, meaning they must be scaled down by DWRITE_FONT_METRICS::designUnitsPerEm.

GetGdiCompatibleMetrics(float, float, RawMatrix3x2?, out FontMetrics1)

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

public void GetGdiCompatibleMetrics(float emSize, float pixelsPerDip, RawMatrix3x2? transform, out FontMetrics1 fontMetrics)

Parameters

emSize float

The logical size of the font in DIP units.

pixelsPerDip float

The number of physical pixels per DIP.

transform RawMatrix3x2?

An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.

fontMetrics FontMetrics1

A reference to a FontMetrics1 structure to fill in. The metrics returned by this function are in font design units.

GetKerningPairAdjustments(int, short[], int[])

Retrieves the kerning pair adjustments from the font's kern table.

public void GetKerningPairAdjustments(int glyphCount, short[] glyphIndices, int[] glyphAdvanceAdjustments)

Parameters

glyphCount int

Number of glyphs to retrieve adjustments for.

glyphIndices short[]

An array of glyph id's to retrieve adjustments for.

glyphAdvanceAdjustments int[]

The advances, returned in font design units, for each glyph. The last glyph adjustment is zero.

Remarks

GetKerningPairAdjustments isn't a direct replacement for GDI's character based GetKerningPairs, but it serves the same role, without the client needing to cache them locally. GetKerningPairAdjustments also uses glyph id's directly rather than UCS-2 characters (how the kern table actually stores them), which avoids glyph collapse and ambiguity, such as the dash and hyphen, or space and non-breaking space.

Newer fonts may have only GPOS kerning instead of the legacy pair-table kerning. Such fonts, like Gabriola, will only return 0's for adjustments. GetKerningPairAdjustments doesn't virtualize and flatten these GPOS entries into kerning pairs.

You can realize a performance benefit by calling IDWriteFontFace1::HasKerningPairs to determine whether you need to call GetKerningPairAdjustments. If you previously called IDWriteFontFace1::HasKerningPairs and it returned SharpDX.Result.False, you can avoid calling GetKerningPairAdjustments because the font has no kerning pair-table entries. That is, in this situation, a call to GetKerningPairAdjustments would be a no-op.

GetRecommendedRenderingMode(float, float, float, RawMatrix3x2?, RawBool, OutlineThreshold, MeasuringMode, out RenderingMode)

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

public void GetRecommendedRenderingMode(float fontEmSize, float dpiX, float dpiY, RawMatrix3x2? transform, RawBool isSideways, OutlineThreshold outlineThreshold, MeasuringMode measuringMode, out RenderingMode renderingMode)

Parameters

fontEmSize float

The logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.

dpiX float

The number of physical pixels per DIP in a horizontal position. 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.

dpiY float

The number of physical pixels per DIP in a vertical position. 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.

transform RawMatrix3x2?

Specifies the world transform.

isSideways RawBool

Whether the glyphs in the run are sideways or not.

outlineThreshold OutlineThreshold

A OutlineThreshold-typed value that specifies the quality of the graphics system's outline rendering, affects the size threshold above which outline rendering is used.

measuringMode MeasuringMode

The measuring method that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for different measuring methods, for example:

  • 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
renderingMode RenderingMode

When this method returns, contains a value that indicates the recommended rendering mode to use.

Remarks

This method should be used to determine the actual rendering mode in cases where the rendering mode of the rendering params object is DWRITE_RENDERING_MODE_DEFAULT.

GetUnicodeRanges(int, UnicodeRange[], out int)

Retrieves a list of character ranges supported by a font.

public void GetUnicodeRanges(int maxRangeCount, UnicodeRange[] unicodeRanges, out int actualRangeCount)

Parameters

maxRangeCount int

Maximum number of character ranges passed in from the client.

unicodeRanges UnicodeRange[]

An array of UnicodeRange structures that are filled with the character ranges.

actualRangeCount int

A reference to the actual number of character ranges, regardless of the maximum count.

Remarks

A list of character ranges supported by the font is useful for scenarios like character picking, glyph display, and efficient font selection lookup. This is similar to GDI's GetFontUnicodeRanges, except that it returns the full Unicode range, not just 16-bit UCS-2.

These ranges are from the cmap, not the OS/2::ulCodePageRange1.

If this method is unavailable, you can use the IDWriteFontFace::GetGlyphIndices method to check for missing glyphs. The method returns the 0 index for glyphs that aren't present in the font.

The IDWriteFont::HasCharacter method is often simpler in cases where you need to check a single character or a series of single characters in succession, such as in font fallback.

GetVerticalGlyphVariants(int, short[], short[])

Retrieves the vertical forms of the nominal glyphs retrieved from GetGlyphIndices.

public void GetVerticalGlyphVariants(int glyphCount, short[] nominalGlyphIndices, short[] verticalGlyphIndices)

Parameters

glyphCount int

The number of glyphs to retrieve.

nominalGlyphIndices short[]

Original glyph indices from cmap.

verticalGlyphIndices short[]

The vertical form of glyph indices.

Remarks

The retrieval uses the font's 'vert' table. This is used in CJK vertical layout so the correct characters are shown.

Call GetGlyphIndices to get the nominal glyph indices, followed by calling this to remap the to the substituted forms, when the run is sideways, and the font has vertical glyph variants. See HasVerticalGlyphVariants for more info.

HasKerningPairs()

Determines whether the font supports pair-kerning.

public RawBool HasKerningPairs()

Returns

RawBool

Returns TRUE if the font supports kerning pairs, otherwise SharpDX.Result.False.

Remarks

If the font doesn't support pair table kerning, you don't need to call IDWriteFontFace1::GetKerningPairAdjustments because it would retrieve all zeroes.

HasVerticalGlyphVariants()

Determines whether the font has any vertical glyph variants.

public RawBool HasVerticalGlyphVariants()

Returns

RawBool

Returns TRUE if the font contains vertical glyph variants, otherwise SharpDX.Result.False.

Remarks

For OpenType fonts, HasVerticalGlyphVariants returns TRUE if the font contains a "vert" feature.

IDWriteFontFace1::GetVerticalGlyphVariants retrieves the vertical forms of the nominal glyphs that are retrieved from IDWriteFontFace::GetGlyphIndices.

Operators

explicit operator FontFace1(nint) 

public static explicit operator FontFace1(nint nativePtr)

Parameters

nativePtr nint

Returns

FontFace1