Table of Contents

Class FontFace

Namespace
SharpDX.DirectWrite
Assembly
SharpDX.Direct2D1.dll
[Guid("5f49804d-7024-4d43-bfa9-d25984f53849")]
public class FontFace : ComObject
Inheritance
FontFace
Derived

Constructors

FontFace(Factory, FontFaceType, FontFile[], int, FontSimulations)

Creates an object that represents a font face.

public FontFace(Factory factory, FontFaceType fontFaceType, FontFile[] fontFiles, int faceIndex, FontSimulations fontFaceSimulationFlags)

Parameters

factory Factory

A reference to a DirectWrite factory Factory

fontFaceType FontFaceType

A value that indicates the type of file format of the font face.

fontFiles FontFile[]

A font file object representing the font face. BecauseFontFace maintains its own references to the input font file objects, you may release them after this call.

faceIndex int

The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.

fontFaceSimulationFlags FontSimulations

A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.

FontFace(Font)

Creates a font face object for the font.

public FontFace(Font font)

Parameters

font Font

the Font to create the FontFace from.

FontFace(nint) 

public FontFace(nint nativePtr)

Parameters

nativePtr nint

Properties

FaceType

Obtains the file format type of a font face. 

public FontFaceType FaceType { get; }

Property Value

FontFaceType

GlyphCount

Obtains the number of glyphs in the font face. 

public short GlyphCount { get; }

Property Value

short

Index

Obtains the index of a font face in the context of its font files. 

public int Index { get; }

Property Value

int

IsSymbolFont

Determines whether the font is a symbol font. 

public RawBool IsSymbolFont { 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 FontMetrics Metrics { get; }

Property Value

FontMetrics

Simulations

Obtains the algorithmic style simulation flags of a font face. 

public FontSimulations Simulations { get; }

Property Value

FontSimulations

Methods

GetDesignGlyphMetrics(short[], bool)

Obtains ideal (resolution-independent) glyph metrics in font design units.

public GlyphMetrics[] GetDesignGlyphMetrics(short[] glyphIndices, bool isSideways)

Parameters

glyphIndices short[]

An array of glyph indices for which to compute metrics. The array must contain at least as many elements as specified by glyphCount.

isSideways bool

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

GlyphMetrics[]

an array of GlyphMetrics structures.

Remarks

Design glyph metrics are used for glyph positioning.

GetFiles()

Obtains the font files representing a font face.

public FontFile[] GetFiles()

Returns

FontFile[]

An array that stores references to font files representing the font face. This parameter can be NULL if the user wants only the number of files representing the font face. This API increments reference count of the font file references returned according to COM conventions, and the client should release them when finished.

Remarks

The IDWriteFontFace::GetFiles method should be called twice. The first time you call GetFilesfontFiles should be NULL. When the method returns, numberOfFiles receives the number of font files that represent the font face. Then, call the method a second time, passing the numberOfFiles value that was output the first call, and a non-null buffer of the correct size to store the FontFile references.

GetGdiCompatibleGlyphMetrics(float, float, RawMatrix3x2?, bool, short[], bool)

Obtains glyph metrics in font design units with the return values compatible with what GDI would produce.

public GlyphMetrics[] GetGdiCompatibleGlyphMetrics(float fontSize, float pixelsPerDip, RawMatrix3x2? transform, bool useGdiNatural, short[] glyphIndices, bool isSideways)

Parameters

fontSize 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.

useGdiNatural bool

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.

glyphIndices short[]

An array of glyph indices for which to compute the metrics.

isSideways bool

A BOOL value that 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

GlyphMetrics[]

An array of GlyphMetrics structures filled by this function. The metrics are in font design units.

GetGdiCompatibleMetrics(float, float, RawMatrix3x2?)

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 FontMetrics GetGdiCompatibleMetrics(float emSize, float pixelsPerDip, RawMatrix3x2? transform)

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.

Returns

FontMetrics

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

GetGlyphIndices(int[])

Returns the nominal mapping of UCS4 Unicode code points to glyph indices as defined by the font 'CMAP' table.

public short[] GetGlyphIndices(int[] codePoints)

Parameters

codePoints int[]

An array of USC4 code points from which to obtain nominal glyph indices. The array must be allocated and be able to contain the number of elements specified by codePointCount.

Returns

short[]

a reference to an array of nominal glyph indices filled by this function.

Remarks

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 variant selectors provide for alternate mappings for character to glyph. This call will always return the default variant.

GetGlyphRunOutline(float, short[], float[], GlyphOffset[], int, RawBool, RawBool, SimplifiedGeometrySink)

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

public void GetGlyphRunOutline(float emSize, short[] glyphIndices, float[] glyphAdvances, GlyphOffset[] glyphOffsets, int glyphCount, RawBool isSideways, RawBool isRightToLeft, SimplifiedGeometrySink geometrySink)

Parameters

emSize float

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

glyphIndices short[]

An array of glyph indices. The glyphs are in logical order and the advance direction depends on the isRightToLeft parameter. The array must be allocated and be able to contain the number of elements specified by glyphCount.

glyphAdvances float[]

An optional array of glyph advances in DIPs. The advance of a glyph is the amount to advance the position (in the direction of the baseline) after drawing the glyph. glyphAdvances contains the number of elements specified by glyphCount.

glyphOffsets GlyphOffset[]

An optional array of glyph offsets, each of which specifies the offset along the baseline and offset perpendicular to the baseline of a glyph relative to the current pen position. glyphOffsets contains the number of elements specified by glyphCount.

glyphCount int

The number of glyphs in the run.

isSideways RawBool

If TRUE, the ascender of the glyph runs alongside the baseline. If SharpDX.Result.False, the glyph ascender runs perpendicular to the baseline. For example, an English alphabet on a vertical baseline would have isSideways set to SharpDX.Result.False.

A client can render a vertical run by setting isSideways to TRUE and rotating the resulting geometry 90 degrees to the right using a transform. The isSideways and isRightToLeft parameters cannot both be true.

isRightToLeft RawBool

The visual order of the glyphs. If this parameter is SharpDX.Result.False, then glyph advances are from left to right. If TRUE, the advance direction is right to left. By default, the advance direction is left to right.

geometrySink SimplifiedGeometrySink

A reference to the interface that is called back to perform outline drawing operations.

GetRecommendedRenderingMode(float, float, MeasuringMode, RenderingParams)

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

public RenderingMode GetRecommendedRenderingMode(float emSize, float pixelsPerDip, MeasuringMode measuringMode, RenderingParams renderingParams)

Parameters

emSize float

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

pixelsPerDip float

The 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.

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
renderingParams RenderingParams

A reference to an object that contains rendering settings such as gamma level, enhanced contrast, and ClearType level. This parameter is necessary in case the rendering parameters object overrides the rendering mode.

Returns

RenderingMode

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

ReleaseFontTable(nint)

Releases the table obtained earlier from TryGetFontTable. 

public void ReleaseFontTable(nint tableContext)

Parameters

tableContext nint

No documentation.

TryGetFontTable(int, out DataPointer, out nint)

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

public bool TryGetFontTable(int openTypeTableTag, out DataPointer tableData, out nint tableContext)

Parameters

openTypeTableTag int

The four-character tag of a OpenType font table to find. Use the DWRITE_MAKE_OPENTYPE_TAG macro to create it as an UINT32. Unlike GDI, it does not support the special TTCF and null tags to access the whole font.

tableData DataPointer

When this method returns, contains the address of a reference to the base of the table in memory. The reference is valid only as long as the font face used to get the font table still exists; (not any other font face, even if it actually refers to the same physical font).

tableContext nint

When this method returns, the address of a reference to the opaque context, which must be freed by calling {{ReleaseFontTable}}. The context actually comes from the lower-level FontFileStream, which may be implemented by the application or DWrite itself. It is possible for a NULL tableContext to be returned, especially if the implementation performs direct memory mapping on 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 because each returned context can be different, you must release each context separately.

Returns

bool

TRUE if the font table exists; otherwise, FALSE.

Remarks

The context for the same tag may be different for each call, so each one must be held and released separately.

Operators

explicit operator FontFace(nint) 

public static explicit operator FontFace(nint nativePtr)

Parameters

nativePtr nint

Returns

FontFace