//+--------------------------------------------------------------------------
//
// Copyright (c) Microsoft Corporation. All rights reserved.
//
// Abstract:
// DirectX Typography Services public API definitions.
//
//----------------------------------------------------------------------------
#ifndef DWRITE_H_INCLUDED
#define DWRITE_H_INCLUDED
#if _MSC_VER > 1000
#pragma once
#endif
#ifndef DWRITE_NO_WINDOWS_H
#include "specstrings.h"
#include "unknwn.h"
#endif // DWRITE_NO_WINDOWS_H
#include "dcommon.h"
#if _FX_COMPILER_ == _FX_VC6_
typedef signed char INT8, *PINT8;
typedef signed short INT16, *PINT16;
typedef signed int INT32, *PINT32;
typedef signed __int64 INT64, *PINT64;
typedef unsigned char UINT8, *PUINT8;
typedef unsigned short UINT16, *PUINT16;
typedef unsigned int UINT32, *PUINT32;
typedef unsigned __int64 UINT64, *PUINT64;
#endif
#ifndef DWRITE_DECLARE_INTERFACE
#define DWRITE_DECLARE_INTERFACE(iid) DECLSPEC_UUID(iid) DECLSPEC_NOVTABLE
#endif
#ifndef DWRITE_EXPORT
#define DWRITE_EXPORT __declspec(dllimport) WINAPI
#endif
///
/// The type of a font represented by a single font file.
/// Font formats that consist of multiple files, e.g. Type 1 .PFM and .PFB, have
/// separate enum values for each of the file type.
///
enum DWRITE_FONT_FILE_TYPE
{
///
/// Font type is not recognized by the DirectWrite font system.
///
DWRITE_FONT_FILE_TYPE_UNKNOWN,
///
/// OpenType font with CFF outlines.
///
DWRITE_FONT_FILE_TYPE_CFF,
///
/// OpenType font with TrueType outlines.
///
DWRITE_FONT_FILE_TYPE_TRUETYPE,
///
/// OpenType font that contains a TrueType collection.
///
DWRITE_FONT_FILE_TYPE_TRUETYPE_COLLECTION,
///
/// Type 1 PFM font.
///
DWRITE_FONT_FILE_TYPE_TYPE1_PFM,
///
/// Type 1 PFB font.
///
DWRITE_FONT_FILE_TYPE_TYPE1_PFB,
///
/// Vector .FON font.
///
DWRITE_FONT_FILE_TYPE_VECTOR,
///
/// Bitmap .FON font.
///
DWRITE_FONT_FILE_TYPE_BITMAP
};
///
/// The file format of a complete font face.
/// Font formats that consist of multiple files, e.g. Type 1 .PFM and .PFB, have
/// a single enum entry.
///
enum DWRITE_FONT_FACE_TYPE
{
///
/// OpenType font face with CFF outlines.
///
DWRITE_FONT_FACE_TYPE_CFF,
///
/// OpenType font face with TrueType outlines.
///
DWRITE_FONT_FACE_TYPE_TRUETYPE,
///
/// OpenType font face that is a part of a TrueType collection.
///
DWRITE_FONT_FACE_TYPE_TRUETYPE_COLLECTION,
///
/// A Type 1 font face.
///
DWRITE_FONT_FACE_TYPE_TYPE1,
///
/// A vector .FON format font face.
///
DWRITE_FONT_FACE_TYPE_VECTOR,
///
/// A bitmap .FON format font face.
///
DWRITE_FONT_FACE_TYPE_BITMAP,
///
/// Font face type is not recognized by the DirectWrite font system.
///
DWRITE_FONT_FACE_TYPE_UNKNOWN
};
///
/// Specifies algorithmic style simulations to be applied to the font face.
/// Bold and oblique simulations can be combined via bitwise OR operation.
///
enum DWRITE_FONT_SIMULATIONS
{
///
/// No simulations are performed.
///
DWRITE_FONT_SIMULATIONS_NONE = 0x0000,
///
/// Algorithmic emboldening is performed.
///
DWRITE_FONT_SIMULATIONS_BOLD = 0x0001,
///
/// Algorithmic italicization is performed.
///
DWRITE_FONT_SIMULATIONS_OBLIQUE = 0x0002
};
#ifdef DEFINE_ENUM_FLAG_OPERATORS
DEFINE_ENUM_FLAG_OPERATORS(DWRITE_FONT_SIMULATIONS);
#endif
///
/// The font weight enumeration describes common values for degree of blackness or thickness of strokes of characters in a font.
/// Font weight values less than 1 or greater than 999 are considered to be invalid, and they are rejected by font API functions.
///
enum DWRITE_FONT_WEIGHT
{
///
/// Predefined font weight : Thin (100).
///
DWRITE_FONT_WEIGHT_THIN = 100,
///
/// Predefined font weight : Extra-light (200).
///
DWRITE_FONT_WEIGHT_EXTRA_LIGHT = 200,
///
/// Predefined font weight : Ultra-light (200).
///
DWRITE_FONT_WEIGHT_ULTRA_LIGHT = 200,
///
/// Predefined font weight : Light (300).
///
DWRITE_FONT_WEIGHT_LIGHT = 300,
///
/// Predefined font weight : Normal (400).
///
DWRITE_FONT_WEIGHT_NORMAL = 400,
///
/// Predefined font weight : Regular (400).
///
DWRITE_FONT_WEIGHT_REGULAR = 400,
///
/// Predefined font weight : Medium (500).
///
DWRITE_FONT_WEIGHT_MEDIUM = 500,
///
/// Predefined font weight : Demi-bold (600).
///
DWRITE_FONT_WEIGHT_DEMI_BOLD = 600,
///
/// Predefined font weight : Semi-bold (600).
///
DWRITE_FONT_WEIGHT_SEMI_BOLD = 600,
///
/// Predefined font weight : Bold (700).
///
DWRITE_FONT_WEIGHT_BOLD = 700,
///
/// Predefined font weight : Extra-bold (800).
///
DWRITE_FONT_WEIGHT_EXTRA_BOLD = 800,
///
/// Predefined font weight : Ultra-bold (800).
///
DWRITE_FONT_WEIGHT_ULTRA_BOLD = 800,
///
/// Predefined font weight : Black (900).
///
DWRITE_FONT_WEIGHT_BLACK = 900,
///
/// Predefined font weight : Heavy (900).
///
DWRITE_FONT_WEIGHT_HEAVY = 900,
///
/// Predefined font weight : Extra-black (950).
///
DWRITE_FONT_WEIGHT_EXTRA_BLACK = 950,
///
/// Predefined font weight : Ultra-black (950).
///
DWRITE_FONT_WEIGHT_ULTRA_BLACK = 950
};
///
/// The font stretch enumeration describes relative change from the normal aspect ratio
/// as specified by a font designer for the glyphs in a font.
/// Values less than 1 or greater than 9 are considered to be invalid, and they are rejected by font API functions.
///
enum DWRITE_FONT_STRETCH
{
///
/// Predefined font stretch : Not known (0).
///
DWRITE_FONT_STRETCH_UNDEFINED = 0,
///
/// Predefined font stretch : Ultra-condensed (1).
///
DWRITE_FONT_STRETCH_ULTRA_CONDENSED = 1,
///
/// Predefined font stretch : Extra-condensed (2).
///
DWRITE_FONT_STRETCH_EXTRA_CONDENSED = 2,
///
/// Predefined font stretch : Condensed (3).
///
DWRITE_FONT_STRETCH_CONDENSED = 3,
///
/// Predefined font stretch : Semi-condensed (4).
///
DWRITE_FONT_STRETCH_SEMI_CONDENSED = 4,
///
/// Predefined font stretch : Normal (5).
///
DWRITE_FONT_STRETCH_NORMAL = 5,
///
/// Predefined font stretch : Medium (5).
///
DWRITE_FONT_STRETCH_MEDIUM = 5,
///
/// Predefined font stretch : Semi-expanded (6).
///
DWRITE_FONT_STRETCH_SEMI_EXPANDED = 6,
///
/// Predefined font stretch : Expanded (7).
///
DWRITE_FONT_STRETCH_EXPANDED = 7,
///
/// Predefined font stretch : Extra-expanded (8).
///
DWRITE_FONT_STRETCH_EXTRA_EXPANDED = 8,
///
/// Predefined font stretch : Ultra-expanded (9).
///
DWRITE_FONT_STRETCH_ULTRA_EXPANDED = 9
};
///
/// The font style enumeration describes the slope style of a font face, such as Normal, Italic or Oblique.
/// Values other than the ones defined in the enumeration are considered to be invalid, and they are rejected by font API functions.
///
enum DWRITE_FONT_STYLE
{
///
/// Font slope style : Normal.
///
DWRITE_FONT_STYLE_NORMAL,
///
/// Font slope style : Oblique.
///
DWRITE_FONT_STYLE_OBLIQUE,
///
/// Font slope style : Italic.
///
DWRITE_FONT_STYLE_ITALIC
};
///
/// The informational string enumeration identifies a string in a font.
///
enum DWRITE_INFORMATIONAL_STRING_ID
{
///
/// Unspecified name ID.
///
DWRITE_INFORMATIONAL_STRING_NONE,
///
/// Copyright notice provided by the font.
///
DWRITE_INFORMATIONAL_STRING_COPYRIGHT_NOTICE,
///
/// String containing a version number.
///
DWRITE_INFORMATIONAL_STRING_VERSION_STRINGS,
///
/// Trademark information provided by the font.
///
DWRITE_INFORMATIONAL_STRING_TRADEMARK,
///
/// Name of the font manufacturer.
///
DWRITE_INFORMATIONAL_STRING_MANUFACTURER,
///
/// Name of the font designer.
///
DWRITE_INFORMATIONAL_STRING_DESIGNER,
///
/// URL of font designer (with protocol, e.g., http://, ftp://).
///
DWRITE_INFORMATIONAL_STRING_DESIGNER_URL,
///
/// Description of the font. Can contain revision information, usage recommendations, history, features, etc.
///
DWRITE_INFORMATIONAL_STRING_DESCRIPTION,
///
/// URL of font vendor (with protocol, e.g., http://, ftp://). If a unique serial number is embedded in the URL, it can be used to register the font.
///
DWRITE_INFORMATIONAL_STRING_FONT_VENDOR_URL,
///
/// Description of how the font may be legally used, or different example scenarios for licensed use. This field should be written in plain language, not legalese.
///
DWRITE_INFORMATIONAL_STRING_LICENSE_DESCRIPTION,
///
/// URL where additional licensing information can be found.
///
DWRITE_INFORMATIONAL_STRING_LICENSE_INFO_URL,
///
/// 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_INFORMATIONAL_STRING_WIN32_FAMILY_NAMES,
///
/// GDI-compatible subfamily name.
///
DWRITE_INFORMATIONAL_STRING_WIN32_SUBFAMILY_NAMES,
///
/// 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_INFORMATIONAL_STRING_PREFERRED_FAMILY_NAMES,
///
/// Subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
///
DWRITE_INFORMATIONAL_STRING_PREFERRED_SUBFAMILY_NAMES,
///
/// Sample text. This can be the font name or any other text that the designer thinks is the best example to display the font in.
///
DWRITE_INFORMATIONAL_STRING_SAMPLE_TEXT
};
///
/// The DWRITE_FONT_METRICS structure specifies the metrics of a font face that
/// are applicable to all glyphs within the font face.
///
struct DWRITE_FONT_METRICS
{
///
/// The number of font design units per em unit.
/// Font files use their own coordinate system of font design units.
/// A font design unit is the smallest measurable unit in the em square,
/// an imaginary square that is used to size and align glyphs.
/// The concept of em square is used as a reference scale factor when defining font size and device transformation semantics.
/// The size of one em square is also commonly used to compute the paragraph identation value.
///
UINT16 designUnitsPerEm;
///
/// Ascent value of the font face in font design units.
/// Ascent is the distance from the top of font character alignment box to English baseline.
///
UINT16 ascent;
///
/// Descent value of the font face in font design units.
/// Descent is the distance from the bottom of font character alignment box to English baseline.
///
UINT16 descent;
///
/// Line gap in font design units.
/// Recommended additional white space to add between lines to improve legibility. The recommended line spacing
/// (baseline-to-baseline distance) is thus the sum of ascent, descent, and lineGap. The line gap is usually
/// positive or zero but can be negative, in which case the recommended line spacing is less than the height
/// of the character alignment box.
///
INT16 lineGap;
///
/// Cap height value of the font face in font design units.
/// Cap height is the distance from English baseline to the top of a typical English capital.
/// Capital "H" is often used as a reference character for the purpose of calculating the cap height value.
///
UINT16 capHeight;
///
/// x-height value of the font face in font design units.
/// x-height is the distance from English baseline to the top of lowercase letter "x", or a similar lowercase character.
///
UINT16 xHeight;
///
/// The underline position value of the font face in font design units.
/// Underline position is the position of underline relative to the English baseline.
/// The value is usually made negative in order to place the underline below the baseline.
///
INT16 underlinePosition;
///
/// The suggested underline thickness value of the font face in font design units.
///
UINT16 underlineThickness;
///
/// The strikethrough position value of the font face in font design units.
/// Strikethrough position is the position of strikethrough relative to the English baseline.
/// The value is usually made positive in order to place the strikethrough above the baseline.
///
INT16 strikethroughPosition;
///
/// The suggested strikethrough thickness value of the font face in font design units.
///
UINT16 strikethroughThickness;
};
///
/// The DWRITE_GLYPH_METRICS structure specifies the metrics of an individual glyph.
/// The units depend on how the metrics are obtained.
///
struct DWRITE_GLYPH_METRICS
{
///
/// Specifies the X offset from the glyph origin to the left edge of the black box.
/// The glyph origin is the current horizontal writing position.
/// A negative value means the black box extends to the left of the origin (often true for lowercase italic 'f').
///
INT32 leftSideBearing;
///
/// Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
///
UINT32 advanceWidth;
///
/// Specifies the X offset from the right edge of the black box to the origin of the next glyph when writing horizontally.
/// The value is negative when the right edge of the black box overhangs the layout box.
///
INT32 rightSideBearing;
///
/// Specifies the vertical offset from the vertical origin to the top of the black box.
/// Thus, a positive value adds whitespace whereas a negative value means the glyph overhangs the top of the layout box.
///
INT32 topSideBearing;
///
/// Specifies the Y offset from the vertical origin of the current glyph to the vertical origin of the next glyph when writing vertically.
/// (Note that the term "origin" by itself denotes the horizontal origin. The vertical origin is different.
/// Its Y coordinate is specified by verticalOriginY value,
/// and its X coordinate is half the advanceWidth to the right of the horizontal origin).
///
UINT32 advanceHeight;
///
/// Specifies the vertical distance from the black box's bottom edge to the advance height.
/// Positive when the bottom edge of the black box is within the layout box.
/// Negative when the bottom edge of black box overhangs the layout box.
///
INT32 bottomSideBearing;
///
/// Specifies the Y coordinate of a glyph's vertical origin, in the font's design coordinate system.
/// The y coordinate of a glyph's vertical origin is the sum of the glyph's top side bearing
/// and the top (i.e. yMax) of the glyph's bounding box.
///
INT32 verticalOriginY;
};
///
/// Optional adjustment to a glyph's position. An glyph offset changes the position of a glyph without affecting
/// the pen position. Offsets are in logical, pre-transform units.
///
struct DWRITE_GLYPH_OFFSET
{
///
/// Offset in the advance direction of the run. A positive advance offset moves the glyph to the right
/// (in pre-transform coordinates) if the run is left-to-right or to the left if the run is right-to-left.
///
FLOAT advanceOffset;
///
/// Offset in the ascent direction, i.e., the direction ascenders point. A positive ascender offset moves
/// the glyph up (in pre-transform coordinates).
///
FLOAT ascenderOffset;
};
///
/// Specifies the type of DirectWrite factory object.
/// DirectWrite factory contains internal state such as font loader registration and cached font data.
/// In most cases it is recommended to use the shared factory object, because it allows multiple components
/// that use DirectWrite to share internal DirectWrite state and reduce memory usage.
/// However, there are cases when it is desirable to reduce the impact of a component,
/// such as a plug-in from an untrusted source, on the rest of the process by sandboxing and isolating it
/// from the rest of the process components. In such cases, it is recommended to use an isolated factory for the sandboxed
/// component.
///
enum DWRITE_FACTORY_TYPE
{
///
/// Shared factory allow for re-use of cached font data across multiple in process components.
/// Such factories also take advantage of cross process font caching components for better performance.
///
DWRITE_FACTORY_TYPE_SHARED,
///
/// Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
///
DWRITE_FACTORY_TYPE_ISOLATED
};
// Creates an OpenType tag as a 32bit integer such that
// the first character in the tag is the lowest byte,
// (least significant on little endian architectures)
// which can be used to compare with tags in the font file.
// This macro is compatible with DWRITE_FONT_FEATURE_TAG.
//
// Example: DWRITE_MAKE_OPENTYPE_TAG('c','c','m','p')
// Dword: 0x706D6363
//
#define DWRITE_MAKE_OPENTYPE_TAG(a,b,c,d) ( \
(static_cast(static_cast(d)) << 24) | \
(static_cast(static_cast(c)) << 16) | \
(static_cast(static_cast(b)) << 8) | \
static_cast(static_cast(a)))
interface IDWriteFontFileStream;
///
/// Font file loader interface handles loading font file resources of a particular type from a key.
/// The font file loader interface is recommended to be implemented by a singleton object.
/// IMPORTANT: font file loader implementations must not register themselves with DirectWrite factory
/// inside their constructors and must not unregister themselves in their destructors, because
/// registration and unregistraton operations increment and decrement the object reference count respectively.
/// Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed
/// outside of the font file loader implementation as a separate step.
///
interface DWRITE_DECLARE_INTERFACE("727cad4e-d6af-4c9e-8a08-d695b11caa49") IDWriteFontFileLoader : public IUnknown
{
///
/// Creates a font file stream object that encapsulates an open file resource.
/// The resource is closed when the last reference to fontFileStream is released.
///
/// Font file reference key that uniquely identifies the font file resource
/// within the scope of the font loader being used.
/// Size of font file reference key in bytes.
/// Pointer to the newly created font file stream.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateStreamFromKey)(
__in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
UINT32 fontFileReferenceKeySize,
__out IDWriteFontFileStream** fontFileStream
) PURE;
};
///
/// A built-in implementation of IDWriteFontFileLoader interface that operates on local font files
/// and exposes local font file information from the font file reference key.
/// Font file references created using CreateFontFileReference use this font file loader.
///
interface DWRITE_DECLARE_INTERFACE("b2d9f3ec-c9fe-4a11-a2ec-d86208f7c0a2") IDWriteLocalFontFileLoader : public IDWriteFontFileLoader
{
///
/// Obtains the length of the absolute file path from the font file reference key.
///
/// Font file reference key that uniquely identifies the local font file
/// within the scope of the font loader being used.
/// Size of font file reference key in bytes.
/// Length of the file path string not including the terminated NULL character.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFilePathLengthFromKey)(
__in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
UINT32 fontFileReferenceKeySize,
__out UINT32* filePathLength
) PURE;
///
/// Obtains the absolute font file path from the font file reference key.
///
/// Font file reference key that uniquely identifies the local font file
/// within the scope of the font loader being used.
/// Size of font file reference key in bytes.
/// Character array that receives the local file path.
/// Size of the filePath array in character count including the terminated NULL character.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFilePathFromKey)(
__in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
UINT32 fontFileReferenceKeySize,
__out_ecount_z(filePathSize) WCHAR* filePath,
UINT32 filePathSize
) PURE;
///
/// Obtains the last write time of the file from the font file reference key.
///
/// Font file reference key that uniquely identifies the local font file
/// within the scope of the font loader being used.
/// Size of font file reference key in bytes.
/// Last modified time of the font file.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLastWriteTimeFromKey)(
__in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
UINT32 fontFileReferenceKeySize,
__out FILETIME* lastWriteTime
) PURE;
};
///
/// The interface for loading font file data.
///
interface DWRITE_DECLARE_INTERFACE("6d4865fe-0ab8-4d91-8f62-5dd6be34a3e0") IDWriteFontFileStream : public IUnknown
{
///
/// Reads a fragment from a file.
///
/// Receives the pointer to the start of the font file fragment.
/// Offset of the fragment from the beginning of the font file.
/// Size of the fragment in bytes.
/// The client defined context to be passed to the ReleaseFileFragment.
///
/// Standard HRESULT error code.
///
///
/// IMPORTANT: ReadFileFragment() implementations must check whether the requested file fragment
/// is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
///
STDMETHOD(ReadFileFragment)(
__deref_out_bcount(fragmentSize) void const** fragmentStart,
UINT64 fileOffset,
UINT64 fragmentSize,
__out void** fragmentContext
) PURE;
///
/// Releases a fragment from a file.
///
/// The client defined context of a font fragment returned from ReadFileFragment.
STDMETHOD_(void, ReleaseFileFragment)(
void* fragmentContext
) PURE;
///
/// Obtains the total size of a file.
///
/// Receives the total size of the file.
///
/// Standard HRESULT error code.
///
///
/// Implementing GetFileSize() for asynchronously loaded font files may require
/// downloading the complete file contents, therefore this method should only be used for operations that
/// either require complete font file to be loaded (e.g., copying a font file) or need to make
/// decisions based on the value of the file size (e.g., validation against a persisted file size).
///
STDMETHOD(GetFileSize)(
__out UINT64* fileSize
) PURE;
///
/// Obtains the last modified time of the file. The last modified time is used by DirectWrite font selection algorithms
/// to determine whether one font resource is more up to date than another one.
///
/// Receives the last modifed time of the file in the format that represents
/// the number of 100-nanosecond intervals since January 1, 1601 (UTC).
///
/// Standard HRESULT error code. For resources that don't have a concept of the last modified time, the implementation of
/// GetLastWriteTime should return E_NOTIMPL.
///
STDMETHOD(GetLastWriteTime)(
__out UINT64* lastWriteTime
) PURE;
};
///
/// The interface that represents a reference to a font file.
///
interface DWRITE_DECLARE_INTERFACE("739d886a-cef5-47dc-8769-1a8b41bebbb0") IDWriteFontFile : public IUnknown
{
///
/// This method obtains the pointer to the reference key of a font file. The pointer is only valid until the object that refers to it is released.
///
/// Pointer to the font file reference key.
/// IMPORTANT: The pointer value is valid until the font file reference object it is obtained from is released.
/// Size of font file reference key in bytes.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetReferenceKey)(
__deref_out_bcount(*fontFileReferenceKeySize) void const** fontFileReferenceKey,
__out UINT32* fontFileReferenceKeySize
) PURE;
///
/// Obtains the file loader associated with a font file object.
///
/// The font file loader associated with the font file object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLoader)(
__out IDWriteFontFileLoader** fontFileLoader
) PURE;
///
/// Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
///
/// TRUE if the font type is supported by the font system, FALSE otherwise.
/// The type of the font file. Note that even if isSupportedFontType is FALSE,
/// the fontFileType value may be different from DWRITE_FONT_FILE_TYPE_UNKNOWN.
/// The type of the font face that can be constructed from the font file.
/// Note that even if isSupportedFontType is FALSE, the fontFaceType value may be different from
/// DWRITE_FONT_FACE_TYPE_UNKNOWN.
/// Number of font faces contained in the font file.
///
/// Standard HRESULT error code if there was a processing error during analysis.
///
///
/// IMPORTANT: certain font file types are recognized, but not supported by the font system.
/// For example, the font system will recognize a file as a Type 1 font file,
/// but will not be able to construct a font face object from it. In such situations, Analyze will set
/// isSupportedFontType output parameter to FALSE.
///
STDMETHOD(Analyze)(
__out BOOL* isSupportedFontType,
__out DWRITE_FONT_FILE_TYPE* fontFileType,
__out_opt DWRITE_FONT_FACE_TYPE* fontFaceType,
__out UINT32* numberOfFaces
) PURE;
};
///
/// Represents the internal structure of a device pixel (i.e., the physical arrangement of red,
/// green, and blue color components) that is assumed for purposes of rendering text.
///
#ifndef DWRITE_PIXEL_GEOMETRY_DEFINED
enum DWRITE_PIXEL_GEOMETRY
{
///
/// The red, green, and blue color components of each pixel are assumed to occupy the same point.
///
DWRITE_PIXEL_GEOMETRY_FLAT,
///
/// Each pixel comprises three vertical stripes, with red on the left, green in the center, and
/// blue on the right. This is the most common pixel geometry for LCD monitors.
///
DWRITE_PIXEL_GEOMETRY_RGB,
///
/// Each pixel comprises three vertical stripes, with blue on the left, green in the center, and
/// red on the right.
///
DWRITE_PIXEL_GEOMETRY_BGR
};
#define DWRITE_PIXEL_GEOMETRY_DEFINED
#endif
///
/// Represents a method of rendering glyphs.
///
enum DWRITE_RENDERING_MODE
{
///
/// Specifies that the rendering mode is determined automatically based on the font and size.
///
DWRITE_RENDERING_MODE_DEFAULT,
///
/// Specifies that no anti-aliasing is performed. Each pixel is either set to the foreground
/// color of the text or retains the color of the background.
///
DWRITE_RENDERING_MODE_ALIASED,
///
/// Specifies ClearType rendering with the same metrics as aliased text. Glyphs can only
/// be positioned on whole-pixel boundaries.
///
DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC,
///
/// Specifies ClearType rendering with the same metrics as text rendering using GDI using a font
/// created with CLEARTYPE_NATURAL_QUALITY. Glyph metrics are closer to their ideal values than
/// with aliased text, but glyphs are still positioned on whole-pixel boundaries.
///
DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL,
///
/// Specifies ClearType rendering with anti-aliasing in the horizontal dimension only. This is
/// typically used with small to medium font sizes (up to 16 ppem).
///
DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL,
///
/// Specifies ClearType rendering with anti-aliasing in both horizontal and vertical dimensions.
/// This is typically used at larger sizes to makes curves and diagonal lines look smoother, at
/// the expense of some softness.
///
DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL_SYMMETRIC,
///
/// Specifies that rendering should bypass the rasterizer and use the outlines directly. This is
/// typically used at very large sizes.
///
DWRITE_RENDERING_MODE_OUTLINE
};
///
/// The DWRITE_MATRIX structure specifies the graphics transform to be applied
/// to rendered glyphs.
///
struct DWRITE_MATRIX
{
///
/// Horizontal scaling / cosine of rotation
///
FLOAT m11;
///
/// Vertical shear / sine of rotation
///
FLOAT m12;
///
/// Horizontal shear / negative sine of rotation
///
FLOAT m21;
///
/// Vertical scaling / cosine of rotation
///
FLOAT m22;
///
/// Horizontal shift (always orthogonal regardless of rotation)
///
FLOAT dx;
///
/// Vertical shift (always orthogonal regardless of rotation)
///
FLOAT dy;
};
///
/// The interface that represents text rendering settings for glyph rasterization and filtering.
///
interface DWRITE_DECLARE_INTERFACE("2f0da53a-2add-47cd-82ee-d9ec34688e75") IDWriteRenderingParams : public IUnknown
{
///
/// Gets the gamma value used for gamma correction. Valid values must be
/// greater than zero and cannot exceed 256.
///
STDMETHOD_(FLOAT, GetGamma)() PURE;
///
/// Gets the amount of contrast enhancement. Valid values are greater than
/// or equal to zero.
///
STDMETHOD_(FLOAT, GetEnhancedContrast)() PURE;
///
/// Gets the ClearType level. Valid values range from 0.0f (no ClearType)
/// to 1.0f (full ClearType).
///
STDMETHOD_(FLOAT, GetClearTypeLevel)() PURE;
///
/// Gets the pixel geometry.
///
STDMETHOD_(DWRITE_PIXEL_GEOMETRY, GetPixelGeometry)() PURE;
///
/// Gets the rendering mode.
///
STDMETHOD_(DWRITE_RENDERING_MODE, GetRenderingMode)() PURE;
};
// Forward declarations of D2D types
interface ID2D1SimplifiedGeometrySink;
typedef ID2D1SimplifiedGeometrySink IDWriteGeometrySink;
///
/// 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.
///
interface DWRITE_DECLARE_INTERFACE("5f49804d-7024-4d43-bfa9-d25984f53849") IDWriteFontFace : public IUnknown
{
///
/// Obtains the file format type of a font face.
///
STDMETHOD_(DWRITE_FONT_FACE_TYPE, GetType)() PURE;
///
/// Obtains the font files representing a font face.
///
/// The number of files representing the font face.
/// User provided array that stores pointers to font files representing the font face.
/// This parameter can be NULL if the user is only interested in the number of files representing the font face.
/// This API increments reference count of the font file pointers returned according to COM conventions, and the client
/// should release them when finished.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFiles)(
__inout UINT32* numberOfFiles,
__out_ecount_opt(*numberOfFiles) IDWriteFontFile** fontFiles
) PURE;
///
/// Obtains 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.
///
STDMETHOD_(UINT32, GetIndex)() PURE;
///
/// Obtains the algorithmic style simulation flags of a font face.
///
STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE;
///
/// Determines whether the font is a symbol font.
///
STDMETHOD_(BOOL, IsSymbolFont)() PURE;
///
/// 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.
///
/// Points to a DWRITE_FONT_METRICS structure to fill in.
/// The metrics returned by this function are in font design units.
STDMETHOD_(void, GetMetrics)(
__out DWRITE_FONT_METRICS* fontFaceMetrics
) PURE;
///
/// Obtains the number of glyphs in the font face.
///
STDMETHOD_(UINT16, GetGlyphCount)() PURE;
///
/// Obtains ideal glyph metrics in font design units. Design glyphs metrics are used for glyph positioning.
///
/// An array of glyph indices to compute the metrics for.
/// The number of elements in the glyphIndices array.
/// Array of DWRITE_GLYPH_METRICS structures filled by this function.
/// The metrics returned by this function are in font design units.
/// 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.
///
/// Standard HRESULT error code. 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.
///
STDMETHOD(GetDesignGlyphMetrics)(
__in_ecount(glyphCount) UINT16 const* glyphIndices,
UINT32 glyphCount,
__out_ecount(glyphCount) DWRITE_GLYPH_METRICS* glyphMetrics,
BOOL isSideways = FALSE
) PURE;
///
/// Returns the nominal mapping of UCS4 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 Variant Selectors provide for alternate mappings for character to glyph.
/// This call will always return the default variant.
///
/// An array of USC4 code points to obtain nominal glyph indices from.
/// The number of elements in the codePoints array.
/// Array of nominal glyph indices filled by this function.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetGlyphIndices)(
__in_ecount(codePointCount) UINT32 const* codePoints,
UINT32 codePointCount,
__out_ecount(codePointCount) UINT16* glyphIndices
) PURE;
///
/// Finds the specified OpenType font table if it exists and returns a pointer to it.
/// The function accesses the underling font data via the IDWriteFontStream interface
/// implemented by the font file loader.
///
/// 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.
///
/// 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).
///
/// Byte size of table.
///
/// 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.
///
/// True if table exists.
///
/// Standard HRESULT error code.
/// 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.
///
STDMETHOD(TryGetFontTable)(
__in UINT32 openTypeTableTag,
__deref_out_bcount(*tableSize) const void** tableData,
__out UINT32* tableSize,
__out void** tableContext,
__out BOOL* exists
) PURE;
///
/// Releases the table obtained earlier from TryGetFontTable.
///
/// Opaque context from TryGetFontTable.
///
/// Standard HRESULT error code.
///
STDMETHOD_(void, ReleaseFontTable)(
__in void* tableContext
) PURE;
///
/// Computes the outline of a run of glyphs by calling back to the outline sink interface.
///
/// Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
/// Array of glyph indices.
/// Optional array of glyph advances in DIPs.
/// Optional array of glyph offsets.
/// Number of glyphs.
/// 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. The isSideways and isRightToLeft parameters cannot both be true.
/// If true, specifies that the advance direction is right to left. By default, the advance direction
/// is left to right.
/// Interface the function calls back to draw each element of the geometry.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetGlyphRunOutline)(
FLOAT emSize,
__in_ecount(glyphCount) UINT16 const* glyphIndices,
__in_ecount_opt(glyphCount) FLOAT const* glyphAdvances,
__in_ecount_opt(glyphCount) DWRITE_GLYPH_OFFSET const* glyphOffsets,
UINT32 glyphCount,
BOOL isSideways,
BOOL isRightToLeft,
IDWriteGeometrySink* geometrySink
) PURE;
///
/// Determines the recommended rendering mode for the font given the specified size and rendering parameters.
///
/// Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
/// 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.
/// Specifies measuring method that will be used for glyphs in the font.
/// Renderer implementations may choose different rendering modes for given measuring methods, 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
///
/// Rendering parameters object. This parameter is necessary in case the rendering parameters
/// object overrides the rendering mode.
/// Receives the recommended rendering mode to use.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetRecommendedRenderingMode)(
FLOAT emSize,
FLOAT pixelsPerDip,
DWRITE_MEASURING_MODE measuringMode,
IDWriteRenderingParams* renderingParams,
__out DWRITE_RENDERING_MODE* renderingMode
) PURE;
///
/// 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.
///
/// Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
/// 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.
/// Optional transform applied to the glyphs and their positions. This transform is applied after the
/// scaling specified by the font size and pixelsPerDip.
/// Points to a DWRITE_FONT_METRICS structure to fill in.
/// The metrics returned by this function are in font design units.
STDMETHOD(GetGdiCompatibleMetrics)(
FLOAT emSize,
FLOAT pixelsPerDip,
__in_opt DWRITE_MATRIX const* transform,
__out DWRITE_FONT_METRICS* fontFaceMetrics
) PURE;
///
/// 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.
///
/// Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
/// 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.
/// Optional transform applied to the glyphs and their positions. This transform is applied after the
/// scaling specified by the font size and pixelsPerDip.
///
/// 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.
///
/// An array of glyph indices to compute the metrics for.
/// The number of elements in the glyphIndices array.
/// Array of DWRITE_GLYPH_METRICS structures filled by this function.
/// The metrics returned by this function are in font design units.
/// 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.
///
/// Standard HRESULT error code. 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.
///
STDMETHOD(GetGdiCompatibleGlyphMetrics)(
FLOAT emSize,
FLOAT pixelsPerDip,
__in_opt DWRITE_MATRIX const* transform,
BOOL useGdiNatural,
__in_ecount(glyphCount) UINT16 const* glyphIndices,
UINT32 glyphCount,
__out_ecount(glyphCount) DWRITE_GLYPH_METRICS* glyphMetrics,
BOOL isSideways = FALSE
) PURE;
};
interface IDWriteFactory;
interface IDWriteFontFileEnumerator;
///
/// The font collection loader interface is used to construct a collection of fonts given a particular type of key.
/// The font collection loader interface is recommended to be implemented by a singleton object.
/// IMPORTANT: font collection loader implementations must not register themselves with a DirectWrite factory
/// inside their constructors and must not unregister themselves in their destructors, because
/// registration and unregistraton operations increment and decrement the object reference count respectively.
/// Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed
/// outside of the font file loader implementation as a separate step.
///
interface DWRITE_DECLARE_INTERFACE("cca920e4-52f0-492b-bfa8-29c72ee0a468") IDWriteFontCollectionLoader : public IUnknown
{
///
/// Creates a font file enumerator object that encapsulates a collection of font files.
/// The font system calls back to this interface to create a font collection.
///
/// Factory associated with the loader.
/// Font collection key that uniquely identifies the collection of font files within
/// the scope of the font collection loader being used.
/// Size of the font collection key in bytes.
/// Pointer to the newly created font file enumerator.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateEnumeratorFromKey)(
IDWriteFactory* factory,
__in_bcount(collectionKeySize) void const* collectionKey,
UINT32 collectionKeySize,
__out IDWriteFontFileEnumerator** fontFileEnumerator
) PURE;
};
///
/// The font file enumerator interface encapsulates a collection of font files. The font system uses this interface
/// to enumerate font files when building a font collection.
///
interface DWRITE_DECLARE_INTERFACE("72755049-5ff7-435d-8348-4be97cfa6c7c") IDWriteFontFileEnumerator : public IUnknown
{
///
/// Advances to the next font file in the collection. When it is first created, the enumerator is positioned
/// before the first element of the collection and the first call to MoveNext advances to the first file.
///
/// Receives the value TRUE if the enumerator advances to a file, or FALSE if
/// the enumerator advanced past the last file in the collection.
///
/// Standard HRESULT error code.
///
STDMETHOD(MoveNext)(
__out BOOL* hasCurrentFile
) PURE;
///
/// Gets a reference to the current font file.
///
/// Pointer to the newly created font file object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetCurrentFontFile)(
__out IDWriteFontFile** fontFile
) PURE;
};
///
/// Represents a collection of strings indexed by locale name.
///
interface DWRITE_DECLARE_INTERFACE("08256209-099a-4b34-b86d-c22b110e7771") IDWriteLocalizedStrings : public IUnknown
{
///
/// Gets the number of language/string pairs.
///
STDMETHOD_(UINT32, GetCount)() PURE;
///
/// Gets the index of the item with the specified locale name.
///
/// Locale name to look for.
/// Receives the zero-based index of the locale name/string pair.
/// Receives TRUE if the locale name exists or FALSE if not.
///
/// Standard HRESULT error code. If the specified locale name does not exist, the return value is S_OK,
/// but *index is UINT_MAX and *exists is FALSE.
///
STDMETHOD(FindLocaleName)(
__in_z WCHAR const* localeName,
__out UINT32* index,
__out BOOL* exists
) PURE;
///
/// Gets the length in characters (not including the null terminator) of the locale name with the specified index.
///
/// Zero-based index of the locale name.
/// Receives the length in characters, not including the null terminator.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLocaleNameLength)(
UINT32 index,
__out UINT32* length
) PURE;
///
/// Copies the locale name with the specified index to the specified array.
///
/// Zero-based index of the locale name.
/// Character array that receives the locale name.
/// Size of the array in characters. The size must include space for the terminating
/// null character.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLocaleName)(
UINT32 index,
__out_ecount_z(size) WCHAR* localeName,
UINT32 size
) PURE;
///
/// Gets the length in characters (not including the null terminator) of the string with the specified index.
///
/// Zero-based index of the string.
/// Receives the length in characters, not including the null terminator.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetStringLength)(
UINT32 index,
__out UINT32* length
) PURE;
///
/// Copies the string with the specified index to the specified array.
///
/// Zero-based index of the string.
/// Character array that receives the string.
/// Size of the array in characters. The size must include space for the terminating
/// null character.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetString)(
UINT32 index,
__out_ecount_z(size) WCHAR* stringBuffer,
UINT32 size
) PURE;
};
interface IDWriteFontFamily;
interface IDWriteFont;
///
/// The IDWriteFontCollection encapsulates a collection of fonts.
///
interface DWRITE_DECLARE_INTERFACE("a84cee02-3eea-4eee-a827-87c1a02a0fcc") IDWriteFontCollection : public IUnknown
{
///
/// Gets the number of font families in the collection.
///
STDMETHOD_(UINT32, GetFontFamilyCount)() PURE;
///
/// Creates a font family object given a zero-based font family index.
///
/// Zero-based index of the font family.
/// Receives a pointer the newly created font family object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontFamily)(
UINT32 index,
__out IDWriteFontFamily** fontFamily
) PURE;
///
/// Finds the font family with the specified family name.
///
/// Name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.
/// Receives the zero-based index of the matching font family if the family name was found or UINT_MAX otherwise.
/// Receives TRUE if the family name exists or FALSE otherwise.
///
/// Standard HRESULT error code. If the specified family name does not exist, the return value is S_OK, but *index is UINT_MAX and *exists is FALSE.
///
STDMETHOD(FindFamilyName)(
__in_z WCHAR const* familyName,
__out UINT32* index,
__out BOOL* exists
) PURE;
///
/// Gets the font object that corresponds to the same physical font as the specified font face object. The specified physical font must belong
/// to the font collection.
///
/// Font face object that specifies the physical font.
/// Receives a pointer to the newly created font object if successful or NULL otherwise.
///
/// Standard HRESULT error code. If the specified physical font is not part of the font collection the return value is DWRITE_E_NOFONT.
///
STDMETHOD(GetFontFromFontFace)(
IDWriteFontFace* fontFace,
__out IDWriteFont** font
) PURE;
};
///
/// The IDWriteFontList interface represents a list of fonts.
///
interface DWRITE_DECLARE_INTERFACE("1a0d8438-1d97-4ec1-aef9-a2fb86ed6acb") IDWriteFontList : public IUnknown
{
///
/// Gets the font collection that contains the fonts.
///
/// Receives a pointer to the font collection object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontCollection)(
__out IDWriteFontCollection** fontCollection
) PURE;
///
/// Gets the number of fonts in the font list.
///
STDMETHOD_(UINT32, GetFontCount)() PURE;
///
/// Gets a font given its zero-based index.
///
/// Zero-based index of the font in the font list.
/// Receives a pointer to the newly created font object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFont)(
UINT32 index,
__out IDWriteFont** font
) PURE;
};
///
/// The IDWriteFontFamily interface represents a set of fonts that share the same design but are differentiated
/// by weight, stretch, and style.
///
interface DWRITE_DECLARE_INTERFACE("da20d8ef-812a-4c43-9802-62ec4abd7add") IDWriteFontFamily : public IDWriteFontList
{
///
/// Creates an localized strings object that contains the family names for the font family, indexed by locale name.
///
/// Receives a pointer to the newly created localized strings object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFamilyNames)(
__out IDWriteLocalizedStrings** names
) PURE;
///
/// Gets the font that best matches the specified properties.
///
/// Requested font weight.
/// Requested font stretch.
/// Requested font style.
/// Receives a pointer to the newly created font object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFirstMatchingFont)(
DWRITE_FONT_WEIGHT weight,
DWRITE_FONT_STRETCH stretch,
DWRITE_FONT_STYLE style,
__out IDWriteFont** matchingFont
) PURE;
///
/// Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
///
/// Requested font weight.
/// Requested font stretch.
/// Requested font style.
/// Receives a pointer to the newly created font list object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetMatchingFonts)(
DWRITE_FONT_WEIGHT weight,
DWRITE_FONT_STRETCH stretch,
DWRITE_FONT_STYLE style,
__out IDWriteFontList** matchingFonts
) PURE;
};
///
/// The IDWriteFont interface represents a physical font in a font collection.
///
interface DWRITE_DECLARE_INTERFACE("acd16696-8c14-4f5d-877e-fe3fc1d32737") IDWriteFont : public IUnknown
{
///
/// Gets the font family to which the specified font belongs.
///
/// Receives a pointer to the font family object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontFamily)(
__out IDWriteFontFamily** fontFamily
) PURE;
///
/// Gets the weight of the specified font.
///
STDMETHOD_(DWRITE_FONT_WEIGHT, GetWeight)() PURE;
///
/// Gets the stretch (aka. width) of the specified font.
///
STDMETHOD_(DWRITE_FONT_STRETCH, GetStretch)() PURE;
///
/// Gets the style (aka. slope) of the specified font.
///
STDMETHOD_(DWRITE_FONT_STYLE, GetStyle)() PURE;
///
/// Returns TRUE if the font is a symbol font or FALSE if not.
///
STDMETHOD_(BOOL, IsSymbolFont)() PURE;
///
/// Gets a localized strings collection containing the face names for the font (e.g., Regular or Bold), indexed by locale name.
///
/// Receives a pointer to the newly created localized strings object.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFaceNames)(
__out IDWriteLocalizedStrings** names
) PURE;
///
/// Gets a localized strings collection containing the specified informational strings, indexed by locale name.
///
/// Identifies the string to get.
/// Receives a pointer to the newly created localized strings object.
/// Receives the value TRUE if the font contains the specified string ID or FALSE if not.
///
/// Standard HRESULT error code. If the font does not contain the specified string, the return value is S_OK but
/// informationalStrings receives a NULL pointer and exists receives the value FALSE.
///
STDMETHOD(GetInformationalStrings)(
DWRITE_INFORMATIONAL_STRING_ID informationalStringID,
__out IDWriteLocalizedStrings** informationalStrings,
__out BOOL* exists
) PURE;
///
/// Gets a value that indicates what simulation are applied to the specified font.
///
STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE;
///
/// Gets the metrics for the font.
///
/// Receives the font metrics.
STDMETHOD_(void, GetMetrics)(
__out DWRITE_FONT_METRICS* fontMetrics
) PURE;
///
/// Determines whether the font supports the specified character.
///
/// Unicode (UCS-4) character value.
/// Receives the value TRUE if the font supports the specified character or FALSE if not.
///
/// Standard HRESULT error code.
///
STDMETHOD(HasCharacter)(
UINT32 unicodeValue,
__out BOOL* exists
) PURE;
///
/// Creates a font face object for the font.
///
/// Receives a pointer to the newly created font face object.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateFontFace)(
__out IDWriteFontFace** fontFace
) PURE;
};
///
/// Direction for how reading progresses.
///
enum DWRITE_READING_DIRECTION
{
///
/// Reading progresses from left to right.
///
DWRITE_READING_DIRECTION_LEFT_TO_RIGHT,
///
/// Reading progresses from right to left.
///
DWRITE_READING_DIRECTION_RIGHT_TO_LEFT
};
///
/// Direction for how lines of text are placed relative to one another.
///
enum DWRITE_FLOW_DIRECTION
{
///
/// Text lines are placed from top to bottom.
///
DWRITE_FLOW_DIRECTION_TOP_TO_BOTTOM
};
///
/// Alignment of paragraph text along the reading direction axis relative to
/// the leading and trailing edge of the layout box.
///
enum DWRITE_TEXT_ALIGNMENT
{
///
/// The leading edge of the paragraph text is aligned to the layout box's leading edge.
///
DWRITE_TEXT_ALIGNMENT_LEADING,
///
/// The trailing edge of the paragraph text is aligned to the layout box's trailing edge.
///
DWRITE_TEXT_ALIGNMENT_TRAILING,
///
/// The center of the paragraph text is aligned to the center of the layout box.
///
DWRITE_TEXT_ALIGNMENT_CENTER
};
///
/// Alignment of paragraph text along the flow direction axis relative to the
/// flow's beginning and ending edge of the layout box.
///
enum DWRITE_PARAGRAPH_ALIGNMENT
{
///
/// The first line of paragraph is aligned to the flow's beginning edge of the layout box.
///
DWRITE_PARAGRAPH_ALIGNMENT_NEAR,
///
/// The last line of paragraph is aligned to the flow's ending edge of the layout box.
///
DWRITE_PARAGRAPH_ALIGNMENT_FAR,
///
/// The center of the paragraph is aligned to the center of the flow of the layout box.
///
DWRITE_PARAGRAPH_ALIGNMENT_CENTER
};
///
/// Word wrapping in multiline paragraph.
///
enum DWRITE_WORD_WRAPPING
{
///
/// Words are broken across lines to avoid text overflowing the layout box.
///
DWRITE_WORD_WRAPPING_WRAP,
///
/// Words are kept within the same line even when it overflows the layout box.
/// This option is often used with scrolling to reveal overflow text.
///
DWRITE_WORD_WRAPPING_NO_WRAP
};
///
/// The method used for line spacing in layout.
///
enum DWRITE_LINE_SPACING_METHOD
{
///
/// Line spacing depends solely on the content, growing to accomodate the size of fonts and inline objects.
///
DWRITE_LINE_SPACING_METHOD_DEFAULT,
///
/// Lines are explicitly set to uniform spacing, regardless of contained font sizes.
/// This can be useful to avoid the uneven appearance that can occur from font fallback.
///
DWRITE_LINE_SPACING_METHOD_UNIFORM
};
///
/// Text granularity used to trim text overflowing the layout box.
///
enum DWRITE_TRIMMING_GRANULARITY
{
///
/// No trimming occurs. Text flows beyond the layout width.
///
DWRITE_TRIMMING_GRANULARITY_NONE,
///
/// Trimming occurs at character cluster boundary.
///
DWRITE_TRIMMING_GRANULARITY_CHARACTER,
///
/// Trimming occurs at word boundary.
///
DWRITE_TRIMMING_GRANULARITY_WORD
};
///
/// Typographic feature of text supplied by the font.
///
enum DWRITE_FONT_FEATURE_TAG
{
DWRITE_FONT_FEATURE_TAG_ALTERNATIVE_FRACTIONS = 0x63726661, // 'afrc'
DWRITE_FONT_FEATURE_TAG_PETITE_CAPITALS_FROM_CAPITALS = 0x63703263, // 'c2pc'
DWRITE_FONT_FEATURE_TAG_SMALL_CAPITALS_FROM_CAPITALS = 0x63733263, // 'c2sc'
DWRITE_FONT_FEATURE_TAG_CONTEXTUAL_ALTERNATES = 0x746c6163, // 'calt'
DWRITE_FONT_FEATURE_TAG_CASE_SENSITIVE_FORMS = 0x65736163, // 'case'
DWRITE_FONT_FEATURE_TAG_GLYPH_COMPOSITION_DECOMPOSITION = 0x706d6363, // 'ccmp'
DWRITE_FONT_FEATURE_TAG_CONTEXTUAL_LIGATURES = 0x67696c63, // 'clig'
DWRITE_FONT_FEATURE_TAG_CAPITAL_SPACING = 0x70737063, // 'cpsp'
DWRITE_FONT_FEATURE_TAG_CONTEXTUAL_SWASH = 0x68777363, // 'cswh'
DWRITE_FONT_FEATURE_TAG_CURSIVE_POSITIONING = 0x73727563, // 'curs'
DWRITE_FONT_FEATURE_TAG_DEFAULT = 0x746c6664, // 'dflt'
DWRITE_FONT_FEATURE_TAG_DISCRETIONARY_LIGATURES = 0x67696c64, // 'dlig'
DWRITE_FONT_FEATURE_TAG_EXPERT_FORMS = 0x74707865, // 'expt'
DWRITE_FONT_FEATURE_TAG_FRACTIONS = 0x63617266, // 'frac'
DWRITE_FONT_FEATURE_TAG_FULL_WIDTH = 0x64697766, // 'fwid'
DWRITE_FONT_FEATURE_TAG_HALF_FORMS = 0x666c6168, // 'half'
DWRITE_FONT_FEATURE_TAG_HALANT_FORMS = 0x6e6c6168, // 'haln'
DWRITE_FONT_FEATURE_TAG_ALTERNATE_HALF_WIDTH = 0x746c6168, // 'halt'
DWRITE_FONT_FEATURE_TAG_HISTORICAL_FORMS = 0x74736968, // 'hist'
DWRITE_FONT_FEATURE_TAG_HORIZONTAL_KANA_ALTERNATES = 0x616e6b68, // 'hkna'
DWRITE_FONT_FEATURE_TAG_HISTORICAL_LIGATURES = 0x67696c68, // 'hlig'
DWRITE_FONT_FEATURE_TAG_HALF_WIDTH = 0x64697768, // 'hwid'
DWRITE_FONT_FEATURE_TAG_HOJO_KANJI_FORMS = 0x6f6a6f68, // 'hojo'
DWRITE_FONT_FEATURE_TAG_JIS04_FORMS = 0x3430706a, // 'jp04'
DWRITE_FONT_FEATURE_TAG_JIS78_FORMS = 0x3837706a, // 'jp78'
DWRITE_FONT_FEATURE_TAG_JIS83_FORMS = 0x3338706a, // 'jp83'
DWRITE_FONT_FEATURE_TAG_JIS90_FORMS = 0x3039706a, // 'jp90'
DWRITE_FONT_FEATURE_TAG_KERNING = 0x6e72656b, // 'kern'
DWRITE_FONT_FEATURE_TAG_STANDARD_LIGATURES = 0x6167696c, // 'liga'
DWRITE_FONT_FEATURE_TAG_LINING_FIGURES = 0x6d756e6c, // 'lnum'
DWRITE_FONT_FEATURE_TAG_LOCALIZED_FORMS = 0x6c636f6c, // 'locl'
DWRITE_FONT_FEATURE_TAG_MARK_POSITIONING = 0x6b72616d, // 'mark'
DWRITE_FONT_FEATURE_TAG_MATHEMATICAL_GREEK = 0x6b72676d, // 'mgrk'
DWRITE_FONT_FEATURE_TAG_MARK_TO_MARK_POSITIONING = 0x6b6d6b6d, // 'mkmk'
DWRITE_FONT_FEATURE_TAG_ALTERNATE_ANNOTATION_FORMS = 0x746c616e, // 'nalt'
DWRITE_FONT_FEATURE_TAG_NLC_KANJI_FORMS = 0x6b636c6e, // 'nlck'
DWRITE_FONT_FEATURE_TAG_OLD_STYLE_FIGURES = 0x6d756e6f, // 'onum'
DWRITE_FONT_FEATURE_TAG_ORDINALS = 0x6e64726f, // 'ordn'
DWRITE_FONT_FEATURE_TAG_PROPORTIONAL_ALTERNATE_WIDTH = 0x746c6170, // 'palt'
DWRITE_FONT_FEATURE_TAG_PETITE_CAPITALS = 0x70616370, // 'pcap'
DWRITE_FONT_FEATURE_TAG_PROPORTIONAL_FIGURES = 0x6d756e70, // 'pnum'
DWRITE_FONT_FEATURE_TAG_PROPORTIONAL_WIDTHS = 0x64697770, // 'pwid'
DWRITE_FONT_FEATURE_TAG_QUARTER_WIDTHS = 0x64697771, // 'qwid'
DWRITE_FONT_FEATURE_TAG_REQUIRED_LIGATURES = 0x67696c72, // 'rlig'
DWRITE_FONT_FEATURE_TAG_RUBY_NOTATION_FORMS = 0x79627572, // 'ruby'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_ALTERNATES = 0x746c6173, // 'salt'
DWRITE_FONT_FEATURE_TAG_SCIENTIFIC_INFERIORS = 0x666e6973, // 'sinf'
DWRITE_FONT_FEATURE_TAG_SMALL_CAPITALS = 0x70636d73, // 'smcp'
DWRITE_FONT_FEATURE_TAG_SIMPLIFIED_FORMS = 0x6c706d73, // 'smpl'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_1 = 0x31307373, // 'ss01'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_2 = 0x32307373, // 'ss02'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_3 = 0x33307373, // 'ss03'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_4 = 0x34307373, // 'ss04'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_5 = 0x35307373, // 'ss05'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_6 = 0x36307373, // 'ss06'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_7 = 0x37307373, // 'ss07'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_8 = 0x38307373, // 'ss08'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_9 = 0x39307373, // 'ss09'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_10 = 0x30317373, // 'ss10'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_11 = 0x31317373, // 'ss11'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_12 = 0x32317373, // 'ss12'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_13 = 0x33317373, // 'ss13'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_14 = 0x34317373, // 'ss14'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_15 = 0x35317373, // 'ss15'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_16 = 0x36317373, // 'ss16'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_17 = 0x37317373, // 'ss17'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_18 = 0x38317373, // 'ss18'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_19 = 0x39317373, // 'ss19'
DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_20 = 0x30327373, // 'ss20'
DWRITE_FONT_FEATURE_TAG_SUBSCRIPT = 0x73627573, // 'subs'
DWRITE_FONT_FEATURE_TAG_SUPERSCRIPT = 0x73707573, // 'sups'
DWRITE_FONT_FEATURE_TAG_SWASH = 0x68737773, // 'swsh'
DWRITE_FONT_FEATURE_TAG_TITLING = 0x6c746974, // 'titl'
DWRITE_FONT_FEATURE_TAG_TRADITIONAL_NAME_FORMS = 0x6d616e74, // 'tnam'
DWRITE_FONT_FEATURE_TAG_TABULAR_FIGURES = 0x6d756e74, // 'tnum'
DWRITE_FONT_FEATURE_TAG_TRADITIONAL_FORMS = 0x64617274, // 'trad'
DWRITE_FONT_FEATURE_TAG_THIRD_WIDTHS = 0x64697774, // 'twid'
DWRITE_FONT_FEATURE_TAG_UNICASE = 0x63696e75, // 'unic'
DWRITE_FONT_FEATURE_TAG_SLASHED_ZERO = 0x6f72657a, // 'zero'
};
///
/// The DWRITE_TEXT_RANGE structure specifies a range of text positions where format is applied.
///
struct DWRITE_TEXT_RANGE
{
///
/// The start text position of the range.
///
UINT32 startPosition;
///
/// The number of text positions in the range.
///
UINT32 length;
};
///
/// The DWRITE_FONT_FEATURE structure specifies properties used to identify and execute typographic feature in the font.
///
struct DWRITE_FONT_FEATURE
{
///
/// The feature OpenType name identifier.
///
DWRITE_FONT_FEATURE_TAG nameTag;
///
/// Execution parameter of the feature.
///
///
/// The parameter should be non-zero to enable the feature. Once enabled, a feature can't be disabled again within
/// the same range. Features requiring a selector use this value to indicate the selector index.
///
UINT32 parameter;
};
///
/// Defines a set of typographic features to be applied during shaping.
/// Notice the character range which this feature list spans is specified
/// as a separate parameter to GetGlyphs.
///
struct DWRITE_TYPOGRAPHIC_FEATURES
{
///
/// Array of font features.
///
__field_ecount(featureCount) DWRITE_FONT_FEATURE* features;
///
/// The number of features.
///
UINT32 featureCount;
};
///
/// The DWRITE_TRIMMING structure specifies the trimming option for text overflowing the layout box.
///
struct DWRITE_TRIMMING
{
///
/// Text granularity of which trimming applies.
///
DWRITE_TRIMMING_GRANULARITY granularity;
///
/// Character code used as the delimiter signaling the beginning of the portion of text to be preserved,
/// most useful for path ellipsis, where the delimeter would be a slash.
///
UINT32 delimiter;
///
/// How many occurences of the delimiter to step back.
///
UINT32 delimiterCount;
};
interface IDWriteTypography;
interface IDWriteInlineObject;
///
/// The format of text used for text layout purpose.
///
///
/// This object may not be thread-safe and it may carry the state of text format change.
///
interface DWRITE_DECLARE_INTERFACE("9c906818-31d7-4fd3-a151-7c5e225db55a") IDWriteTextFormat : public IUnknown
{
///
/// Set alignment option of text relative to layout box's leading and trailing edge.
///
/// Text alignment option
///
/// Standard HRESULT error code.
///
STDMETHOD(SetTextAlignment)(
DWRITE_TEXT_ALIGNMENT textAlignment
) PURE;
///
/// Set alignment option of paragraph relative to layout box's top and bottom edge.
///
/// Paragraph alignment option
///
/// Standard HRESULT error code.
///
STDMETHOD(SetParagraphAlignment)(
DWRITE_PARAGRAPH_ALIGNMENT paragraphAlignment
) PURE;
///
/// Set word wrapping option.
///
/// Word wrapping option
///
/// Standard HRESULT error code.
///
STDMETHOD(SetWordWrapping)(
DWRITE_WORD_WRAPPING wordWrapping
) PURE;
///
/// Set paragraph reading direction.
///
/// Text reading direction
///
/// Standard HRESULT error code.
///
STDMETHOD(SetReadingDirection)(
DWRITE_READING_DIRECTION readingDirection
) PURE;
///
/// Set paragraph flow direction.
///
/// Paragraph flow direction
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFlowDirection)(
DWRITE_FLOW_DIRECTION flowDirection
) PURE;
///
/// Set incremental tab stop position.
///
/// The incremental tab stop value
///
/// Standard HRESULT error code.
///
STDMETHOD(SetIncrementalTabStop)(
FLOAT incrementalTabStop
) PURE;
///
/// Set trimming options for any trailing text exceeding the layout width
/// or for any far text exceeding the layout height.
///
/// Text trimming options.
/// Application-defined omission sign. This parameter may be NULL if no trimming sign is desired.
///
/// Any inline object can be used for the trimming sign, but CreateEllipsisTrimmingSign
/// provides a typical ellipsis symbol. Trimming is also useful vertically for hiding
/// partial lines.
///
///
/// Standard HRESULT error code.
///
STDMETHOD(SetTrimming)(
__in DWRITE_TRIMMING const* trimmingOptions,
IDWriteInlineObject* trimmingSign
) PURE;
///
/// Set line spacing.
///
/// How to determine line height.
/// The line height, or rather distance between one baseline to another.
/// Distance from top of line to baseline. A reasonable ratio to lineSpacing is 80%.
///
/// For the default method, spacing depends solely on the content.
/// For uniform spacing, the given line height will override the content.
///
///
/// Standard HRESULT error code.
///
STDMETHOD(SetLineSpacing)(
DWRITE_LINE_SPACING_METHOD lineSpacingMethod,
FLOAT lineSpacing,
FLOAT baseline
) PURE;
///
/// Get alignment option of text relative to layout box's leading and trailing edge.
///
STDMETHOD_(DWRITE_TEXT_ALIGNMENT, GetTextAlignment)() PURE;
///
/// Get alignment option of paragraph relative to layout box's top and bottom edge.
///
STDMETHOD_(DWRITE_PARAGRAPH_ALIGNMENT, GetParagraphAlignment)() PURE;
///
/// Get word wrapping option.
///
STDMETHOD_(DWRITE_WORD_WRAPPING, GetWordWrapping)() PURE;
///
/// Get paragraph reading direction.
///
STDMETHOD_(DWRITE_READING_DIRECTION, GetReadingDirection)() PURE;
///
/// Get paragraph flow direction.
///
STDMETHOD_(DWRITE_FLOW_DIRECTION, GetFlowDirection)() PURE;
///
/// Get incremental tab stop position.
///
STDMETHOD_(FLOAT, GetIncrementalTabStop)() PURE;
///
/// Get trimming options for text overflowing the layout width.
///
/// Text trimming options.
/// Trimming omission sign. This parameter may be NULL.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetTrimming)(
__out DWRITE_TRIMMING* trimmingOptions,
__out IDWriteInlineObject** trimmingSign
) PURE;
///
/// Get line spacing.
///
/// How line height is determined.
/// The line height, or rather distance between one baseline to another.
/// Distance from top of line to baseline.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLineSpacing)(
__out DWRITE_LINE_SPACING_METHOD* lineSpacingMethod,
__out FLOAT* lineSpacing,
__out FLOAT* baseline
) PURE;
///
/// Get the font collection.
///
/// The current font collection.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontCollection)(
__out IDWriteFontCollection** fontCollection
) PURE;
///
/// Get the length of the font family name, in characters, not including the terminating NULL character.
///
STDMETHOD_(UINT32, GetFontFamilyNameLength)() PURE;
///
/// Get a copy of the font family name.
///
/// Character array that receives the current font family name
/// Size of the character array in character count including the terminated NULL character.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontFamilyName)(
__out_ecount_z(nameSize) WCHAR* fontFamilyName,
UINT32 nameSize
) PURE;
///
/// Get the font weight.
///
STDMETHOD_(DWRITE_FONT_WEIGHT, GetFontWeight)() PURE;
///
/// Get the font style.
///
STDMETHOD_(DWRITE_FONT_STYLE, GetFontStyle)() PURE;
///
/// Get the font stretch.
///
STDMETHOD_(DWRITE_FONT_STRETCH, GetFontStretch)() PURE;
///
/// Get the font em height.
///
STDMETHOD_(FLOAT, GetFontSize)() PURE;
///
/// Get the length of the locale name, in characters, not including the terminating NULL character.
///
STDMETHOD_(UINT32, GetLocaleNameLength)() PURE;
///
/// Get a copy of the locale name.
///
/// Character array that receives the current locale name
/// Size of the character array in character count including the terminated NULL character.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLocaleName)(
__out_ecount_z(nameSize) WCHAR* localeName,
UINT32 nameSize
) PURE;
};
///
/// Font typography setting.
///
interface DWRITE_DECLARE_INTERFACE("55f1112b-1dc2-4b3c-9541-f46894ed85b6") IDWriteTypography : public IUnknown
{
///
/// Add font feature.
///
/// The font feature to add.
///
/// Standard HRESULT error code.
///
STDMETHOD(AddFontFeature)(
DWRITE_FONT_FEATURE fontFeature
) PURE;
///
/// Get the number of font features.
///
STDMETHOD_(UINT32, GetFontFeatureCount)() PURE;
///
/// Get the font feature at the specified index.
///
/// The zero-based index of the font feature to get.
/// The font feature.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontFeature)(
UINT32 fontFeatureIndex,
__out DWRITE_FONT_FEATURE* fontFeature
) PURE;
};
enum DWRITE_SCRIPT_SHAPES
{
///
/// No additional shaping requirement. Text is shaped with the writing system default behavior.
///
DWRITE_SCRIPT_SHAPES_DEFAULT = 0,
///
/// Text should leave no visual on display i.e. control or format control characters.
///
DWRITE_SCRIPT_SHAPES_NO_VISUAL = 1
};
#ifdef DEFINE_ENUM_FLAG_OPERATORS
DEFINE_ENUM_FLAG_OPERATORS(DWRITE_SCRIPT_SHAPES);
#endif
///
/// Association of text and its writing system script as well as some display attributes.
///
struct DWRITE_SCRIPT_ANALYSIS
{
///
/// Zero-based index representation of writing system script.
///
UINT16 script;
///
/// Additional shaping requirement of text.
///
DWRITE_SCRIPT_SHAPES shapes;
};
///
/// Condition at the edges of inline object or text used to determine
/// line-breaking behavior.
///
enum DWRITE_BREAK_CONDITION
{
///
/// Whether a break is allowed is determined by the condition of the
/// neighboring text span or inline object.
///
DWRITE_BREAK_CONDITION_NEUTRAL,
///
/// A break is allowed, unless overruled by the condition of the
/// neighboring text span or inline object, either prohibited by a
/// May Not or forced by a Must.
///
DWRITE_BREAK_CONDITION_CAN_BREAK,
///
/// There should be no break, unless overruled by a Must condition from
/// the neighboring text span or inline object.
///
DWRITE_BREAK_CONDITION_MAY_NOT_BREAK,
///
/// The break must happen, regardless of the condition of the adjacent
/// text span or inline object.
///
DWRITE_BREAK_CONDITION_MUST_BREAK
};
///
/// Line breakpoint characteristics of a character.
///
struct DWRITE_LINE_BREAKPOINT
{
///
/// Breaking condition before the character.
///
UINT8 breakConditionBefore : 2;
///
/// Breaking condition after the character.
///
UINT8 breakConditionAfter : 2;
///
/// The character is some form of whitespace, which may be meaningful
/// for justification.
///
UINT8 isWhitespace : 1;
///
/// The character is a soft hyphen, often used to indicate hyphenation
/// points inside words.
///
UINT8 isSoftHyphen : 1;
UINT8 padding : 2;
};
///
/// How to apply number substitution on digits and related punctuation.
///
enum DWRITE_NUMBER_SUBSTITUTION_METHOD
{
///
/// Specifies that the substitution method should be determined based
/// on LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
///
DWRITE_NUMBER_SUBSTITUTION_METHOD_FROM_CULTURE,
///
/// If the culture is Arabic or Farsi, specifies that the number shape
/// depend on the context. Either traditional or nominal number shape
/// are used depending on the nearest preceding strong character or (if
/// there is none) the reading direction of the paragraph.
///
DWRITE_NUMBER_SUBSTITUTION_METHOD_CONTEXTUAL,
///
/// Specifies that code points 0x30-0x39 are always rendered as nominal numeral
/// shapes (ones of the European number), i.e., no substitution is performed.
///
DWRITE_NUMBER_SUBSTITUTION_METHOD_NONE,
///
/// Specifies that number are rendered using the national number shape
/// as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
///
DWRITE_NUMBER_SUBSTITUTION_METHOD_NATIONAL,
///
/// Specifies that number are rendered using the traditional shape
/// for the specified culture. For most cultures, this is the same as
/// NativeNational. However, NativeNational results in Latin number
/// for some Arabic cultures, whereas this value results in Arabic
/// number for all Arabic cultures.
///
DWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL
};
///
/// Holds the appropriate digits and numeric punctuation for a given locale.
///
interface DECLSPEC_UUID("14885CC9-BAB0-4f90-B6ED-5C366A2CD03D") DECLSPEC_NOVTABLE IDWriteNumberSubstitution : public IUnknown
{
};
///
/// Shaping output properties per input character.
///
struct DWRITE_SHAPING_TEXT_PROPERTIES
{
///
/// This character can be shaped independently from the others
/// (usually set for the space character).
///
UINT16 isShapedAlone : 1;
///
/// Reserved for use by shaping engine.
///
UINT16 reserved : 15;
};
///
/// Shaping output properties per output glyph.
///
struct DWRITE_SHAPING_GLYPH_PROPERTIES
{
///
/// Justification class, whether to use spacing, kashidas, or
/// another method. This exists for backwards compatibility
/// with Uniscribe's SCRIPT_JUSTIFY enum.
///
UINT16 justification : 4;
///
/// Indicates glyph is the first of a cluster.
///
UINT16 isClusterStart : 1;
///
/// Glyph is a diacritic.
///
UINT16 isDiacritic : 1;
///
/// Glyph has no width, blank, ZWJ, ZWNJ etc.
///
UINT16 isZeroWidthSpace : 1;
///
/// Reserved for use by shaping engine.
///
UINT16 reserved : 9;
};
///
/// The interface implemented by the text analyzer's client to provide text to
/// the analyzer. It allows the separation between the logical view of text as
/// a continuous stream of characters identifiable by unique text positions,
/// and the actual memory layout of potentially discrete blocks of text in the
/// client's backing store.
///
/// If any of these callbacks returns an error, the analysis functions will
/// stop prematurely and return a callback error. Rather than return E_NOTIMPL,
/// an application should stub the method and return a constant/null and S_OK.
///
interface DECLSPEC_UUID("688e1a58-5094-47c8-adc8-fbcea60ae92b") DECLSPEC_NOVTABLE IDWriteTextAnalysisSource : public IUnknown
{
///
/// Get a block of text starting at the specified text position.
/// Returning NULL indicates the end of text - the position is after
/// the last character. This function is called iteratively for
/// each consecutive block, tying together several fragmented blocks
/// in the backing store into a virtual contiguous string.
///
/// First position of the piece to obtain. All
/// positions are in UTF16 code-units, not whole characters, which
/// matters when supplementary characters are used.
/// Address that receives a pointer to the text block
/// at the specified position.
/// Number of UTF16 units of the retrieved chunk.
/// The returned length is not the length of the block, but the length
/// remaining in the block, from the given position until its end.
/// So querying for a position that is 75 positions into a 100
/// postition block would return 25.
/// Pointer to the first character at the given text position.
/// NULL indicates no chunk available at the specified position, either
/// because textPosition >= the entire text content length or because the
/// queried position is not mapped into the app's backing store.
///
/// Although apps can implement sparse textual content that only maps part of
/// the backing store, the app must map any text that is in the range passed
/// to any analysis functions.
///
STDMETHOD(GetTextAtPosition)(
UINT32 textPosition,
__out WCHAR const** textString,
__out UINT32* textLength
) PURE;
///
/// Get a block of text immediately preceding the specified position.
///
/// Position immediately after the last position of the chunk to obtain.
/// Address that receives a pointer to the text block
/// at the specified position.
/// Number of UTF16 units of the retrieved block.
/// The length returned is from the given position to the front of
/// the block.
/// Pointer to the first character at (textPosition - textLength).
/// NULL indicates no chunk available at the specified position, either
/// because textPosition == 0,the textPosition > the entire text content
/// length, or the queried position is not mapped into the app's backing
/// store.
///
/// Although apps can implement sparse textual content that only maps part of
/// the backing store, the app must map any text that is in the range passed
/// to any analysis functions.
///
STDMETHOD(GetTextBeforePosition)(
UINT32 textPosition,
__out WCHAR const** textString,
__out UINT32* textLength
) PURE;
///
/// Get paragraph reading direction.
///
STDMETHOD_(DWRITE_READING_DIRECTION, GetParagraphReadingDirection)() PURE;
///
/// Get locale name on the range affected by it.
///
/// Position to get the locale name of.
/// Receives the length from the given position up to the
/// next differing locale.
/// Address that receives a pointer to the locale
/// at the specified position.
///
/// The localeName pointer must remain valid until the next call or until
/// the analysis returns.
///
STDMETHOD(GetLocaleName)(
UINT32 textPosition,
__out UINT32* textLength,
__out_z WCHAR const** localeName
) PURE;
///
/// Get number substitution on the range affected by it.
///
/// Position to get the number substitution of.
/// Receives the length from the given position up to the
/// next differing number substitution.
/// Address that receives a pointer to the number substitution
/// at the specified position.
///
/// Any implementation should return the number substitution with an
/// incremented ref count, and the analysis will release when finished
/// with it (either before the next call or before it returns). However,
/// the sink callback may hold onto it after that.
///
STDMETHOD(GetNumberSubstitution)(
UINT32 textPosition,
__out UINT32* textLength,
__out IDWriteNumberSubstitution** numberSubstitution
) PURE;
};
///
/// The interface implemented by the text analyzer's client to receive the
/// output of a given text analysis. The Text analyzer disregards any current
/// state of the analysis sink, therefore a Set method call on a range
/// overwrites the previously set analysis result of the same range.
///
interface DECLSPEC_UUID("5810cd44-0ca0-4701-b3fa-bec5182ae4f6") DECLSPEC_NOVTABLE IDWriteTextAnalysisSink : public IUnknown
{
///
/// Report script analysis for the text range.
///
/// Starting position to report from.
/// Number of UTF16 units of the reported range.
/// Script analysis of characters in range.
///
/// A successful code or error code to abort analysis.
///
STDMETHOD(SetScriptAnalysis)(
UINT32 textPosition,
UINT32 textLength,
__in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis
) PURE;
///
/// Repport line-break opportunities for each character, starting from
/// the specified position.
///
/// Starting position to report from.
/// Number of UTF16 units of the reported range.
/// Breaking conditions for each character.
///
/// A successful code or error code to abort analysis.
///
STDMETHOD(SetLineBreakpoints)(
UINT32 textPosition,
UINT32 textLength,
__in_ecount(textLength) DWRITE_LINE_BREAKPOINT const* lineBreakpoints
) PURE;
///
/// Set bidirectional level on the range, called once per each
/// level run change (either explicit or resolved implicit).
///
/// Starting position to report from.
/// Number of UTF16 units of the reported range.
/// Explicit level from embedded control codes
/// RLE/RLO/LRE/LRO/PDF, determined before any additional rules.
/// Final implicit level considering the
/// explicit level and characters' natural directionality, after all
/// Bidi rules have been applied.
///
/// A successful code or error code to abort analysis.
///
STDMETHOD(SetBidiLevel)(
UINT32 textPosition,
UINT32 textLength,
UINT8 explicitLevel,
UINT8 resolvedLevel
) PURE;
///
/// Set number substitution on the range.
///
/// Starting position to report from.
/// Number of UTF16 units of the reported range.
/// The number substitution applicable to
/// the returned range of text. The sink callback may hold onto it by
/// incrementing its ref count.
///
/// A successful code or error code to abort analysis.
///
///
/// Unlike script and bidi analysis, where every character passed to the
/// analyzer has a result, this will only be called for those ranges where
/// substitution is applicable. For any other range, you will simply not
/// be called.
///
STDMETHOD(SetNumberSubstitution)(
UINT32 textPosition,
UINT32 textLength,
__notnull IDWriteNumberSubstitution* numberSubstitution
) PURE;
};
///
/// Analyzes various text properties for complex script processing.
///
interface DWRITE_DECLARE_INTERFACE("b7e6163e-7f46-43b4-84b3-e4e6249c365d") IDWriteTextAnalyzer : public IUnknown
{
///
/// Analyzes a text range for script boundaries, reading text attributes
/// from the source and reporting the Unicode script ID to the sink
/// callback SetScript.
///
/// Source object to analyze.
/// Starting position within the source object.
/// Length to analyze.
/// Callback object.
///
/// Standard HRESULT error code.
///
STDMETHOD(AnalyzeScript)(
IDWriteTextAnalysisSource* analysisSource,
UINT32 textPosition,
UINT32 textLength,
IDWriteTextAnalysisSink* analysisSink
) PURE;
///
/// Analyzes a text range for script directionality, reading attributes
/// from the source and reporting levels to the sink callback SetBidiLevel.
///
/// Source object to analyze.
/// Starting position within the source object.
/// Length to analyze.
/// Callback object.
///
/// Standard HRESULT error code.
///
///
/// While the function can handle multiple paragraphs, the text range
/// should not arbitrarily split the middle of paragraphs. Otherwise the
/// returned levels may be wrong, since the Bidi algorithm is meant to
/// apply to the paragraph as a whole.
///
///
/// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account.
///
STDMETHOD(AnalyzeBidi)(
IDWriteTextAnalysisSource* analysisSource,
UINT32 textPosition,
UINT32 textLength,
IDWriteTextAnalysisSink* analysisSink
) PURE;
///
/// Analyzes a text range for spans where number substitution is applicable,
/// reading attributes from the source and reporting substitutable ranges
/// to the sink callback SetNumberSubstitution.
///
/// Source object to analyze.
/// Starting position within the source object.
/// Length to analyze.
/// Callback object.
///
/// Standard HRESULT error code.
///
///
/// While the function can handle multiple ranges of differing number
/// substitutions, the text ranges should not arbitrarily split the
/// middle of numbers. Otherwise it will treat the numbers separately
/// and will not translate any intervening punctuation.
///
///
/// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account.
///
STDMETHOD(AnalyzeNumberSubstitution)(
IDWriteTextAnalysisSource* analysisSource,
UINT32 textPosition,
UINT32 textLength,
IDWriteTextAnalysisSink* analysisSink
) PURE;
///
/// Analyzes a text range for potential breakpoint opportunities, reading
/// attributes from the source and reporting breakpoint opportunities to
/// the sink callback SetLineBreakpoints.
///
/// Source object to analyze.
/// Starting position within the source object.
/// Length to analyze.
/// Callback object.
///
/// Standard HRESULT error code.
///
///
/// While the function can handle multiple paragraphs, the text range
/// should not arbitrarily split the middle of paragraphs, unless the
/// given text span is considered a whole unit. Otherwise the
/// returned properties for the first and last characters will
/// inappropriately allow breaks.
///
///
/// Special cases include the first, last, and surrogate characters. Any
/// text span is treated as if adjacent to inline objects on either side.
/// So the rules with contingent-break opportunities are used, where the
/// edge between text and inline objects is always treated as a potential
/// break opportunity, dependent on any overriding rules of the adjacent
/// objects to prohibit or force the break (see Unicode TR #14).
/// Surrogate pairs never break between.
///
STDMETHOD(AnalyzeLineBreakpoints)(
IDWriteTextAnalysisSource* analysisSource,
UINT32 textPosition,
UINT32 textLength,
IDWriteTextAnalysisSink* analysisSink
) PURE;
///
/// Parses the input text string and maps it to the set of glyphs and associated glyph data
/// according to the font and the writing system's rendering rules.
///
/// The string to convert to glyphs.
/// The length of textString.
/// The font face to get glyphs from.
/// Set to true if the text is intended to be
/// drawn vertically.
/// Set to TRUE for right-to-left text.
/// Script analysis result from AnalyzeScript.
/// The locale to use when selecting glyphs.
/// e.g. the same character may map to different glyphs for ja-jp vs zh-chs.
/// If this is NULL then the default mapping based on the script is used.
/// Optional number substitution which
/// selects the appropriate glyphs for digits and related numeric characters,
/// depending on the results obtained from AnalyzeNumberSubstitution. Passing
/// null indicates that no substitution is needed and that the digits should
/// receive nominal glyphs.
/// An array of pointers to the sets of typographic
/// features to use in each feature range.
/// The length of each feature range, in characters.
/// The sum of all lengths should be equal to textLength.
/// The number of feature ranges.
/// The maximum number of glyphs that can be
/// returned.
/// The mapping from character ranges to glyph
/// ranges.
/// Per-character output properties.
/// Output glyph indices.
/// Per-glyph output properties.
/// The actual number of glyphs returned if
/// the call succeeds.
///
/// Standard HRESULT error code.
///
///
/// Note that the mapping from characters to glyphs is, in general, many-
/// to-many. The recommended estimate for the per-glyph output buffers is
/// (3 * textLength / 2 + 16). This is not guaranteed to be sufficient.
///
/// The value of the actualGlyphCount parameter is only valid if the call
/// succeeds. In the event that maxGlyphCount is not big enough
/// E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER),
/// will be returned. The application should allocate a larger buffer and try again.
///
STDMETHOD(GetGlyphs)(
__in_ecount(textLength) WCHAR const* textString,
UINT32 textLength,
IDWriteFontFace* fontFace,
BOOL isSideways,
BOOL isRightToLeft,
__in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis,
__in_z_opt WCHAR const* localeName,
__maybenull IDWriteNumberSubstitution* numberSubstitution,
__in_ecount_opt(featureRanges) DWRITE_TYPOGRAPHIC_FEATURES const** features,
__in_ecount_opt(featureRanges) UINT32 const* featureRangeLengths,
UINT32 featureRanges,
UINT32 maxGlyphCount,
__out_ecount(textLength) UINT16* clusterMap,
__out_ecount(textLength) DWRITE_SHAPING_TEXT_PROPERTIES* textProps,
__out_ecount(maxGlyphCount) UINT16* glyphIndices,
__out_ecount(maxGlyphCount) DWRITE_SHAPING_GLYPH_PROPERTIES* glyphProps,
__out UINT32* actualGlyphCount
) PURE;
///
/// Place glyphs output from the GetGlyphs method according to the font
/// and the writing system's rendering rules.
///
/// The original string the glyphs came from.
/// The mapping from character ranges to glyph
/// ranges. Returned by GetGlyphs.
/// Per-character properties. Returned by
/// GetGlyphs.
/// The length of textString.
/// Glyph indices. See GetGlyphs
/// Per-glyph properties. See GetGlyphs
/// The number of glyphs.
/// The font face the glyphs came from.
/// Logical font size in DIP's.
/// Set to true if the text is intended to be
/// drawn vertically.
/// Set to TRUE for right-to-left text.
/// Script analysis result from AnalyzeScript.
/// The locale to use when selecting glyphs.
/// e.g. the same character may map to different glyphs for ja-jp vs zh-chs.
/// If this is NULL then the default mapping based on the script is used.
/// An array of pointers to the sets of typographic
/// features to use in each feature range.
/// The length of each feature range, in characters.
/// The sum of all lengths should be equal to textLength.
/// The number of feature ranges.
/// The advance width of each glyph.
/// The offset of the origin of each glyph.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetGlyphPlacements)(
__in_ecount(textLength) WCHAR const* textString,
__in_ecount(textLength) UINT16 const* clusterMap,
__in_ecount(textLength) DWRITE_SHAPING_TEXT_PROPERTIES* textProps,
UINT32 textLength,
__in_ecount(glyphCount) UINT16 const* glyphIndices,
__in_ecount(glyphCount) DWRITE_SHAPING_GLYPH_PROPERTIES const* glyphProps,
UINT32 glyphCount,
IDWriteFontFace * fontFace,
FLOAT fontEmSize,
BOOL isSideways,
BOOL isRightToLeft,
__in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis,
__in_z_opt WCHAR const* localeName,
__in_ecount_opt(featureRanges) DWRITE_TYPOGRAPHIC_FEATURES const** features,
__in_ecount_opt(featureRanges) UINT32 const* featureRangeLengths,
UINT32 featureRanges,
__out_ecount(glyphCount) FLOAT* glyphAdvances,
__out_ecount(glyphCount) DWRITE_GLYPH_OFFSET* glyphOffsets
) PURE;
///
/// Place glyphs output from the GetGlyphs method according to the font
/// and the writing system's rendering rules.
///
/// The original string the glyphs came from.
/// The mapping from character ranges to glyph
/// ranges. Returned by GetGlyphs.
/// Per-character properties. Returned by
/// GetGlyphs.
/// The length of textString.
/// Glyph indices. See GetGlyphs
/// Per-glyph properties. See GetGlyphs
/// The number of glyphs.
/// The font face the glyphs came from.
/// Logical font size in DIP's.
/// 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.
/// Optional transform applied to the glyphs and their positions. This transform is applied after the
/// scaling specified by the font size and pixelsPerDip.
///
/// 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.
///
/// Set to true if the text is intended to be
/// drawn vertically.
/// Set to TRUE for right-to-left text.
/// Script analysis result from AnalyzeScript.
/// The locale to use when selecting glyphs.
/// e.g. the same character may map to different glyphs for ja-jp vs zh-chs.
/// If this is NULL then the default mapping based on the script is used.
/// An array of pointers to the sets of typographic
/// features to use in each feature range.
/// The length of each feature range, in characters.
/// The sum of all lengths should be equal to textLength.
/// The number of feature ranges.
/// The advance width of each glyph.
/// The offset of the origin of each glyph.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetGdiCompatibleGlyphPlacements)(
__in_ecount(textLength) WCHAR const* textString,
__in_ecount(textLength) UINT16 const* clusterMap,
__in_ecount(textLength) DWRITE_SHAPING_TEXT_PROPERTIES* textProps,
UINT32 textLength,
__in_ecount(glyphCount) UINT16 const* glyphIndices,
__in_ecount(glyphCount) DWRITE_SHAPING_GLYPH_PROPERTIES const* glyphProps,
UINT32 glyphCount,
IDWriteFontFace * fontFace,
FLOAT fontEmSize,
FLOAT pixelsPerDip,
__in_opt DWRITE_MATRIX const* transform,
BOOL useGdiNatural,
BOOL isSideways,
BOOL isRightToLeft,
__in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis,
__in_z_opt WCHAR const* localeName,
__in_ecount_opt(featureRanges) DWRITE_TYPOGRAPHIC_FEATURES const** features,
__in_ecount_opt(featureRanges) UINT32 const* featureRangeLengths,
UINT32 featureRanges,
__out_ecount(glyphCount) FLOAT* glyphAdvances,
__out_ecount(glyphCount) DWRITE_GLYPH_OFFSET* glyphOffsets
) PURE;
};
///
/// The DWRITE_GLYPH_RUN structure contains the information needed by renderers
/// to draw glyph runs. All coordinates are in device independent pixels (DIPs).
///
struct DWRITE_GLYPH_RUN
{
///
/// The physical font face to draw with.
///
__notnull IDWriteFontFace* fontFace;
///
/// Logical size of the font in DIPs, not points (equals 1/96 inch).
///
FLOAT fontEmSize;
///
/// The number of glyphs.
///
UINT32 glyphCount;
///
/// The indices to render.
///
__field_ecount(glyphCount) UINT16 const* glyphIndices;
///
/// Glyph advance widths.
///
__field_ecount_opt(glyphCount) FLOAT const* glyphAdvances;
///
/// Glyph offsets.
///
__field_ecount_opt(glyphCount) DWRITE_GLYPH_OFFSET const* glyphOffsets;
///
/// If true, specifies that glyphs are rotated 90 degrees to the left and
/// vertical metrics are used. Vertical writing is achieved by specifying
/// isSideways = true and rotating the entire run 90 degrees to the right
/// via a rotate transform.
///
BOOL isSideways;
///
/// The implicit resolved bidi level of the run. Odd levels indicate
/// right-to-left languages like Hebrew and Arabic, while even levels
/// indicate left-to-right languages like English and Japanese (when
/// written horizontally). For right-to-left languages, the text origin
/// is on the right, and text should be drawn to the left.
///
UINT32 bidiLevel;
};
///
/// The DWRITE_GLYPH_RUN_DESCRIPTION structure contains additional properties
/// related to those in DWRITE_GLYPH_RUN.
///
struct DWRITE_GLYPH_RUN_DESCRIPTION
{
///
/// The locale name associated with this run.
///
__nullterminated WCHAR const* localeName;
///
/// The text associated with the glyphs.
///
__field_ecount(stringLength) WCHAR const* string;
///
/// The number of characters (UTF16 code-units).
/// Note that this may be different than the number of glyphs.
///
UINT32 stringLength;
///
/// An array of indices to the glyph indices array, of the first glyphs of
/// all the glyph clusters of the glyphs to render.
///
__field_ecount(stringLength) UINT16 const* clusterMap;
///
/// Corresponding text position in the original string
/// this glyph run came from.
///
UINT32 textPosition;
};
///
/// The DWRITE_UNDERLINE structure contains about the size and placement of
/// underlines. All coordinates are in device independent pixels (DIPs).
///
struct DWRITE_UNDERLINE
{
///
/// Width of the underline, measured parallel to the baseline.
///
FLOAT width;
///
/// Thickness of the underline, measured perpendicular to the
/// baseline.
///
FLOAT thickness;
///
/// Offset of the underline from the baseline.
/// A positive offset represents a position below the baseline and
/// a negative offset is above.
///
FLOAT offset;
///
/// Height of the tallest run where the underline applies.
///
FLOAT runHeight;
///
/// Reading direction of the text associated with the underline. This
/// value is used to interpret whether the width value runs horizontally
/// or vertically.
///
DWRITE_READING_DIRECTION readingDirection;
///
/// Flow direction of the text associated with the underline. This value
/// is used to interpret whether the thickness value advances top to
/// bottom, left to right, or right to left.
///
DWRITE_FLOW_DIRECTION flowDirection;
///
/// Locale of the text the underline is being drawn under. Can be
/// pertinent where the locale affects how the underline is drawn.
/// For example, in vertical text, the underline belongs on the
/// left for Chinese but on the right for Japanese.
/// This choice is completely left up to higher levels.
///
__nullterminated WCHAR const* localeName;
///
/// The measuring mode can be useful to the renderer to determine how
/// underlines are rendered, e.g. rounding the thickness to a whole pixel
/// in GDI-compatible modes.
///
DWRITE_MEASURING_MODE measuringMode;
};
///
/// The DWRITE_STRIKETHROUGH structure contains about the size and placement of
/// strickthroughs. All coordinates are in device independent pixels (DIPs).
///
struct DWRITE_STRIKETHROUGH
{
///
/// Width of the strikethrough, measured parallel to the baseline.
///
FLOAT width;
///
/// Thickness of the strikethrough, measured perpendicular to the
/// baseline.
///
FLOAT thickness;
///
/// Offset of the stikethrough from the baseline.
/// A positive offset represents a position below the baseline and
/// a negative offset is above.
///
FLOAT offset;
///
/// Reading direction of the text associated with the strikethrough. This
/// value is used to interpret whether the width value runs horizontally
/// or vertically.
///
DWRITE_READING_DIRECTION readingDirection;
///
/// Flow direction of the text associated with the strikethrough. This
/// value is used to interpret whether the thickness value advances top to
/// bottom, left to right, or right to left.
///
DWRITE_FLOW_DIRECTION flowDirection;
///
/// Locale of the range. Can be pertinent where the locale affects the style.
///
__nullterminated WCHAR const* localeName;
///
/// The measuring mode can be useful to the renderer to determine how
/// underlines are rendered, e.g. rounding the thickness to a whole pixel
/// in GDI-compatible modes.
///
DWRITE_MEASURING_MODE measuringMode;
};
///
/// The DWRITE_LINE_METRICS structure contains information about a formatted
/// line of text.
///
struct DWRITE_LINE_METRICS
{
///
/// The number of total text positions in the line.
/// This includes any trailing whitespace and newline characters.
///
UINT32 length;
///
/// The number of whitespace positions at the end of the line. Newline
/// sequences are considered whitespace.
///
UINT32 trailingWhitespaceLength;
///
/// The number of characters in the newline sequence at the end of the line.
/// If the count is zero, then the line was either wrapped or it is the
/// end of the text.
///
UINT32 newlineLength;
///
/// Height of the line as measured from top to bottom.
///
FLOAT height;
///
/// Distance from the top of the line to its baseline.
///
FLOAT baseline;
///
/// The line is trimmed.
///
BOOL isTrimmed;
};
///
/// The DWRITE_CLUSTER_METRICS structure contains information about a glyph cluster.
///
struct DWRITE_CLUSTER_METRICS
{
///
/// The total advance width of all glyphs in the cluster.
///
FLOAT width;
///
/// The number of text positions in the cluster.
///
UINT16 length;
///
/// Indicate whether line can be broken right after the cluster.
///
UINT16 canWrapLineAfter : 1;
///
/// Indicate whether the cluster corresponds to whitespace character.
///
UINT16 isWhitespace : 1;
///
/// Indicate whether the cluster corresponds to a newline character.
///
UINT16 isNewline : 1;
///
/// Indicate whether the cluster corresponds to soft hyphen character.
///
UINT16 isSoftHyphen : 1;
///
/// Indicate whether the cluster is read from right to left.
///
UINT16 isRightToLeft : 1;
UINT16 padding : 11;
};
///
/// Overall metrics associated with text after layout.
/// All coordinates are in device independent pixels (DIPs).
///
struct DWRITE_TEXT_METRICS
{
///
/// Left-most point of formatted text relative to layout box
/// (excluding any glyph overhang).
///
FLOAT left;
///
/// Top-most point of formatted text relative to layout box
/// (excluding any glyph overhang).
///
FLOAT top;
///
/// The width of the formatted text ignoring trailing whitespace
/// at the end of each line.
///
FLOAT width;
///
/// The width of the formatted text taking into account the
/// trailing whitespace at the end of each line.
///
FLOAT widthIncludingTrailingWhitespace;
///
/// The height of the formatted text. The height of an empty string
/// is determined by the size of the default font's line height.
///
FLOAT height;
///
/// Initial width given to the layout. Depending on whether the text
/// was wrapped or not, it can be either larger or smaller than the
/// text content width.
///
FLOAT layoutWidth;
///
/// Initial height given to the layout. Depending on the length of the
/// text, it may be larger or smaller than the text content height.
///
FLOAT layoutHeight;
///
/// The maximum reordering count of any line of text, used
/// to calculate the most number of hit-testing boxes needed.
/// If the layout has no bidirectional text or no text at all,
/// the minimum level is 1.
///
UINT32 maxBidiReorderingDepth;
///
/// Total number of lines.
///
UINT32 lineCount;
};
///
/// Properties describing the geometric measurement of an
/// application-defined inline object.
///
struct DWRITE_INLINE_OBJECT_METRICS
{
///
/// Width of the inline object.
///
FLOAT width;
///
/// Height of the inline object as measured from top to bottom.
///
FLOAT height;
///
/// Distance from the top of the object to the baseline where it is lined up with the adjacent text.
/// If the baseline is at the bottom, baseline simply equals height.
///
FLOAT baseline;
///
/// Flag indicating whether the object is to be placed upright or alongside the text baseline
/// for vertical text.
///
BOOL supportsSideways;
};
///
/// The DWRITE_OVERHANG_METRICS structure holds how much any visible pixels
/// (in DIPs) overshoot each side of the layout or inline objects.
///
///
/// Positive overhangs indicate that the visible area extends outside the layout
/// box or inline object, while negative values mean there is whitespace inside.
/// The returned values are unaffected by rendering transforms or pixel snapping.
/// Additionally, they may not exactly match final target's pixel bounds after
/// applying grid fitting and hinting.
///
struct DWRITE_OVERHANG_METRICS
{
///
/// The distance from the left-most visible DIP to its left alignment edge.
///
FLOAT left;
///
/// The distance from the top-most visible DIP to its top alignment edge.
///
FLOAT top;
///
/// The distance from the right-most visible DIP to its right alignment edge.
///
FLOAT right;
///
/// The distance from the bottom-most visible DIP to its bottom alignment edge.
///
FLOAT bottom;
};
///
/// Geometry enclosing of text positions.
///
struct DWRITE_HIT_TEST_METRICS
{
///
/// First text position within the geometry.
///
UINT32 textPosition;
///
/// Number of text positions within the geometry.
///
UINT32 length;
///
/// Left position of the top-left coordinate of the geometry.
///
FLOAT left;
///
/// Top position of the top-left coordinate of the geometry.
///
FLOAT top;
///
/// Geometry's width.
///
FLOAT width;
///
/// Geometry's height.
///
FLOAT height;
///
/// Bidi level of text positions enclosed within the geometry.
///
UINT32 bidiLevel;
///
/// Geometry encloses text?
///
BOOL isText;
///
/// Range is trimmed.
///
BOOL isTrimmed;
};
interface IDWriteTextRenderer;
///
/// The IDWriteInlineObject interface wraps an application defined inline graphic,
/// allowing DWrite to query metrics as if it was a glyph inline with the text.
///
interface DWRITE_DECLARE_INTERFACE("8339FDE3-106F-47ab-8373-1C6295EB10B3") IDWriteInlineObject : public IUnknown
{
///
/// The application implemented rendering callback (IDWriteTextRenderer::DrawInlineObject)
/// can use this to draw the inline object without needing to cast or query the object
/// type. The text layout does not call this method directly.
///
/// The context passed to IDWriteTextLayout::Draw.
/// The renderer passed to IDWriteTextLayout::Draw as the object's containing parent.
/// X-coordinate at the top-left corner of the inline object.
/// Y-coordinate at the top-left corner of the inline object.
/// The object should be drawn on its side.
/// The object is in an right-to-left context and should be drawn flipped.
/// The drawing effect set in IDWriteTextLayout::SetDrawingEffect.
///
/// Standard HRESULT error code.
///
STDMETHOD(Draw)(
__maybenull void* clientDrawingContext,
IDWriteTextRenderer* renderer,
FLOAT originX,
FLOAT originY,
BOOL isSideways,
BOOL isRightToLeft,
__maybenull IUnknown* clientDrawingEffect
) PURE;
///
/// TextLayout calls this callback function to get the measurement of the inline object.
///
/// Returned metrics
///
/// Standard HRESULT error code.
///
STDMETHOD(GetMetrics)(
__out DWRITE_INLINE_OBJECT_METRICS* metrics
) PURE;
///
/// TextLayout calls this callback function to get the visible extents (in DIPs) of the inline object.
/// In the case of a simple bitmap, with no padding and no overhang, all the overhangs will
/// simply be zeroes.
///
/// Overshoot of visible extents (in DIPs) outside the object.
///
/// Standard HRESULT error code.
///
///
/// The overhangs should be returned relative to the reported size of the object
/// (DWRITE_INLINE_OBJECT_METRICS::width/height), and should not be baseline
/// adjusted. If you have an image that is actually 100x100 DIPs, but you want it
/// slightly inset (perhaps it has a glow) by 20 DIPs on each side, you would
/// return a width/height of 60x60 and four overhangs of 20 DIPs.
///
STDMETHOD(GetOverhangMetrics)(
__out DWRITE_OVERHANG_METRICS* overhangs
) PURE;
///
/// Layout uses this to determine the line breaking behavior of the inline object
/// amidst the text.
///
/// Line-breaking condition between the object and the content immediately preceding it.
/// Line-breaking condition between the object and the content immediately following it.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetBreakConditions)(
__out DWRITE_BREAK_CONDITION* breakConditionBefore,
__out DWRITE_BREAK_CONDITION* breakConditionAfter
) PURE;
};
///
/// The IDWritePixelSnapping interface defines the pixel snapping properties of a text renderer.
///
interface DWRITE_DECLARE_INTERFACE("eaf3a2da-ecf4-4d24-b644-b34f6842024b") IDWritePixelSnapping : public IUnknown
{
///
/// Determines whether pixel snapping is disabled. The recommended default is FALSE,
/// unless doing animation that requires subpixel vertical placement.
///
/// The context passed to IDWriteTextLayout::Draw.
/// Receives TRUE if pixel snapping is disabled or FALSE if it not.
///
/// Standard HRESULT error code.
///
STDMETHOD(IsPixelSnappingDisabled)(
__maybenull void* clientDrawingContext,
__out BOOL* isDisabled
) PURE;
///
/// Gets the current transform that maps abstract coordinates to DIPs,
/// which may disable pixel snapping upon any rotation or shear.
///
/// The context passed to IDWriteTextLayout::Draw.
/// Receives the transform.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetCurrentTransform)(
__maybenull void* clientDrawingContext,
__out DWRITE_MATRIX* transform
) PURE;
///
/// Gets the number of physical pixels per DIP. A DIP (device-independent pixel) is 1/96 inch,
/// so the pixelsPerDip value is the number of logical pixels per inch divided by 96 (yielding
/// a value of 1 for 96 DPI and 1.25 for 120).
///
/// The context passed to IDWriteTextLayout::Draw.
/// Receives the number of physical pixels per DIP.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetPixelsPerDip)(
__maybenull void* clientDrawingContext,
__out FLOAT* pixelsPerDip
) PURE;
};
///
/// The IDWriteTextLayout interface represents a set of application-defined
/// callbacks that perform rendering of text, inline objects, and decorations
/// such as underlines.
///
interface DWRITE_DECLARE_INTERFACE("ef8a8135-5cc6-45fe-8825-c5a0724eb819") IDWriteTextRenderer : public IDWritePixelSnapping
{
///
/// IDWriteTextLayout::Draw calls this function to instruct the client to
/// render a run of glyphs.
///
/// The context passed to
/// IDWriteTextLayout::Draw.
/// X-coordinate of the baseline.
/// Y-coordinate of the baseline.
/// Specifies measuring method for glyphs in the run.
/// Renderer implementations may choose different rendering modes for given measuring methods,
/// but best results are seen when the rendering mode matches the corresponding measuring mode:
/// 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
///
/// The glyph run to draw.
/// Properties of the characters
/// associated with this run.
/// The drawing effect set in
/// IDWriteTextLayout::SetDrawingEffect.
///
/// Standard HRESULT error code.
///
STDMETHOD(DrawGlyphRun)(
__maybenull void* clientDrawingContext,
FLOAT baselineOriginX,
FLOAT baselineOriginY,
DWRITE_MEASURING_MODE measuringMode,
__in DWRITE_GLYPH_RUN const* glyphRun,
__in DWRITE_GLYPH_RUN_DESCRIPTION const* glyphRunDescription,
__maybenull IUnknown* clientDrawingEffect
) PURE;
///
/// IDWriteTextLayout::Draw calls this function to instruct the client to draw
/// an underline.
///
/// The context passed to
/// IDWriteTextLayout::Draw.
/// X-coordinate of the baseline.
/// Y-coordinate of the baseline.
/// Underline logical information.
/// The drawing effect set in
/// IDWriteTextLayout::SetDrawingEffect.
///
/// Standard HRESULT error code.
///
///
/// A single underline can be broken into multiple calls, depending on
/// how the formatting changes attributes. If font sizes/styles change
/// within an underline, the thickness and offset will be averaged
/// weighted according to characters.
/// To get the correct top coordinate of the underline rect, add underline::offset
/// to the baseline's Y. Otherwise the underline will be immediately under the text.
/// The x coordinate will always be passed as the left side, regardless
/// of text directionality. This simplifies drawing and reduces the
/// problem of round-off that could potentially cause gaps or a double
/// stamped alpha blend. To avoid alpha overlap, round the end points
/// to the nearest device pixel.
///
STDMETHOD(DrawUnderline)(
__maybenull void* clientDrawingContext,
FLOAT baselineOriginX,
FLOAT baselineOriginY,
__in DWRITE_UNDERLINE const* underline,
__maybenull IUnknown* clientDrawingEffect
) PURE;
///
/// IDWriteTextLayout::Draw calls this function to instruct the client to draw
/// a strikethrough.
///
/// The context passed to
/// IDWriteTextLayout::Draw.
/// X-coordinate of the baseline.
/// Y-coordinate of the baseline.
/// Strikethrough logical information.
/// The drawing effect set in
/// IDWriteTextLayout::SetDrawingEffect.
///
/// Standard HRESULT error code.
///
///
/// A single strikethrough can be broken into multiple calls, depending on
/// how the formatting changes attributes. Strikethrough is not averaged
/// across font sizes/styles changes.
/// To get the correct top coordinate of the strikethrough rect,
/// add strikethrough::offset to the baseline's Y.
/// Like underlines, the x coordinate will always be passed as the left side,
/// regardless of text directionality.
///
STDMETHOD(DrawStrikethrough)(
__maybenull void* clientDrawingContext,
FLOAT baselineOriginX,
FLOAT baselineOriginY,
__in DWRITE_STRIKETHROUGH const* strikethrough,
__maybenull IUnknown* clientDrawingEffect
) PURE;
///
/// IDWriteTextLayout::Draw calls this application callback when it needs to
/// draw an inline object.
///
/// The context passed to IDWriteTextLayout::Draw.
/// X-coordinate at the top-left corner of the inline object.
/// Y-coordinate at the top-left corner of the inline object.
/// The object set using IDWriteTextLayout::SetInlineObject.
/// The object should be drawn on its side.
/// The object is in an right-to-left context and should be drawn flipped.
/// The drawing effect set in
/// IDWriteTextLayout::SetDrawingEffect.
///
/// Standard HRESULT error code.
///
///
/// The right-to-left flag is a hint for those cases where it would look
/// strange for the image to be shown normally (like an arrow pointing to
/// right to indicate a submenu).
///
STDMETHOD(DrawInlineObject)(
__maybenull void* clientDrawingContext,
FLOAT originX,
FLOAT originY,
IDWriteInlineObject* inlineObject,
BOOL isSideways,
BOOL isRightToLeft,
__maybenull IUnknown* clientDrawingEffect
) PURE;
};
///
/// The IDWriteTextLayout interface represents a block of text after it has
/// been fully analyzed and formatted.
///
/// All coordinates are in device independent pixels (DIPs).
///
interface DWRITE_DECLARE_INTERFACE("53737037-6d14-410b-9bfe-0b182bb70961") IDWriteTextLayout : public IDWriteTextFormat
{
///
/// Set layout maximum width
///
/// Layout maximum width
///
/// Standard HRESULT error code.
///
STDMETHOD(SetMaxWidth)(
FLOAT maxWidth
) PURE;
///
/// Set layout maximum height
///
/// Layout maximum height
///
/// Standard HRESULT error code.
///
STDMETHOD(SetMaxHeight)(
FLOAT maxHeight
) PURE;
///
/// Set the font collection.
///
/// The font collection to set
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFontCollection)(
IDWriteFontCollection* fontCollection,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set null-terminated font family name.
///
/// Font family name
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFontFamilyName)(
__in_z WCHAR const* fontFamilyName,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set font weight.
///
/// Font weight
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFontWeight)(
DWRITE_FONT_WEIGHT fontWeight,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set font style.
///
/// Font style
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFontStyle)(
DWRITE_FONT_STYLE fontStyle,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set font stretch.
///
/// font stretch
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFontStretch)(
DWRITE_FONT_STRETCH fontStretch,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set font em height.
///
/// Font em height
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetFontSize)(
FLOAT fontSize,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set underline.
///
/// The Boolean flag indicates whether underline takes place
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetUnderline)(
BOOL hasUnderline,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set strikethrough.
///
/// The Boolean flag indicates whether strikethrough takes place
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetStrikethrough)(
BOOL hasStrikethrough,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set application-defined drawing effect.
///
/// Pointer to an application-defined drawing effect.
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
///
/// This drawing effect is associated with the specified range and will be passed back
/// to the application via the callback when the range is drawn at drawing time.
///
STDMETHOD(SetDrawingEffect)(
IUnknown* drawingEffect,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set inline object.
///
/// Pointer to an application-implemented inline object.
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
///
/// This inline object applies to the specified range and will be passed back
/// to the application via the DrawInlineObject callback when the range is drawn.
/// Any text in that range will be suppressed.
///
STDMETHOD(SetInlineObject)(
IDWriteInlineObject* inlineObject,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set font typography features.
///
/// Pointer to font typography setting.
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetTypography)(
IDWriteTypography* typography,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Set locale name.
///
/// Locale name
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetLocaleName)(
__in_z WCHAR const* localeName,
DWRITE_TEXT_RANGE textRange
) PURE;
///
/// Get layout maximum width
///
STDMETHOD_(FLOAT, GetMaxWidth)() PURE;
///
/// Get layout maximum height
///
STDMETHOD_(FLOAT, GetMaxHeight)() PURE;
///
/// Get the font collection where the current position is at.
///
/// The current text position.
/// The current font collection
/// Text range to which this change applies.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontCollection)(
UINT32 currentPosition,
__out IDWriteFontCollection** fontCollection,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the length of the font family name where the current position is at.
///
/// The current text position.
/// Size of the character array in character count not including the terminated NULL character.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontFamilyNameLength)(
UINT32 currentPosition,
__out UINT32* nameLength,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Copy the font family name where the current position is at.
///
/// The current text position.
/// Character array that receives the current font family name
/// Size of the character array in character count including the terminated NULL character.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontFamilyName)(
UINT32 currentPosition,
__out_ecount_z(nameSize) WCHAR* fontFamilyName,
UINT32 nameSize,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the font weight where the current position is at.
///
/// The current text position.
/// The current font weight
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontWeight)(
UINT32 currentPosition,
__out DWRITE_FONT_WEIGHT* fontWeight,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the font style where the current position is at.
///
/// The current text position.
/// The current font style
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontStyle)(
UINT32 currentPosition,
__out DWRITE_FONT_STYLE* fontStyle,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the font stretch where the current position is at.
///
/// The current text position.
/// The current font stretch
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontStretch)(
UINT32 currentPosition,
__out DWRITE_FONT_STRETCH* fontStretch,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the font em height where the current position is at.
///
/// The current text position.
/// The current font em height
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetFontSize)(
UINT32 currentPosition,
__out FLOAT* fontSize,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the underline presence where the current position is at.
///
/// The current text position.
/// The Boolean flag indicates whether text is underlined.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetUnderline)(
UINT32 currentPosition,
__out BOOL* hasUnderline,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the strikethrough presence where the current position is at.
///
/// The current text position.
/// The Boolean flag indicates whether text has strikethrough.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetStrikethrough)(
UINT32 currentPosition,
__out BOOL* hasStrikethrough,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the application-defined drawing effect where the current position is at.
///
/// The current text position.
/// The current application-defined drawing effect.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetDrawingEffect)(
UINT32 currentPosition,
__out IUnknown** drawingEffect,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the inline object at the given position.
///
/// The given text position.
/// The inline object.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetInlineObject)(
UINT32 currentPosition,
__out IDWriteInlineObject** inlineObject,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the typography setting where the current position is at.
///
/// The current text position.
/// The current typography setting.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetTypography)(
UINT32 currentPosition,
__out IDWriteTypography** typography,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the length of the locale name where the current position is at.
///
/// The current text position.
/// Size of the character array in character count not including the terminated NULL character.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLocaleNameLength)(
UINT32 currentPosition,
__out UINT32* nameLength,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Get the locale name where the current position is at.
///
/// The current text position.
/// Character array that receives the current locale name
/// Size of the character array in character count including the terminated NULL character.
/// The position range of the current format.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetLocaleName)(
UINT32 currentPosition,
__out_ecount_z(nameSize) WCHAR* localeName,
UINT32 nameSize,
__out_opt DWRITE_TEXT_RANGE* textRange = NULL
) PURE;
///
/// Initiate drawing of the text.
///
/// An application defined value
/// included in rendering callbacks.
/// The set of application-defined callbacks that do
/// the actual rendering.
/// X-coordinate of the layout's left side.
/// Y-coordinate of the layout's top side.
///
/// Standard HRESULT error code.
///
STDMETHOD(Draw)(
__maybenull void* clientDrawingContext,
IDWriteTextRenderer* renderer,
FLOAT originX,
FLOAT originY
) PURE;
///
/// GetLineMetrics returns properties of each line.
///
/// The array to fill with line information.
/// The maximum size of the lineMetrics array.
/// The actual size of the lineMetrics
/// array that is needed.
///
/// Standard HRESULT error code.
///
///
/// If maxLineCount is not large enough E_NOT_SUFFICIENT_BUFFER,
/// which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER),
/// is returned and *actualLineCount is set to the number of lines
/// needed.
///
STDMETHOD(GetLineMetrics)(
__out_ecount_opt(maxLineCount) DWRITE_LINE_METRICS* lineMetrics,
UINT32 maxLineCount,
__out UINT32* actualLineCount
) PURE;
///
/// GetMetrics retrieves overall metrics for the formatted string.
///
/// The returned metrics.
///
/// Standard HRESULT error code.
///
///
/// Drawing effects like underline and strikethrough do not contribute
/// to the text size, which is essentially the sum of advance widths and
/// line heights. Additionally, visible swashes and other graphic
/// adornments may extend outside the returned width and height.
///
STDMETHOD(GetMetrics)(
__out DWRITE_TEXT_METRICS* textMetrics
) PURE;
///
/// GetOverhangMetrics returns the overhangs (in DIPs) of the layout and all
/// objects contained in it, including text glyphs and inline objects.
///
/// Overshoots of visible extents (in DIPs) outside the layout.
///
/// Standard HRESULT error code.
///
///
/// Any underline and strikethrough do not contribute to the black box
/// determination, since these are actually drawn by the renderer, which
/// is allowed to draw them in any variety of styles.
///
STDMETHOD(GetOverhangMetrics)(
__out DWRITE_OVERHANG_METRICS* overhangs
) PURE;
///
/// Retrieve logical properties and measurement of each cluster.
///
/// The array to fill with cluster information.
/// The maximum size of the clusterMetrics array.
/// The actual size of the clusterMetrics array that is needed.
///
/// Standard HRESULT error code.
///
///
/// If maxClusterCount is not large enough E_NOT_SUFFICIENT_BUFFER,
/// which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER),
/// is returned and *actualClusterCount is set to the number of clusters
/// needed.
///
STDMETHOD(GetClusterMetrics)(
__out_ecount_opt(maxClusterCount) DWRITE_CLUSTER_METRICS* clusterMetrics,
UINT32 maxClusterCount,
__out UINT32* actualClusterCount
) PURE;
///
/// Determines the minimum possible width the layout can be set to without
/// emergency breaking between the characters of whole words.
///
/// Minimum width.
///
/// Standard HRESULT error code.
///
STDMETHOD(DetermineMinWidth)(
__out FLOAT* minWidth
) PURE;
///
/// Given a coordinate (in DIPs) relative to the top-left of the layout box,
/// this returns the corresponding hit-test metrics of the text string where
/// the hit-test has occurred. This is useful for mapping mouse clicks to caret
/// positions. When the given coordinate is outside the text string, the function
/// sets the output value *isInside to false but returns the nearest character
/// position.
///
/// X coordinate to hit-test, relative to the top-left location of the layout box.
/// Y coordinate to hit-test, relative to the top-left location of the layout box.
/// Output flag indicating whether the hit-test location is at the leading or the trailing
/// side of the character. When the output *isInside value is set to false, this value is set according to the output
/// *position value to represent the edge closest to the hit-test location.
/// Output flag indicating whether the hit-test location is inside the text string.
/// When false, the position nearest the text's edge is returned.
/// Output geometry fully enclosing the hit-test location. When the output *isInside value
/// is set to false, this structure represents the geometry enclosing the edge closest to the hit-test location.
///
/// Standard HRESULT error code.
///
STDMETHOD(HitTestPoint)(
FLOAT pointX,
FLOAT pointY,
__out BOOL* isTrailingHit,
__out BOOL* isInside,
__out DWRITE_HIT_TEST_METRICS* hitTestMetrics
) PURE;
///
/// Given a text position and whether the caret is on the leading or trailing
/// edge of that position, this returns the corresponding coordinate (in DIPs)
/// relative to the top-left of the layout box. This is most useful for drawing
/// the caret's current position, but it could also be used to anchor an IME to the
/// typed text or attach a floating menu near the point of interest. It may also be
/// used to programmatically obtain the geometry of a particular text position
/// for UI automation.
///
/// Text position to get the coordinate of.
/// Flag indicating whether the location is of the leading or the trailing side of the specified text position.
/// Output caret X, relative to the top-left of the layout box.
/// Output caret Y, relative to the top-left of the layout box.
/// Output geometry fully enclosing the specified text position.
///
/// Standard HRESULT error code.
///
///
/// When drawing a caret at the returned X,Y, it should should be centered on X
/// and drawn from the Y coordinate down. The height will be the size of the
/// hit-tested text (which can vary in size within a line).
/// Reading direction also affects which side of the character the caret is drawn.
/// However, the returned X coordinate will be correct for either case.
/// You can get a text length back that is larger than a single character.
/// This happens for complex scripts when multiple characters form a single cluster,
/// when diacritics join their base character, or when you test a surrogate pair.
///
STDMETHOD(HitTestTextPosition)(
UINT32 textPosition,
BOOL isTrailingHit,
__out FLOAT* pointX,
__out FLOAT* pointY,
__out DWRITE_HIT_TEST_METRICS* hitTestMetrics
) PURE;
///
/// The application calls this function to get a set of hit-test metrics
/// corresponding to a range of text positions. The main usage for this
/// is to draw highlighted selection of the text string.
///
/// The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to
/// HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER), when the buffer size of
/// hitTestMetrics is too small to hold all the regions calculated by the
/// function. In such situation, the function sets the output value
/// *actualHitTestMetricsCount to the number of geometries calculated.
/// The application is responsible to allocate a new buffer of greater
/// size and call the function again.
///
/// A good value to use as an initial value for maxHitTestMetricsCount may
/// be calculated from the following equation:
/// maxHitTestMetricsCount = lineCount * maxBidiReorderingDepth
///
/// where lineCount is obtained from the value of the output argument
/// *actualLineCount from the function IDWriteTextLayout::GetLineMetrics,
/// and the maxBidiReorderingDepth value from the DWRITE_TEXT_METRICS
/// structure of the output argument *textMetrics from the function
/// IDWriteFactory::CreateTextLayout.
///
/// First text position of the specified range.
/// Number of positions of the specified range.
/// Offset of the X origin (left of the layout box) which is added to each of the hit-test metrics returned.
/// Offset of the Y origin (top of the layout box) which is added to each of the hit-test metrics returned.
/// Pointer to a buffer of the output geometry fully enclosing the specified position range.
/// Maximum number of distinct metrics it could hold in its buffer memory.
/// Actual number of metrics returned or needed.
///
/// Standard HRESULT error code.
///
///
/// There are no gaps in the returned metrics. While there could be visual gaps,
/// depending on bidi ordering, each range is contiguous and reports all the text,
/// including any hidden characters and trimmed text.
/// The height of each returned range will be the same within each line, regardless
/// of how the font sizes vary.
///
STDMETHOD(HitTestTextRange)(
UINT32 textPosition,
UINT32 textLength,
FLOAT originX,
FLOAT originY,
__out_ecount_opt(maxHitTestMetricsCount) DWRITE_HIT_TEST_METRICS* hitTestMetrics,
UINT32 maxHitTestMetricsCount,
__out UINT32* actualHitTestMetricsCount
) PURE;
};
///
/// Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
///
interface DWRITE_DECLARE_INTERFACE("5e5a32a3-8dff-4773-9ff6-0696eab77267") IDWriteBitmapRenderTarget : public IUnknown
{
///
/// Draws a run of glyphs to the bitmap.
///
/// Horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
/// Vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
/// Specifies measuring method for glyphs in the run.
/// 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, and
/// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL for DWRITE_MEASURING_MODE_GDI_NATURAL.
///
/// Structure containing the properties of the glyph run.
/// Object that controls rendering behavior.
/// Specifies the foreground color of the text.
/// Optional rectangle that receives the bounding box (in pixels not DIPs) of all the pixels affected by
/// drawing the glyph run. The black box rectangle may extend beyond the dimensions of the bitmap.
///
/// Standard HRESULT error code.
///
STDMETHOD(DrawGlyphRun)(
FLOAT baselineOriginX,
FLOAT baselineOriginY,
DWRITE_MEASURING_MODE measuringMode,
__in DWRITE_GLYPH_RUN const* glyphRun,
IDWriteRenderingParams* renderingParams,
COLORREF textColor,
__out_opt RECT* blackBoxRect = NULL
) PURE;
///
/// Gets a handle to the memory device context.
///
///
/// Returns the device context handle.
///
///
/// An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle
/// (HBITMAP) by calling GetCurrentObject. An application that wants information about the underlying bitmap, including
/// a pointer to the pixel data, can call GetObject to fill in a DIBSECTION structure. The bitmap is always a 32-bit
/// top-down DIB.
///
STDMETHOD_(HDC, GetMemoryDC)() PURE;
///
/// Gets the number of bitmap pixels per DIP. A DIP (device-independent pixel) is 1/96 inch so this value is the number
/// if pixels per inch divided by 96.
///
///
/// Returns the number of bitmap pixels per DIP.
///
STDMETHOD_(FLOAT, GetPixelsPerDip)() PURE;
///
/// Sets the number of bitmap pixels per DIP. A DIP (device-independent pixel) is 1/96 inch so this value is the number
/// if pixels per inch divided by 96.
///
/// Specifies the number of pixels per DIP.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetPixelsPerDip)(
FLOAT pixelsPerDip
) PURE;
///
/// Gets the transform that maps abstract coordinate to DIPs. By default this is the identity
/// transform. Note that this is unrelated to the world transform of the underlying device
/// context.
///
/// Receives the transform.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetCurrentTransform)(
__out DWRITE_MATRIX* transform
) PURE;
///
/// Sets the transform that maps abstract coordinate to DIPs. This does not affect the world
/// transform of the underlying device context.
///
/// Specifies the new transform. This parameter can be NULL, in which
/// case the identity transform is implied.
///
/// Standard HRESULT error code.
///
STDMETHOD(SetCurrentTransform)(
__in_opt DWRITE_MATRIX const* transform
) PURE;
///
/// Gets the dimensions of the bitmap.
///
/// Receives the size of the bitmap in pixels.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetSize)(
__out SIZE* size
) PURE;
///
/// Resizes the bitmap.
///
/// New bitmap width, in pixels.
/// New bitmap height, in pixels.
///
/// Standard HRESULT error code.
///
STDMETHOD(Resize)(
UINT32 width,
UINT32 height
) PURE;
};
///
/// The GDI interop interface provides interoperability with GDI.
///
interface DWRITE_DECLARE_INTERFACE("1edd9491-9853-4299-898f-6432983b6f3a") IDWriteGdiInterop : public IUnknown
{
///
/// Creates a font object that matches the properties specified by the LOGFONT structure.
///
/// Structure containing a GDI-compatible font description.
/// Receives a newly created font object if successful, or NULL in case of error.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateFontFromLOGFONT)(
__in LOGFONTW const* logFont,
__out IDWriteFont** font
) PURE;
///
/// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font.
///
/// Specifies a font in the system font collection.
/// Structure that receives a GDI-compatible font description.
/// Contains TRUE if the specified font object is part of the system font collection
/// or FALSE otherwise.
///
/// Standard HRESULT error code.
///
STDMETHOD(ConvertFontToLOGFONT)(
IDWriteFont* font,
__out LOGFONTW* logFont,
__out BOOL* isSystemFont
) PURE;
///
/// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font.
///
/// Specifies a font face.
/// Structure that receives a GDI-compatible font description.
///
/// Standard HRESULT error code.
///
STDMETHOD(ConvertFontFaceToLOGFONT)(
IDWriteFontFace* font,
__out LOGFONTW* logFont
) PURE;
///
/// Creates a font face object that corresponds to the currently selected HFONT.
///
/// Handle to a device context into which a font has been selected. It is assumed that the client
/// has already performed font mapping and that the font selected into the DC is the actual font that would be used
/// for rendering glyphs.
/// Contains the newly created font face object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateFontFaceFromHdc)(
HDC hdc,
__out IDWriteFontFace** fontFace
) PURE;
///
/// Creates an object that encapsulates a bitmap and memory DC which can be used for rendering glyphs.
///
/// Optional device context used to create a compatible memory DC.
/// Width of the bitmap.
/// Height of the bitmap.
/// Receives a pointer to the newly created render target.
STDMETHOD(CreateBitmapRenderTarget)(
__in_opt HDC hdc,
UINT32 width,
UINT32 height,
__out IDWriteBitmapRenderTarget** renderTarget
) PURE;
};
///
/// The DWRITE_TEXTURE_TYPE enumeration identifies a type of alpha texture. An alpha texture is a bitmap of alpha values, each
/// representing the darkness (i.e., opacity) of a pixel or subpixel.
///
enum DWRITE_TEXTURE_TYPE
{
///
/// Specifies an alpha texture for aliased text rendering (i.e., bi-level, where each pixel is either fully opaque or fully transparent),
/// with one byte per pixel.
///
DWRITE_TEXTURE_ALIASED_1x1,
///
/// Specifies an alpha texture for ClearType text rendering, with three bytes per pixel in the horizontal dimension and
/// one byte per pixel in the vertical dimension.
///
DWRITE_TEXTURE_CLEARTYPE_3x1
};
///
/// Maximum alpha value in a texture returned by IDWriteGlyphRunAnalysis::CreateAlphaTexture.
///
#define DWRITE_ALPHA_MAX 255
///
/// Interface that encapsulates information used to render a glyph run.
///
interface DWRITE_DECLARE_INTERFACE("7d97dbf7-e085-42d4-81e3-6a883bded118") IDWriteGlyphRunAnalysis : public IUnknown
{
///
/// Gets the bounding rectangle of the physical pixels affected by the glyph run.
///
/// Specifies the type of texture requested. If a bi-level texture is requested, the
/// bounding rectangle includes only bi-level glyphs. Otherwise, the bounding rectangle includes only anti-aliased
/// glyphs.
/// Receives the bounding rectangle, or an empty rectangle if there are no glyphs
/// if the specified type.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetAlphaTextureBounds)(
DWRITE_TEXTURE_TYPE textureType,
__out RECT* textureBounds
) PURE;
///
/// Creates an alpha texture of the specified type.
///
/// Specifies the type of texture requested. If a bi-level texture is requested, the
/// texture contains only bi-level glyphs. Otherwise, the texture contains only anti-aliased glyphs.
/// Specifies the bounding rectangle of the texture, which can be different than
/// the bounding rectangle returned by GetAlphaTextureBounds.
/// Receives the array of alpha values.
/// Size of the alphaValues array. The minimum size depends on the dimensions of the
/// rectangle and the type of texture requested.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateAlphaTexture)(
DWRITE_TEXTURE_TYPE textureType,
__in RECT const* textureBounds,
__out_bcount(bufferSize) BYTE* alphaValues,
UINT32 bufferSize
) PURE;
///
/// Gets properties required for ClearType blending.
///
/// Rendering parameters object. In most cases, the values returned in the output
/// parameters are based on the properties of this object. The exception is if a GDI-compatible rendering mode
/// is specified.
/// Receives the gamma value to use for gamma correction.
/// Receives the enhanced contrast value.
/// Receives the ClearType level.
STDMETHOD(GetAlphaBlendParams)(
IDWriteRenderingParams* renderingParams,
__out FLOAT* blendGamma,
__out FLOAT* blendEnhancedContrast,
__out FLOAT* blendClearTypeLevel
) PURE;
};
///
/// The root factory interface for all DWrite objects.
///
interface DWRITE_DECLARE_INTERFACE("b859ee5a-d838-4b5b-a2e8-1adc7d93db48") IDWriteFactory : public IUnknown
{
///
/// Gets a font collection representing the set of installed fonts.
///
/// Receives a pointer to the system font collection object, or NULL in case of failure.
/// If this parameter is nonzero, the function performs an immediate check for changes to the set of
/// installed fonts. If this parameter is FALSE, the function will still detect changes if the font cache service is running, but
/// there may be some latency. For example, an application might specify TRUE if it has itself just installed a font and wants to
/// be sure the font collection contains that font.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetSystemFontCollection)(
__out IDWriteFontCollection** fontCollection,
BOOL checkForUpdates = FALSE
) PURE;
///
/// Creates a font collection using a custom font collection loader.
///
/// Application-defined font collection loader, which must have been previously
/// registered using RegisterFontCollectionLoader.
/// Key used by the loader to identify a collection of font files.
/// Size in bytes of the collection key.
/// Receives a pointer to the system font collection object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateCustomFontCollection)(
IDWriteFontCollectionLoader* collectionLoader,
__in_bcount(collectionKeySize) void const* collectionKey,
UINT32 collectionKeySize,
__out IDWriteFontCollection** fontCollection
) PURE;
///
/// Registers a custom font collection loader with the factory object.
///
/// Application-defined font collection loader.
///
/// Standard HRESULT error code.
///
STDMETHOD(RegisterFontCollectionLoader)(
IDWriteFontCollectionLoader* fontCollectionLoader
) PURE;
///
/// Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
///
/// Application-defined font collection loader.
///
/// Standard HRESULT error code.
///
STDMETHOD(UnregisterFontCollectionLoader)(
IDWriteFontCollectionLoader* fontCollectionLoader
) PURE;
///
/// CreateFontFileReference creates a font file reference object from a local font file.
///
/// Absolute file path. Subsequent operations on the constructed object may fail
/// if the user provided filePath doesn't correspond to a valid file on the disk.
/// Last modified time of the input file path. If the parameter is omitted,
/// the function will access the font file to obtain its last write time, so the clients are encouraged to specify this value
/// to avoid extra disk access. Subsequent operations on the constructed object may fail
/// if the user provided lastWriteTime doesn't match the file on the disk.
/// Contains newly created font file reference object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateFontFileReference)(
__in_z WCHAR const* filePath,
__in_opt FILETIME const* lastWriteTime,
__out IDWriteFontFile** fontFile
) PURE;
///
/// CreateCustomFontFileReference creates a reference to an application specific font file resource.
/// This function enables an application or a document to use a font without having to install it on the system.
/// The fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.
///
/// Font file reference key that uniquely identifies the font file resource
/// during the lifetime of fontFileLoader.
/// Size of font file reference key in bytes.
/// Font file loader that will be used by the font system to load data from the file identified by
/// fontFileReferenceKey.
/// Contains the newly created font file object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
///
/// This function is provided for cases when an application or a document needs to use a font
/// without having to install it on the system. fontFileReferenceKey has to be unique only in the scope
/// of the fontFileLoader used in this call.
///
STDMETHOD(CreateCustomFontFileReference)(
__in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
UINT32 fontFileReferenceKeySize,
IDWriteFontFileLoader* fontFileLoader,
__out IDWriteFontFile** fontFile
) PURE;
///
/// Creates a font face object.
///
/// The file format of the font face.
/// The number of font files require to represent the font face.
/// Font files representing the font face. Since IDWriteFontFace maintains its own references
/// to the input font file objects, it's OK to release them after this call.
/// 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.
/// Font face simulation flags for algorithmic emboldening and italicization.
/// Contains the newly created font face object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateFontFace)(
DWRITE_FONT_FACE_TYPE fontFaceType,
UINT32 numberOfFiles,
__in_ecount(numberOfFiles) IDWriteFontFile* const* fontFiles,
UINT32 faceIndex,
DWRITE_FONT_SIMULATIONS fontFaceSimulationFlags,
__out IDWriteFontFace** fontFace
) PURE;
///
/// Creates a rendering parameters object with default settings for the primary monitor.
///
/// Holds the newly created rendering parameters object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateRenderingParams)(
__out IDWriteRenderingParams** renderingParams
) PURE;
///
/// Creates a rendering parameters object with default settings for the specified monitor.
///
/// The monitor to read the default values from.
/// Holds the newly created rendering parameters object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateMonitorRenderingParams)(
HMONITOR monitor,
__out IDWriteRenderingParams** renderingParams
) PURE;
///
/// Creates a rendering parameters object with the specified properties.
///
/// The gamma value used for gamma correction, which must be greater than zero and cannot exceed 256.
/// The amount of contrast enhancement, zero or greater.
/// The degree of ClearType level, from 0.0f (no ClearType) to 1.0f (full ClearType).
/// The geometry of a device pixel.
/// Method of rendering glyphs. In most cases, this should be DWRITE_RENDERING_MODE_DEFAULT to automatically use an appropriate mode.
/// Holds the newly created rendering parameters object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateCustomRenderingParams)(
FLOAT gamma,
FLOAT enhancedContrast,
FLOAT clearTypeLevel,
DWRITE_PIXEL_GEOMETRY pixelGeometry,
DWRITE_RENDERING_MODE renderingMode,
__out IDWriteRenderingParams** renderingParams
) PURE;
///
/// Registers a font file loader with DirectWrite.
///
/// Pointer to the implementation of the IDWriteFontFileLoader for a particular file resource type.
///
/// Standard HRESULT error code.
///
///
/// This function registers a font file loader with DirectWrite.
/// Font file loader interface handles loading font file resources of a particular type from a key.
/// The font file loader interface is recommended to be implemented by a singleton object.
/// A given instance can only be registered once.
/// Succeeding attempts will return an error that it has already been registered.
/// IMPORTANT: font file loader implementations must not register themselves with DirectWrite
/// inside their constructors and must not unregister themselves in their destructors, because
/// registration and unregistraton operations increment and decrement the object reference count respectively.
/// Instead, registration and unregistration of font file loaders with DirectWrite should be performed
/// outside of the font file loader implementation as a separate step.
///
STDMETHOD(RegisterFontFileLoader)(
IDWriteFontFileLoader* fontFileLoader
) PURE;
///
/// Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
///
/// Pointer to the file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
///
/// This function will succeed if the user loader is requested to be removed.
/// It will fail if the pointer to the file loader identifies a standard DirectWrite loader,
/// or a loader that is never registered or has already been unregistered.
///
///
/// This function unregisters font file loader callbacks with the DirectWrite font system.
/// The font file loader interface is recommended to be implemented by a singleton object.
/// IMPORTANT: font file loader implementations must not register themselves with DirectWrite
/// inside their constructors and must not unregister themselves in their destructors, because
/// registration and unregistraton operations increment and decrement the object reference count respectively.
/// Instead, registration and unregistration of font file loaders with DirectWrite should be performed
/// outside of the font file loader implementation as a separate step.
///
STDMETHOD(UnregisterFontFileLoader)(
IDWriteFontFileLoader* fontFileLoader
) PURE;
///
/// Create a text format object used for text layout.
///
/// Name of the font family
/// Font collection. NULL indicates the system font collection.
/// Font weight
/// Font style
/// Font stretch
/// Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.
/// Locale name
/// Contains newly created text format object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateTextFormat)(
__in_z WCHAR const* fontFamilyName,
__maybenull IDWriteFontCollection* fontCollection,
DWRITE_FONT_WEIGHT fontWeight,
DWRITE_FONT_STYLE fontStyle,
DWRITE_FONT_STRETCH fontStretch,
FLOAT fontSize,
__in_z WCHAR const* localeName,
__out IDWriteTextFormat** textFormat
) PURE;
///
/// Create a typography object used in conjunction with text format for text layout.
///
/// Contains newly created typography object, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateTypography)(
__out IDWriteTypography** typography
) PURE;
///
/// Create an object used for interoperability with GDI.
///
/// Receives the GDI interop object if successful, or NULL in case of failure.
///
/// Standard HRESULT error code.
///
STDMETHOD(GetGdiInterop)(
__out IDWriteGdiInterop** gdiInterop
) PURE;
///
/// CreateTextLayout takes a string, format, and associated constraints
/// and produces and object representing the fully analyzed
/// and formatted result.
///
/// The string to layout.
/// The length of the string.
/// The format to apply to the string.
/// Width of the layout box.
/// Height of the layout box.
/// The resultant object.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateTextLayout)(
__in_ecount(stringLength) WCHAR const* string,
UINT32 stringLength,
IDWriteTextFormat* textFormat,
FLOAT maxWidth,
FLOAT maxHeight,
__out IDWriteTextLayout** textLayout
) PURE;
///
/// CreateGdiCompatibleTextLayout takes a string, format, and associated constraints
/// and produces and object representing the result formatted for a particular display resolution
/// and measuring method. The resulting text layout should only be used for the intended resolution,
/// and for cases where text scalability is desired, CreateTextLayout should be used instead.
///
/// The string to layout.
/// The length of the string.
/// The format to apply to the string.
/// Width of the layout box.
/// Height of the layout box.
/// Number of physical pixels per DIP. For example, if rendering onto a 96 DPI device then pixelsPerDip
/// is 1. If rendering onto a 120 DPI device then pixelsPerDip is 120/96.
/// Optional transform applied to the glyphs and their positions. This transform is applied after the
/// scaling specified the font size and pixelsPerDip.
///
/// When set to FALSE, instructs the text layout to use the same metrics as GDI aliased text.
/// When set to TRUE, instructs the text layout to use the same metrics as text measured by GDI using a font
/// created with CLEARTYPE_NATURAL_QUALITY.
///
/// The resultant object.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateGdiCompatibleTextLayout)(
__in_ecount(stringLength) WCHAR const* string,
UINT32 stringLength,
IDWriteTextFormat* textFormat,
FLOAT layoutWidth,
FLOAT layoutHeight,
FLOAT pixelsPerDip,
__in_opt DWRITE_MATRIX const* transform,
BOOL useGdiNatural,
__out IDWriteTextLayout** textLayout
) PURE;
///
/// The application may call this function to create an inline object for trimming, using an ellipsis as the omission sign.
/// The ellipsis will be created using the current settings of the format, including base font, style, and any effects.
/// Alternate omission signs can be created by the application by implementing IDWriteInlineObject.
///
/// Text format used as a template for the omission sign.
/// Created omission sign.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateEllipsisTrimmingSign)(
IDWriteTextFormat* textFormat,
__out IDWriteInlineObject** trimmingSign
) PURE;
///
/// Return an interface to perform text analysis with.
///
/// The resultant object.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateTextAnalyzer)(
__out IDWriteTextAnalyzer** textAnalyzer
) PURE;
///
/// Creates a number substitution object using a locale name,
/// substitution method, and whether to ignore user overrides (uses NLS
/// defaults for the given culture instead).
///
/// Method of number substitution to use.
/// Which locale to obtain the digits from.
/// Ignore the user's settings and use the locale defaults
/// Receives a pointer to the newly created object.
STDMETHOD(CreateNumberSubstitution)(
__in DWRITE_NUMBER_SUBSTITUTION_METHOD substitutionMethod,
__in_z WCHAR const* localeName,
__in BOOL ignoreUserOverride,
__out IDWriteNumberSubstitution** numberSubstitution
) PURE;
///
/// Creates a glyph run analysis object, which encapsulates information
/// used to render a glyph run.
///
/// Structure specifying the properties of the glyph run.
/// Number of physical pixels per DIP. For example, if rendering onto a 96 DPI bitmap then pixelsPerDip
/// is 1. If rendering onto a 120 DPI bitmap then pixelsPerDip is 120/96.
/// Optional transform applied to the glyphs and their positions. This transform is applied after the
/// scaling specified the emSize and pixelsPerDip.
/// Specifies the rendering mode, which must be one of the raster rendering modes (i.e., not default
/// and not outline).
/// Specifies the method to measure glyphs.
/// Horizontal position of the baseline origin, in DIPs.
/// Vertical position of the baseline origin, in DIPs.
/// Receives a pointer to the newly created object.
///
/// Standard HRESULT error code.
///
STDMETHOD(CreateGlyphRunAnalysis)(
__in DWRITE_GLYPH_RUN const* glyphRun,
FLOAT pixelsPerDip,
__in_opt DWRITE_MATRIX const* transform,
DWRITE_RENDERING_MODE renderingMode,
DWRITE_MEASURING_MODE measuringMode,
FLOAT baselineOriginX,
FLOAT baselineOriginY,
__out IDWriteGlyphRunAnalysis** glyphRunAnalysis
) PURE;
}; // interface IDWriteFactory
///
/// Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
///
/// Identifies whether the factory object will be shared or isolated.
/// Identifies the DirectWrite factory interface, such as __uuidof(IDWriteFactory).
/// Receives the DirectWrite factory object.
///
/// Standard HRESULT error code.
///
///
/// Obtains DirectWrite factory object that is used for subsequent creation of individual DirectWrite classes.
/// DirectWrite factory contains internal state such as font loader registration and cached font data.
/// In most cases it is recommended to use the shared factory object, because it allows multiple components
/// that use DirectWrite to share internal DirectWrite state and reduce memory usage.
/// However, there are cases when it is desirable to reduce the impact of a component,
/// such as a plug-in from an untrusted source, on the rest of the process by sandboxing and isolating it
/// from the rest of the process components. In such cases, it is recommended to use an isolated factory for the sandboxed
/// component.
///
EXTERN_C HRESULT DWRITE_EXPORT DWriteCreateFactory(
__in DWRITE_FACTORY_TYPE factoryType,
__in REFIID iid,
__out IUnknown **factory
);
// Macros used to define DirectWrite error codes.
#define FACILITY_DWRITE 0x898
#define DWRITE_ERR_BASE 0x5000
#define MAKE_DWRITE_HR(severity, code) MAKE_HRESULT(severity, FACILITY_DWRITE, (DWRITE_ERR_BASE + code))
#define MAKE_DWRITE_HR_ERR(code) MAKE_DWRITE_HR(SEVERITY_ERROR, code)
///
/// Indicates an error in an input file such as a font file.
///
#define DWRITE_E_FILEFORMAT MAKE_DWRITE_HR_ERR(0x000)
///
/// Indicates an error originating in DirectWrite code, which is not expected to occur but is safe to recover from.
///
#define DWRITE_E_UNEXPECTED MAKE_DWRITE_HR_ERR(0x001)
///
/// Indicates the specified font does not exist.
///
#define DWRITE_E_NOFONT MAKE_DWRITE_HR_ERR(0x002)
///
/// A font file could not be opened because the file, directory, network location, drive, or other storage
/// location does not exist or is unavailable.
///
#define DWRITE_E_FILENOTFOUND MAKE_DWRITE_HR_ERR(0x003)
///
/// A font file exists but could not be opened due to access denied, sharing violation, or similar error.
///
#define DWRITE_E_FILEACCESS MAKE_DWRITE_HR_ERR(0x004)
///
/// A font collection is obsolete due to changes in the system.
///
#define DWRITE_E_FONTCOLLECTIONOBSOLETE MAKE_DWRITE_HR_ERR(0x005)
///
/// The given interface is already registered.
///
#define DWRITE_E_ALREADYREGISTERED MAKE_DWRITE_HR_ERR(0x006)
#endif /* DWRITE_H_INCLUDED */