IDWriteFontSet4::GetMatchingFonts method (dwrite_3.h)

Generates a matching font set based on the requested inputs, ordered so that nearer matches are earlier.

Syntax

HRESULT GetMatchingFonts(
  WCHAR const                  *familyName,
  DWRITE_FONT_AXIS_VALUE const *fontAxisValues,
  UINT32                       fontAxisValueCount,
  DWRITE_FONT_SIMULATIONS      allowedSimulations,
  IDWriteFontSet4              **matchingFonts
);

Parameters

familyName

Type: _In_z_ WCHAR const*

Font family name. This can be: a typographic family name, weight/stretch/style family name, GDI (RBIZ) family name, or full name.

fontAxisValues

Type: _In_reads_(fontAxisValueCount) DWRITE_FONT_AXIS_VALUE const*

Array of font axis values.

fontAxisValueCount

Type: UINT32

Number of font axis values.

allowedSimulations

Type: DWRITE_FONT_SIMULATIONS

Specifies which simulations (that is, algorithmic emboldening and/or slant) may be applied to matching fonts to better match the specified axis values. If the argument is DWRITE_FONT_SIMULATIONS_NONE (0), then no simulations are applied.

matchingFonts

Type: _COM_Outptr_ IDWriteFontSet4**

Receives a pointer to a newly-created font set, which contains a prioritized list of fonts that match the specified inputs.

Return value

Type: HRESULT

If the function succeeds, then it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This can yield distinct items that were not in the original font set, including items with simulation flags (if they would be a closer match to the request) and instances that were not named by the font author. Items from the same font resources are collapsed into one: the closest possible match.

Requirements