RetroArch
Classes | Macros | Enumerations | Variables
dwrite_3.h File Reference
#include <dwrite_2.h>
Include dependency graph for dwrite_3.h:

Go to the source code of this file.

Classes

struct  DWRITE_FONT_PROPERTY
 Font property used for filtering font sets and building a font set with explicit properties. More...
 
struct  DWRITE_LINE_METRICS1
 The interface that represents text rendering settings for glyph rasterization and filtering. More...
 
struct  DWRITE_LINE_SPACING
 The DWRITE_LINE_SPACING structure specifies the parameters used to specify how to manage space between lines. More...
 
struct  DWRITE_COLOR_GLYPH_RUN1
 Represents a color glyph run. The IDWriteFactory4::TranslateColorGlyphRun method returns an ordered collection of color glyph runs of varying types depending on what the font supports. More...
 
struct  DWRITE_GLYPH_IMAGE_DATA
 Data for a single glyph from GetGlyphImageData. More...
 
struct  DWRITE_FILE_FRAGMENT
 Enumerator for an ordered collection of color glyph runs. More...
 
struct  DWRITE_FONT_AXIS_VALUE
 Value for a font axis, used when querying and creating font instances. More...
 
struct  DWRITE_FONT_AXIS_RANGE
 Minimum and maximum range of a font axis. More...
 

Macros

#define DWRITE_E_REMOTEFONT   _HRESULT_TYPEDEF_(0x8898500DL)
 A font resource could not be accessed because it was remote. This can happen when calling CreateFontFace on a non-local font or trying to measure/draw glyphs that are not downloaded yet. More...
 
#define DWRITE_E_DOWNLOADCANCELLED   _HRESULT_TYPEDEF_(0x8898500EL)
 The download was canceled, which happens if the application calls IDWriteFontDownloadQueue::CancelDownload before they finish. More...
 
#define DWRITE_E_DOWNLOADFAILED   _HRESULT_TYPEDEF_(0x8898500FL)
 The download failed to complete because the remote resource is missing or the network is down. More...
 
#define DWRITE_E_TOOMANYDOWNLOADS   _HRESULT_TYPEDEF_(0x88985010L)
 A download request was not added or a download failed because there are too many active downloads. More...
 
#define DWRITE_MAKE_FONT_AXIS_TAG(a, b, c, d)   (static_cast<DWRITE_FONT_AXIS_TAG>(DWRITE_MAKE_OPENTYPE_TAG(a,b,c,d)))
 Creates an OpenType tag for a font axis. More...
 

Enumerations

enum  DWRITE_FONT_PROPERTY_ID {
  DWRITE_FONT_PROPERTY_ID_NONE, DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FAMILY_NAME, DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FAMILY_NAME, DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FACE_NAME,
  DWRITE_FONT_PROPERTY_ID_FULL_NAME, DWRITE_FONT_PROPERTY_ID_WIN32_FAMILY_NAME, DWRITE_FONT_PROPERTY_ID_POSTSCRIPT_NAME, DWRITE_FONT_PROPERTY_ID_DESIGN_SCRIPT_LANGUAGE_TAG,
  DWRITE_FONT_PROPERTY_ID_SUPPORTED_SCRIPT_LANGUAGE_TAG, DWRITE_FONT_PROPERTY_ID_SEMANTIC_TAG, DWRITE_FONT_PROPERTY_ID_WEIGHT, DWRITE_FONT_PROPERTY_ID_STRETCH,
  DWRITE_FONT_PROPERTY_ID_STYLE, DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FACE_NAME, DWRITE_FONT_PROPERTY_ID_TOTAL = DWRITE_FONT_PROPERTY_ID_STYLE + 1, DWRITE_FONT_PROPERTY_ID_TOTAL_RS3 = DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FACE_NAME + 1,
  DWRITE_FONT_PROPERTY_ID_PREFERRED_FAMILY_NAME = DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FAMILY_NAME, DWRITE_FONT_PROPERTY_ID_FAMILY_NAME = DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FAMILY_NAME, DWRITE_FONT_PROPERTY_ID_FACE_NAME = DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FACE_NAME
}
 The font property enumeration identifies a string in a font. More...
 
enum  DWRITE_LOCALITY { DWRITE_LOCALITY_REMOTE, DWRITE_LOCALITY_PARTIAL, DWRITE_LOCALITY_LOCAL }
 Specifies the locality of a resource. More...
 
enum  DWRITE_RENDERING_MODE1 {
  DWRITE_RENDERING_MODE1_DEFAULT = DWRITE_RENDERING_MODE_DEFAULT, DWRITE_RENDERING_MODE1_ALIASED = DWRITE_RENDERING_MODE_ALIASED, DWRITE_RENDERING_MODE1_GDI_CLASSIC = DWRITE_RENDERING_MODE_GDI_CLASSIC, DWRITE_RENDERING_MODE1_GDI_NATURAL = DWRITE_RENDERING_MODE_GDI_NATURAL,
  DWRITE_RENDERING_MODE1_NATURAL = DWRITE_RENDERING_MODE_NATURAL, DWRITE_RENDERING_MODE1_NATURAL_SYMMETRIC = DWRITE_RENDERING_MODE_NATURAL_SYMMETRIC, DWRITE_RENDERING_MODE1_OUTLINE = DWRITE_RENDERING_MODE_OUTLINE, DWRITE_RENDERING_MODE1_NATURAL_SYMMETRIC_DOWNSAMPLED
}
 Represents a method of rendering glyphs. More...
 
enum  DWRITE_FONT_LINE_GAP_USAGE { DWRITE_FONT_LINE_GAP_USAGE_DEFAULT, DWRITE_FONT_LINE_GAP_USAGE_DISABLED, DWRITE_FONT_LINE_GAP_USAGE_ENABLED }
 Specify whether DWRITE_FONT_METRICS::lineGap value should be part of the line metrics. More...
 
enum  DWRITE_CONTAINER_TYPE { DWRITE_CONTAINER_TYPE_UNKNOWN, DWRITE_CONTAINER_TYPE_WOFF, DWRITE_CONTAINER_TYPE_WOFF2 }
 IDWriteRemoteFontFileStream represents a font file stream parts of which may be non-local. Non-local data must be downloaded before it can be accessed using ReadFragment. The interface exposes methods to download font data and query the locality of font data. More...
 
enum  DWRITE_FONT_AXIS_TAG : UINT32 {
  DWRITE_FONT_AXIS_TAG_WEIGHT = DWRITE_MAKE_FONT_AXIS_TAG('w','g','h','t'), DWRITE_FONT_AXIS_TAG_WIDTH = DWRITE_MAKE_FONT_AXIS_TAG('w','d','t','h'), DWRITE_FONT_AXIS_TAG_SLANT = DWRITE_MAKE_FONT_AXIS_TAG('s','l','n','t'), DWRITE_FONT_AXIS_TAG_OPTICAL_SIZE = DWRITE_MAKE_FONT_AXIS_TAG('o','p','s','z'),
  DWRITE_FONT_AXIS_TAG_ITALIC = DWRITE_MAKE_FONT_AXIS_TAG('i','t','a','l')
}
 Four character identifier for a font axis. More...
 
enum  DWRITE_FONT_FAMILY_MODEL { DWRITE_FONT_FAMILY_MODEL_TYPOGRAPHIC, DWRITE_FONT_FAMILY_MODEL_WEIGHT_STRETCH_STYLE }
 How font families are grouped together, used by IDWriteFontCollection. More...
 
enum  DWRITE_AUTOMATIC_FONT_AXES { DWRITE_AUTOMATIC_FONT_AXES_NONE = 0x0000, DWRITE_AUTOMATIC_FONT_AXES_OPTICAL_SIZE = 0x0001 }
 Apply certain axes automatically in layout during font selection. More...
 
enum  DWRITE_FONT_AXIS_ATTRIBUTES { DWRITE_FONT_AXIS_ATTRIBUTES_NONE = 0x0000, DWRITE_FONT_AXIS_ATTRIBUTES_VARIABLE = 0x0001, DWRITE_FONT_AXIS_ATTRIBUTES_HIDDEN = 0x0002 }
 Attributes for a font axis. More...
 

Variables

interface DWRITE_DECLARE_INTERFACE("68648C83-6EDE-46C0-AB46-20083A887FDE") IDWriteRemoteFontFileLoader interface DWRITE_DECLARE_INTERFACE("DC102F47-A12D-4B1C-822D-9E117E33043F") IDWriteInMemoryFontFileLoader interface DWRITE_DECLARE_INTERFACE("958DB99A-BE2A-4F09-AF7D-65189803D1D3") IDWriteFactory5 interface IDWriteFontResource
 The IDWriteRemoteFontFileLoader interface represents a font file loader that can access remote (i.e., downloadable) fonts. The IDWriteFactory5::CreateHttpFontFileLoader method returns an instance of this interface, or a client can create its own implementation. More...
 

Macro Definition Documentation

◆ DWRITE_E_DOWNLOADCANCELLED

#define DWRITE_E_DOWNLOADCANCELLED   _HRESULT_TYPEDEF_(0x8898500EL)

The download was canceled, which happens if the application calls IDWriteFontDownloadQueue::CancelDownload before they finish.

◆ DWRITE_E_DOWNLOADFAILED

#define DWRITE_E_DOWNLOADFAILED   _HRESULT_TYPEDEF_(0x8898500FL)

The download failed to complete because the remote resource is missing or the network is down.

◆ DWRITE_E_REMOTEFONT

#define DWRITE_E_REMOTEFONT   _HRESULT_TYPEDEF_(0x8898500DL)

A font resource could not be accessed because it was remote. This can happen when calling CreateFontFace on a non-local font or trying to measure/draw glyphs that are not downloaded yet.

◆ DWRITE_E_TOOMANYDOWNLOADS

#define DWRITE_E_TOOMANYDOWNLOADS   _HRESULT_TYPEDEF_(0x88985010L)

A download request was not added or a download failed because there are too many active downloads.

◆ DWRITE_MAKE_FONT_AXIS_TAG

#define DWRITE_MAKE_FONT_AXIS_TAG (   a,
  b,
  c,
 
)    (static_cast<DWRITE_FONT_AXIS_TAG>(DWRITE_MAKE_OPENTYPE_TAG(a,b,c,d)))

Creates an OpenType tag for a font axis.

Enumeration Type Documentation

◆ DWRITE_AUTOMATIC_FONT_AXES

Apply certain axes automatically in layout during font selection.

Enumerator
DWRITE_AUTOMATIC_FONT_AXES_NONE 

No axes are automatically applied.

DWRITE_AUTOMATIC_FONT_AXES_OPTICAL_SIZE 

Automatically pick an appropriate optical value based on the font size (via SetFontSize) when no value is specified via DWRITE_FONT_AXIS_TAG_OPTICAL_SIZE. Callers can still explicitly apply the 'opsz' value over text ranges via SetFontAxisValues, which take priority.

◆ DWRITE_CONTAINER_TYPE

IDWriteRemoteFontFileStream represents a font file stream parts of which may be non-local. Non-local data must be downloaded before it can be accessed using ReadFragment. The interface exposes methods to download font data and query the locality of font data.

For more information, see the description of IDWriteRemoteFontFileLoader.

Specifies the container format of a font resource. A container format is distinct from a font file format (DWRITE_FONT_FILE_TYPE) because the container describes the container in which the underlying font file is packaged.

Enumerator
DWRITE_CONTAINER_TYPE_UNKNOWN 
DWRITE_CONTAINER_TYPE_WOFF 
DWRITE_CONTAINER_TYPE_WOFF2 

◆ DWRITE_FONT_AXIS_ATTRIBUTES

Attributes for a font axis.

Enumerator
DWRITE_FONT_AXIS_ATTRIBUTES_NONE 

No attributes.

DWRITE_FONT_AXIS_ATTRIBUTES_VARIABLE 

This axis is implemented as a variation axis in a variable font, with a continuous range of values, such as a range of weights from 100..900. Otherwise it is either a static axis that holds a single point, or it has a range but doesn't vary, such as optical size in the Skia Heading font which covers a range of points but doesn't interpolate any new glyph outlines.

DWRITE_FONT_AXIS_ATTRIBUTES_HIDDEN 

This axis is recommended to be remain hidden in user interfaces. The font developer may recommend this if an axis is intended to be accessed only programmatically, or is meant for font-internal or font-developer use only. The axis may be exposed in lower-level font inspection utilities, but should not be exposed in common or even advanced-mode user interfaces in content-authoring apps.

◆ DWRITE_FONT_AXIS_TAG

Four character identifier for a font axis.

Use DWRITE_MAKE_FONT_AXIS_TAG() to create a custom one.

Enumerator
DWRITE_FONT_AXIS_TAG_WEIGHT 
DWRITE_FONT_AXIS_TAG_WIDTH 
DWRITE_FONT_AXIS_TAG_SLANT 
DWRITE_FONT_AXIS_TAG_OPTICAL_SIZE 
DWRITE_FONT_AXIS_TAG_ITALIC 

◆ DWRITE_FONT_FAMILY_MODEL

How font families are grouped together, used by IDWriteFontCollection.

Enumerator
DWRITE_FONT_FAMILY_MODEL_TYPOGRAPHIC 

Families are grouped by the typographic family name preferred by the font author. The family can contain as many face as the font author wants. This corresponds to the DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FAMILY_NAME.

DWRITE_FONT_FAMILY_MODEL_WEIGHT_STRETCH_STYLE 

Families are grouped by the weight-stretch-style family name, where all faces that differ only by those three axes are grouped into the same family, but any other axes go into a distinct family. For example, the Sitka family with six different optical sizes yields six separate families (Sitka Caption, Display, Text, Subheading, Heading, Banner...). This corresponds to the DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FAMILY_NAME.

◆ DWRITE_FONT_LINE_GAP_USAGE

Specify whether DWRITE_FONT_METRICS::lineGap value should be part of the line metrics.

Enumerator
DWRITE_FONT_LINE_GAP_USAGE_DEFAULT 

The usage of the font line gap depends on the method used for text layout.

DWRITE_FONT_LINE_GAP_USAGE_DISABLED 

The font line gap is excluded from line spacing

DWRITE_FONT_LINE_GAP_USAGE_ENABLED 

The font line gap is included in line spacing

◆ DWRITE_FONT_PROPERTY_ID

The font property enumeration identifies a string in a font.

Enumerator
DWRITE_FONT_PROPERTY_ID_NONE 

Unspecified font property identifier.

DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FAMILY_NAME 

Family name for the weight-stretch-style model.

DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FAMILY_NAME 

Family name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with GDI. This name is typically only present if it differs from the GDI-compatible family name.

DWRITE_FONT_PROPERTY_ID_WEIGHT_STRETCH_STYLE_FACE_NAME 

Face name of the for the weight-stretch-style (e.g., Regular or Bold).

DWRITE_FONT_PROPERTY_ID_FULL_NAME 

The full name of the font, e.g. "Arial Bold", from name id 4 in the name table.

DWRITE_FONT_PROPERTY_ID_WIN32_FAMILY_NAME 

GDI-compatible family name. Because GDI allows a maximum of four fonts per family, fonts in the same family may have different GDI-compatible family names (e.g., "Arial", "Arial Narrow", "Arial Black").

DWRITE_FONT_PROPERTY_ID_POSTSCRIPT_NAME 

The postscript name of the font, e.g. "GillSans-Bold" from name id 6 in the name table.

DWRITE_FONT_PROPERTY_ID_DESIGN_SCRIPT_LANGUAGE_TAG 

Script/language tag to identify the scripts or languages that the font was primarily designed to support.

The design script/language tag is meant to be understood from the perspective of users. For example, a font is considered designed for English if it is considered useful for English users. Note that this is different from what a font might be capable of supporting. For example, the Meiryo font was primarily designed for Japanese users. While it is capable of displaying English well, it was not meant to be offered for the benefit of non-Japanese-speaking English users.


As another example, a font designed for Chinese may be capable of displaying Japanese text, but would likely look incorrect to Japanese users.


The valid values for this property are "ScriptLangTag" values. These are adapted from the IETF BCP 47 specification, "Tags for Identifying Languages" (see http://tools.ietf.org/html/bcp47). In a BCP 47 language tag, a language subtag element is mandatory and other subtags are optional. In a ScriptLangTag, a script subtag is mandatory and other subtags are option. The following augmented BNF syntax, adapted from BCP 47, is used:

ScriptLangTag = [language "-"]
                script
                ["-" region]
                *("-" variant)
                *("-" extension)
                ["-" privateuse]

The expansion of the elements and the intended semantics associated with each are as defined in BCP 47. Script subtags are taken from ISO 15924. At present, no extensions are defined, and any extension should be ignored. Private use subtags are defined by private agreement between the source and recipient and may be ignored.


Subtags must be valid for use in BCP 47 and contained in the Language Subtag Registry maintained by IANA. (See http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry and section 3 of BCP 47 for details.


Any ScriptLangTag value not conforming to these specifications is ignored.


Examples: "Latn" denotes Latin script (and any language or writing system using Latin) "Cyrl" denotes Cyrillic script "sr-Cyrl" denotes Cyrillic script as used for writing the Serbian language; a font that has this property value may not be suitable for displaying text in Russian or other languages written using Cyrillic script "Jpan" denotes Japanese writing (Han + Hiragana + Katakana)


When passing this property to GetPropertyValues, use the overload which does not take a language parameter, since this property has no specific language.

DWRITE_FONT_PROPERTY_ID_SUPPORTED_SCRIPT_LANGUAGE_TAG 

Script/language tag to identify the scripts or languages that the font declares it is able to support.

DWRITE_FONT_PROPERTY_ID_SEMANTIC_TAG 

Semantic tag to describe the font (e.g. Fancy, Decorative, Handmade, Sans-serif, Swiss, Pixel, Futuristic).

DWRITE_FONT_PROPERTY_ID_WEIGHT 

Weight of the font represented as a decimal string in the range 1-999.

<remark> This enum is discouraged for use with IDWriteFontSetBuilder2 in favor of the more generic font axis DWRITE_FONT_AXIS_TAG_WEIGHT which supports higher precision and range. </remark>

DWRITE_FONT_PROPERTY_ID_STRETCH 

Stretch of the font represented as a decimal string in the range 1-9.

<remark> This enum is discouraged for use with IDWriteFontSetBuilder2 in favor of the more generic font axis DWRITE_FONT_AXIS_TAG_WIDTH which supports higher precision and range. </remark>

DWRITE_FONT_PROPERTY_ID_STYLE 

Style of the font represented as a decimal string in the range 0-2.

<remark> This enum is discouraged for use with IDWriteFontSetBuilder2 in favor of the more generic font axes DWRITE_FONT_AXIS_TAG_SLANT and DWRITE_FONT_AXIS_TAG_ITAL. </remark>

DWRITE_FONT_PROPERTY_ID_TYPOGRAPHIC_FACE_NAME 

Face name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with GDI.

DWRITE_FONT_PROPERTY_ID_TOTAL 

Total number of properties for NTDDI_WIN10 (IDWriteFontSet).

DWRITE_FONT_PROPERTY_ID_TOTAL cannot be used as a property ID.

DWRITE_FONT_PROPERTY_ID_TOTAL_RS3 

Total number of properties for NTDDI_WIN10_RS3 (IDWriteFontSet1).

DWRITE_FONT_PROPERTY_ID_PREFERRED_FAMILY_NAME 
DWRITE_FONT_PROPERTY_ID_FAMILY_NAME 
DWRITE_FONT_PROPERTY_ID_FACE_NAME 

◆ DWRITE_LOCALITY

Specifies the locality of a resource.

Enumerator
DWRITE_LOCALITY_REMOTE 

The resource is remote, and information is unknown yet, including the file size and date. Attempting to create a font or file stream will fail until locality becomes at least partial.

DWRITE_LOCALITY_PARTIAL 

The resource is partially local, meaning you can query the size and date of the file stream, and you may be able to create a font face and retrieve the particular glyphs for metrics and drawing, but not all the glyphs will be present.

DWRITE_LOCALITY_LOCAL 

The resource is completely local, and all font functions can be called without concern of missing data or errors related to network connectivity.

◆ DWRITE_RENDERING_MODE1

Represents a method of rendering glyphs.

Enumerator
DWRITE_RENDERING_MODE1_DEFAULT 

Specifies that the rendering mode is determined automatically based on the font and size.

DWRITE_RENDERING_MODE1_ALIASED 

Specifies that no antialiasing is performed. Each pixel is either set to the foreground color of the text or retains the color of the background.

DWRITE_RENDERING_MODE1_GDI_CLASSIC 

Specifies that antialiasing is performed in the horizontal direction and the appearance of glyphs is layout-compatible with GDI using CLEARTYPE_QUALITY. Use DWRITE_MEASURING_MODE_GDI_CLASSIC to get glyph advances. The antialiasing may be either ClearType or grayscale depending on the text antialiasing mode.

DWRITE_RENDERING_MODE1_GDI_NATURAL 

Specifies that antialiasing is performed in the horizontal direction and the appearance of glyphs is layout-compatible with GDI using CLEARTYPE_NATURAL_QUALITY. Glyph advances are close to the font design advances, but are still rounded to whole pixels. Use DWRITE_MEASURING_MODE_GDI_NATURAL to get glyph advances. The antialiasing may be either ClearType or grayscale depending on the text antialiasing mode.

DWRITE_RENDERING_MODE1_NATURAL 

Specifies that antialiasing is performed in the horizontal direction. This rendering mode allows glyphs to be positioned with subpixel precision and is therefore suitable for natural (i.e., resolution-independent) layout. The antialiasing may be either ClearType or grayscale depending on the text antialiasing mode.

DWRITE_RENDERING_MODE1_NATURAL_SYMMETRIC 

Similar to natural mode except that antialiasing is performed in both the horizontal and vertical directions. This is typically used at larger sizes to make curves and diagonal lines look smoother. The antialiasing may be either ClearType or grayscale depending on the text antialiasing mode.

DWRITE_RENDERING_MODE1_OUTLINE 

Specifies that rendering should bypass the rasterizer and use the outlines directly. This is typically used at very large sizes.

DWRITE_RENDERING_MODE1_NATURAL_SYMMETRIC_DOWNSAMPLED 

Similar to natural symmetric mode except that when possible, text should be rasterized in a downsampled form.

Variable Documentation

◆ IDWriteFontResource

interface DWRITE_DECLARE_INTERFACE ("68648C83-6EDE-46C0-AB46-20083A887FDE") IDWriteRemoteFontFileLoader interface DWRITE_DECLARE_INTERFACE ("DC102F47-A12D-4B1C-822D-9E117E33043F") IDWriteInMemoryFontFileLoader interface DWRITE_DECLARE_INTERFACE ("958DB99A-BE2A-4F09-AF7D-65189803D1D3") IDWriteFactory5 interface IDWriteFontResource

The IDWriteRemoteFontFileLoader interface represents a font file loader that can access remote (i.e., downloadable) fonts. The IDWriteFactory5::CreateHttpFontFileLoader method returns an instance of this interface, or a client can create its own implementation.

Calls to a remote file loader or stream should never block waiting for network operations. Any call that cannot succeeded immediately using local (e.g., cached) must should return DWRITE_E_REMOTEFONT. This error signifies to DWrite that it should add requests to the font download queue.

The IDWriteInMemoryFontFileLoader interface enables clients to reference in-memory fonts without having to implement a custom loader. The IDWriteFactory5::CreateInMemoryFontFileLoader method returns an instance of this interface, which the client is responsible for registering and unregistering using IDWriteFactory::RegisterFontFileLoader and IDWriteFactory::UnregisterFontFileLoader.

The root factory interface for all DWrite objects.